@makerkit/workers-outbox 0.0.0-stage → 0.0.2

package/dist/drizzle.mjs

@@ -0,0 +1,166 @@
+import { a as REASONED_TERMINAL_STATUSES, i as JOB_STATUSES, n as ATTEMPT_TRIGGERS, o as TERMINAL_STATUSES, r as CLAIMABLE_STATUSES, t as ATTEMPT_OUTCOMES } from "./status-BZhIWoE0.mjs";
+import { r as sqlLiteralList, t as MIN_SERVER_VERSION_NUM } from "./migrations-CX7O2Lcq.mjs";
+import { n as readOutboxCatalog, t as queryRows } from "./catalog-G6w4wb_w.mjs";
+import { sql } from "drizzle-orm";
+import { bigint, check, foreignKey, getTableConfig, index, integer, jsonb, pgSchema, primaryKey, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+// src/drizzle/schema.ts
+/** Source of truth for the tables; the `/sql` DDL is pinned to it by a parity test. */
+const outboxSchema = pgSchema("outbox");
+const timestamptz = (name) => timestamp(name, {
+	precision: 3,
+	withTimezone: true
+});
+const list = (values) => sql.raw(sqlLiteralList(values));
+const outboxJob = outboxSchema.table("job", {
+	id: uuid("id").primaryKey(),
+	kind: text("kind").notNull(),
+	dedupeKey: text("dedupe_key").notNull(),
+	payload: jsonb("payload").notNull(),
+	status: text("status").$type().notNull().default("pending"),
+	tenantKey: text("tenant_key"),
+	correlationId: text("correlation_id"),
+	metadata: jsonb("metadata").$type().notNull().default({}),
+	availableAt: timestamptz("available_at").notNull().defaultNow(),
+	nextAttemptAt: timestamptz("next_attempt_at"),
+	leaseToken: uuid("lease_token"),
+	leasedUntil: timestamptz("leased_until"),
+	startedAttempts: integer("started_attempts").notNull().default(0),
+	finishedAttempts: integer("finished_attempts").notNull().default(0),
+	spentAttempts: integer("spent_attempts").notNull().default(0),
+	codeStreak: integer("code_streak").notNull().default(0),
+	stickyCode: text("sticky_code"),
+	minVersionMs: bigint("min_version_ms", { mode: "number" }),
+	lastErrorCode: text("last_error_code"),
+	lastErrorMessage: text("last_error_message"),
+	terminalReason: text("terminal_reason"),
+	createdAt: timestamptz("created_at").notNull().defaultNow(),
+	updatedAt: timestamptz("updated_at").notNull().defaultNow(),
+	finishedAt: timestamptz("finished_at"),
+	nudgeSentAt: timestamptz("nudge_sent_at"),
+	nudgeAttempts: integer("nudge_attempts").notNull().default(0),
+	lastNudgeError: text("last_nudge_error"),
+	orderingKey: text("ordering_key"),
+	seq: bigint("seq", { mode: "number" }).notNull().generatedAlwaysAsIdentity()
+}, (t) => [
+	uniqueIndex("job_tenant_dedupe_key_unique").on(sql`COALESCE(${t.tenantKey}, '')`, t.dedupeKey),
+	check("job_status_check", sql`${t.status} IN (${list(JOB_STATUSES)})`),
+	check("job_retrying_requires_next_attempt_at", sql`${t.status} <> 'retrying' OR ${t.nextAttemptAt} IS NOT NULL`),
+	check("job_processing_iff_leased", sql`(${t.status} = 'processing') = (${t.leaseToken} IS NOT NULL AND ${t.leasedUntil} IS NOT NULL)`),
+	check("job_attempt_counters", sql`${t.finishedAttempts} >= 0 AND ${t.finishedAttempts} <= ${t.startedAttempts} AND ${t.spentAttempts} >= 0 AND ${t.spentAttempts} <= ${t.finishedAttempts} AND ${t.codeStreak} >= 0`),
+	check("job_terminal_iff_finished_at", sql`(${t.status} IN (${list(TERMINAL_STATUSES)})) = (${t.finishedAt} IS NOT NULL)`),
+	check("job_terminal_reason", sql`(${t.status} IN (${list(REASONED_TERMINAL_STATUSES)})) = (${t.terminalReason} IS NOT NULL)`),
+	index("job_claim_due_idx").on(sql`COALESCE(${t.nextAttemptAt}, ${t.availableAt})`, t.createdAt, t.id).where(sql`${t.status} IN (${list(CLAIMABLE_STATUSES)})`),
+	index("job_pending_kind_idx").on(t.kind, t.availableAt, t.createdAt).where(sql`${t.status} = 'pending'`),
+	index("job_retrying_kind_idx").on(t.kind, t.nextAttemptAt, t.createdAt).where(sql`${t.status} = 'retrying'`),
+	index("job_lease_expiry_idx").on(t.leasedUntil).where(sql`${t.status} = 'processing'`),
+	index("job_retention_idx").on(t.status, t.finishedAt).where(sql`${t.status} IN (${list(TERMINAL_STATUSES)})`),
+	index("job_tenant_key_idx").on(t.tenantKey).where(sql`${t.tenantKey} IS NOT NULL`),
+	index("job_correlation_id_idx").on(t.correlationId).where(sql`${t.correlationId} IS NOT NULL`),
+	index("job_status_created_idx").on(t.status, t.createdAt, t.id)
+]);
+const outboxAttempt = outboxSchema.table("attempt", {
+	jobId: uuid("job_id").notNull(),
+	attemptNo: integer("attempt_no").notNull(),
+	kind: text("kind").notNull(),
+	leaseToken: uuid("lease_token").notNull(),
+	trigger: text("trigger").$type().notNull(),
+	startedAt: timestamptz("started_at").notNull(),
+	finishedAt: timestamptz("finished_at"),
+	outcome: text("outcome").$type(),
+	code: text("code"),
+	message: text("message"),
+	durationMs: integer("duration_ms")
+}, (t) => [
+	primaryKey({
+		name: "attempt_pkey",
+		columns: [t.jobId, t.attemptNo]
+	}),
+	foreignKey({
+		name: "attempt_job_id_fkey",
+		columns: [t.jobId],
+		foreignColumns: [outboxJob.id]
+	}).onDelete("cascade"),
+	check("attempt_trigger_check", sql`${t.trigger} IN (${list(ATTEMPT_TRIGGERS)})`),
+	check("attempt_outcome_check", sql`${t.outcome} IS NULL OR ${t.outcome} IN (${list(ATTEMPT_OUTCOMES)})`),
+	check("attempt_finished_iff_outcome", sql`(${t.outcome} IS NULL) = (${t.finishedAt} IS NULL)`),
+	index("attempt_finished_at_idx").on(t.finishedAt).where(sql`${t.finishedAt} IS NOT NULL`)
+]);
+// src/drizzle/verify-schema.ts
+const OUTBOX_TABLES = [outboxJob, outboxAttempt];
+/** Empty = matches. Compares columns and names, not index/CHECK bodies; extra objects aren't drift. */
+async function verifyOutboxSchema(db) {
+	const [version] = await queryRows(db, sql`SELECT current_setting('server_version_num') AS server_version_num, now() AS read_at`);
+	const actual = Number(version?.server_version_num);
+	const drift = actual < 17e4 ? [{
+		type: "unsupported_version",
+		minimum: MIN_SERVER_VERSION_NUM,
+		actual
+	}] : [];
+	const catalog = await readOutboxCatalog(db);
+	return [...drift, ...OUTBOX_TABLES.flatMap((table) => diffTable(table, catalog))];
+}
+function diffTable(table, catalog) {
+	const config = getTableConfig(table);
+	const tableName = config.name;
+	const liveColumns = catalog.columns.filter((column) => column.table === tableName);
+	if (liveColumns.length === 0) return [{
+		type: "missing_table",
+		table: tableName
+	}];
+	const drift = [];
+	for (const column of config.columns) {
+		const live = liveColumns.find((candidate) => candidate.column === column.name);
+		if (!live) {
+			drift.push({
+				type: "missing_column",
+				table: tableName,
+				column: column.name
+			});
+			continue;
+		}
+		const expected = describeColumn(column.getSQLType(), column.notNull);
+		const actual = describeColumn(live.type, live.notNull);
+		if (expected !== actual) drift.push({
+			type: "column_mismatch",
+			table: tableName,
+			column: column.name,
+			expected,
+			actual
+		});
+	}
+	const liveConstraints = new Set(catalog.constraints.filter((c) => c.table === tableName).map((c) => c.name));
+	for (const name of expectedConstraintNames(table)) if (!liveConstraints.has(name)) drift.push({
+		type: "missing_constraint",
+		table: tableName,
+		name
+	});
+	const liveIndexes = new Map(catalog.indexes.filter((i) => i.table === tableName).map((i) => [i.name, i]));
+	for (const name of config.indexes.flatMap((index) => index.config.name ?? [])) {
+		const live = liveIndexes.get(name);
+		if (!live) drift.push({
+			type: "missing_index",
+			table: tableName,
+			name
+		});
+		else if (!live.valid) drift.push({
+			type: "invalid_index",
+			table: tableName,
+			name
+		});
+	}
+	return drift;
+}
+function expectedConstraintNames(table) {
+	const config = getTableConfig(table);
+	return [
+		...config.columns.some((column) => column.primary) ? [`${config.name}_pkey`] : [],
+		...config.primaryKeys.map((pk) => pk.getName()),
+		...config.uniqueConstraints.flatMap((u) => u.getName() ?? []),
+		...config.foreignKeys.map((fk) => fk.getName()),
+		...config.checks.map((c) => c.name)
+	];
+}
+function describeColumn(type, notNull) {
+	return `${type.replace(/\s+\(/g, "(").toLowerCase()}${notNull ? " not null" : ""}`;
+}
+export { outboxAttempt, outboxJob, outboxSchema, verifyOutboxSchema };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { $ as cancel, A as DeadReason, G as JobDefinitionInput, H as AnyJob, J as defineJob, K as JobDeps, M as AttemptOutcome, N as AttemptTrigger, P as JobStatus, Q as HandlerOutcome, U as JobContext, W as JobDefinition, X as RetryPolicy, Y as defineJobFor, Z as RetryPolicyInput, a as EnqueueResult, b as TransitionHook, d as StrictOutbox, et as fail, f as StrictScopedEnqueue, g as OutboxEvent, h as EventSink, i as EnqueueRequest, j as Transition, l as RefusedEnqueueResult, m as createOutbox, n as DepsOf, nt as retry, o as Outbox, p as TenantScope, q as defaultClassify, r as EnqueueRefusedError, rt as MessageRedactor, s as OutboxOptions, t as AcceptedEnqueueResult, tt as ok, u as ScopedEnqueue, x as TransitionHookEvent, y as RunReport } from "./create-outbox-C4vdn6Dr.mjs";
+import { i as QueueSender, n as LaneConnection, r as OutboxDb, t as Clock } from "./types-ClomUJ_8.mjs";
+export { type AcceptedEnqueueResult, type AnyJob, type AttemptOutcome, type AttemptTrigger, type Clock, type DeadReason, type DepsOf, EnqueueRefusedError, type EnqueueRequest, type EnqueueResult, type EventSink, type HandlerOutcome, type JobContext, type JobDefinition, type JobDefinitionInput, type JobDeps, type JobStatus, type LaneConnection, type MessageRedactor, type Outbox, type OutboxDb, type OutboxEvent, type OutboxOptions, type QueueSender, type RefusedEnqueueResult, type RetryPolicy, type RetryPolicyInput, type RunReport, type ScopedEnqueue, type StrictOutbox, type StrictScopedEnqueue, type TenantScope, type Transition, type TransitionHook, type TransitionHookEvent, cancel, createOutbox, defaultClassify, defineJob, defineJobFor, fail, ok, retry };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { t as EnqueueRefusedError, p as cancel, r as createOutbox, u as defaultClassify, d as defineJob, f as defineJobFor, m as fail, h as ok, g as retry } from "./create-outbox-BTMmdvLs.mjs";

package/dist/inspect.d.mts

@@ -0,0 +1,2 @@
+import { B as KindBacklog, C as countBacklog, D as listJobs, E as getJob, F as BacklogReport, I as BacklogSeverity, L as BacklogThresholds, O as DEFAULT_INSPECT_STATEMENT_TIMEOUT_MS, R as DEFAULT_BACKLOG_AGED_MS, S as aggregateAttemptOutcomes, T as findJobsByCorrelationId, V as evaluateBacklog, k as InspectBound, w as countJobs, z as DEFAULT_BACKLOG_THRESHOLDS } from "./create-outbox-C4vdn6Dr.mjs";
+export { type BacklogReport, type BacklogSeverity, type BacklogThresholds, DEFAULT_BACKLOG_AGED_MS, DEFAULT_BACKLOG_THRESHOLDS, DEFAULT_INSPECT_STATEMENT_TIMEOUT_MS, type InspectBound, type KindBacklog, aggregateAttemptOutcomes, countBacklog, countJobs, evaluateBacklog, findJobsByCorrelationId, getJob, listJobs };

package/dist/inspect.mjs

@@ -0,0 +1,41 @@
+import { S as listJobs$1, d as countBacklog$1, f as countJobs$1, g as getJob$1, h as findJobsByCorrelationId$1, n as DEFAULT_BACKLOG_THRESHOLDS, o as aggregateAttemptOutcomes$1, r as evaluateBacklog, t as DEFAULT_BACKLOG_AGED_MS } from "./backlog-Bd62tjCT.mjs";
+import { t as queryRows } from "./catalog-G6w4wb_w.mjs";
+import { sql } from "drizzle-orm";
+// src/inspect/bounded.ts
+/**
+* Default bound on one inspection read. A long scan holds back the xmin horizon, so autovacuum
+* can't clean the queue table's dead tuples while it runs.
+*/
+const DEFAULT_INSPECT_STATEMENT_TIMEOUT_MS = 3e4;
+const MAX_STATEMENT_TIMEOUT_MS = 2147483647;
+const canTransact = (db) => typeof db.transaction === "function";
+/**
+* Runs `read` in its own transaction (a savepoint inside the caller's) with a transaction-local
+* `statement_timeout`, restored before returning, so nothing leaks into a caller's transaction or,
+* on Hyperdrive, into another client's session. A runner without `transaction` runs unbounded.
+*/
+async function boundedRead(db, bound, read) {
+	const timeoutMs = bound?.statementTimeoutMs ?? 3e4;
+	if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_STATEMENT_TIMEOUT_MS) throw new Error(`inspect: statementTimeoutMs must be an integer in [0, ${MAX_STATEMENT_TIMEOUT_MS}], got ${timeoutMs}`);
+	if (timeoutMs === 0 || !canTransact(db)) return read(db);
+	return db.transaction(async (tx) => {
+		const [previous] = await queryRows(tx, sql`SELECT current_setting('statement_timeout') AS previous,
+                 set_config('statement_timeout', ${String(timeoutMs)}, true) AS applied`);
+		const result = await read(tx);
+		await tx.execute(sql`SELECT set_config('statement_timeout', ${previous?.previous ?? "0"}, true)`);
+		return result;
+	});
+}
+// src/inspect/index.ts
+/** Each read runs under a transaction-local `statement_timeout` (default 30 s; see `InspectBound`). */
+const bounded = (read) => (db, input) => {
+	const { statementTimeoutMs, ...rest } = input;
+	return boundedRead(db, { statementTimeoutMs }, (tx) => read(tx, rest));
+};
+const aggregateAttemptOutcomes = bounded(aggregateAttemptOutcomes$1);
+const countBacklog = bounded(countBacklog$1);
+const countJobs = bounded(countJobs$1);
+const findJobsByCorrelationId = bounded(findJobsByCorrelationId$1);
+const getJob = bounded(getJob$1);
+const listJobs = bounded(listJobs$1);
+export { DEFAULT_BACKLOG_AGED_MS, DEFAULT_BACKLOG_THRESHOLDS, DEFAULT_INSPECT_STATEMENT_TIMEOUT_MS, aggregateAttemptOutcomes, countBacklog, countJobs, evaluateBacklog, findJobsByCorrelationId, getJob, listJobs };

package/dist/migrations-CX7O2Lcq.mjs

@@ -0,0 +1,98 @@
+import { a as REASONED_TERMINAL_STATUSES, i as JOB_STATUSES, n as ATTEMPT_TRIGGERS, o as TERMINAL_STATUSES, r as CLAIMABLE_STATUSES, t as ATTEMPT_OUTCOMES } from "./status-BZhIWoE0.mjs";
+// src/sql/sql-list.ts
+const IDENTIFIER_LIKE = /^[a-z_]+$/;
+function sqlLiteralList(values) {
+	for (const value of values) if (!IDENTIFIER_LIKE.test(value)) throw new Error(`sqlLiteralList: refusing non-constant value ${JSON.stringify(value)}`);
+	return values.map((value) => `'${value}'`).join(", ");
+}
+// src/sql/migrations.ts
+const jobStatuses = sqlLiteralList(JOB_STATUSES);
+const claimable = sqlLiteralList(CLAIMABLE_STATUSES);
+const terminal = sqlLiteralList(TERMINAL_STATUSES);
+const reasonedTerminal = sqlLiteralList(REASONED_TERMINAL_STATUSES);
+/** PostgreSQL 17: settlement relies on `transaction_timeout`. */
+const MIN_SERVER_VERSION_NUM = 17e4;
+/** Fails setup on an older server, before any object is created. */
+function serverVersionGuard(minimum) {
+	return `DO $guard$
+BEGIN
+  IF current_setting('server_version_num')::int < ${minimum} THEN
+    RAISE EXCEPTION 'workers-outbox requires PostgreSQL ${Math.floor(minimum / 1e4)} or newer; this server is %', current_setting('server_version')
+      USING ERRCODE = 'feature_not_supported';
+  END IF;
+END
+$guard$`;
+}
+const OUTBOX_MIGRATIONS = [{
+	id: "0001_init",
+	statements: [
+		serverVersionGuard(MIN_SERVER_VERSION_NUM),
+		`CREATE SCHEMA "outbox"`,
+		`CREATE TABLE "outbox"."job" (
+  "id" uuid PRIMARY KEY,
+  "kind" text NOT NULL,
+  "dedupe_key" text NOT NULL,
+  "payload" jsonb NOT NULL,
+  "status" text DEFAULT 'pending' NOT NULL,
+  "tenant_key" text,
+  "correlation_id" text,
+  "metadata" jsonb DEFAULT '{}' NOT NULL,
+  "available_at" timestamp(3) with time zone DEFAULT now() NOT NULL,
+  "next_attempt_at" timestamp(3) with time zone,
+  "lease_token" uuid,
+  "leased_until" timestamp(3) with time zone,
+  "started_attempts" integer DEFAULT 0 NOT NULL,
+  "finished_attempts" integer DEFAULT 0 NOT NULL,
+  "spent_attempts" integer DEFAULT 0 NOT NULL,
+  "code_streak" integer DEFAULT 0 NOT NULL,
+  "sticky_code" text,
+  "min_version_ms" bigint,
+  "last_error_code" text,
+  "last_error_message" text,
+  "terminal_reason" text,
+  "created_at" timestamp(3) with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp(3) with time zone DEFAULT now() NOT NULL,
+  "finished_at" timestamp(3) with time zone,
+  "nudge_sent_at" timestamp(3) with time zone,
+  "nudge_attempts" integer DEFAULT 0 NOT NULL,
+  "last_nudge_error" text,
+  "ordering_key" text,
+  "seq" bigint GENERATED ALWAYS AS IDENTITY NOT NULL,
+  CONSTRAINT "job_status_check" CHECK ("status" IN (${jobStatuses})),
+  CONSTRAINT "job_retrying_requires_next_attempt_at" CHECK ("status" <> 'retrying' OR "next_attempt_at" IS NOT NULL),
+  CONSTRAINT "job_processing_iff_leased" CHECK (("status" = 'processing') = ("lease_token" IS NOT NULL AND "leased_until" IS NOT NULL)),
+  CONSTRAINT "job_attempt_counters" CHECK ("finished_attempts" >= 0 AND "finished_attempts" <= "started_attempts" AND "spent_attempts" >= 0 AND "spent_attempts" <= "finished_attempts" AND "code_streak" >= 0),
+  CONSTRAINT "job_terminal_iff_finished_at" CHECK (("status" IN (${terminal})) = ("finished_at" IS NOT NULL)),
+  CONSTRAINT "job_terminal_reason" CHECK (("status" IN (${reasonedTerminal})) = ("terminal_reason" IS NOT NULL))
+)`,
+		`CREATE TABLE "outbox"."attempt" (
+  "job_id" uuid NOT NULL,
+  "attempt_no" integer NOT NULL,
+  "kind" text NOT NULL,
+  "lease_token" uuid NOT NULL,
+  "trigger" text NOT NULL,
+  "started_at" timestamp(3) with time zone NOT NULL,
+  "finished_at" timestamp(3) with time zone,
+  "outcome" text,
+  "code" text,
+  "message" text,
+  "duration_ms" integer,
+  CONSTRAINT "attempt_pkey" PRIMARY KEY ("job_id", "attempt_no"),
+  CONSTRAINT "attempt_job_id_fkey" FOREIGN KEY ("job_id") REFERENCES "outbox"."job" ("id") ON DELETE CASCADE,
+  CONSTRAINT "attempt_trigger_check" CHECK ("trigger" IN (${sqlLiteralList(ATTEMPT_TRIGGERS)})),
+  CONSTRAINT "attempt_outcome_check" CHECK ("outcome" IS NULL OR "outcome" IN (${sqlLiteralList(ATTEMPT_OUTCOMES)})),
+  CONSTRAINT "attempt_finished_iff_outcome" CHECK (("outcome" IS NULL) = ("finished_at" IS NULL))
+)`,
+		`CREATE UNIQUE INDEX "job_tenant_dedupe_key_unique" ON "outbox"."job" (COALESCE("tenant_key", ''), "dedupe_key")`,
+		`CREATE INDEX "job_claim_due_idx" ON "outbox"."job" (COALESCE("next_attempt_at", "available_at"), "created_at", "id") WHERE "status" IN (${claimable})`,
+		`CREATE INDEX "job_pending_kind_idx" ON "outbox"."job" ("kind", "available_at", "created_at") WHERE "status" = 'pending'`,
+		`CREATE INDEX "job_retrying_kind_idx" ON "outbox"."job" ("kind", "next_attempt_at", "created_at") WHERE "status" = 'retrying'`,
+		`CREATE INDEX "job_lease_expiry_idx" ON "outbox"."job" ("leased_until") WHERE "status" = 'processing'`,
+		`CREATE INDEX "job_retention_idx" ON "outbox"."job" ("status", "finished_at") WHERE "status" IN (${terminal})`,
+		`CREATE INDEX "job_tenant_key_idx" ON "outbox"."job" ("tenant_key") WHERE "tenant_key" IS NOT NULL`,
+		`CREATE INDEX "job_correlation_id_idx" ON "outbox"."job" ("correlation_id") WHERE "correlation_id" IS NOT NULL`,
+		`CREATE INDEX "job_status_created_idx" ON "outbox"."job" ("status", "created_at", "id")`,
+		`CREATE INDEX "attempt_finished_at_idx" ON "outbox"."attempt" ("finished_at") WHERE "finished_at" IS NOT NULL`
+	]
+}];
+export { OUTBOX_MIGRATIONS as n, sqlLiteralList as r, MIN_SERVER_VERSION_NUM as t };

package/dist/pg.d.mts

@@ -0,0 +1,30 @@
+import { n as LaneConnection } from "./types-ClomUJ_8.mjs";
+import { ClientConfig, Pool } from "pg";
+export interface PgConnectorOptions {
+  /**
+   * Errors a session raises outside a query, e.g. the FATAL `transaction_timeout` sends when it
+   * ends a settlement past its deadline. They are always caught (node-pg would otherwise crash the
+   * process); this only observes them. The outbox has already seen the failed query.
+   */
+  onError?: (error: Error) => void;
+}
+export interface PgClientConnectorOptions extends PgConnectorOptions {
+  /** Bound on opening one session. Default 10 s. */
+  connectionTimeoutMs?: number;
+}
+/**
+ * A fresh `pg.Client` per lane — the shape Hyperdrive expects, since it pools upstream:
+ * `createPgConnector(env.OUTBOX_DB.connectionString)`. `close()` and `destroy()` both end the
+ * session (a client is never reused); a query still running server-side runs until it next
+ * writes to the closed socket, which the settlement's own `transaction_timeout` bounds.
+ */
+export declare function createPgConnector(config: string | ClientConfig, options?: PgClientConnectorOptions): () => Promise<LaneConnection>;
+/**
+ * Checks clients out of a pool you own (Node, or a long-lived Worker-side pool). Set the pool's
+ * `connectionTimeoutMillis`: the outbox bounds its own wait, but a checkout that never returns
+ * still holds a pool slot. Also attach `pool.on('error', …)`: node-pg re-emits a returned
+ * client's late errors (a FATAL after release) on the pool, which crashes the process unlistened.
+ * `close()` returns the client; `destroy()` discards it
+ * (`release(true)`), so a session abandoned mid-query is never reused.
+ */
+export declare function createPgPoolConnector(pool: Pool, options?: PgConnectorOptions): () => Promise<LaneConnection>;

package/dist/pg.mjs

@@ -0,0 +1,76 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Client } from "pg";
+// src/pg/index.ts
+const DEFAULT_CONNECTION_TIMEOUT_MS = 1e4;
+/**
+* A fresh `pg.Client` per lane — the shape Hyperdrive expects, since it pools upstream:
+* `createPgConnector(env.OUTBOX_DB.connectionString)`. `close()` and `destroy()` both end the
+* session (a client is never reused); a query still running server-side runs until it next
+* writes to the closed socket, which the settlement's own `transaction_timeout` bounds.
+*/
+function createPgConnector(config, options = {}) {
+	const base = typeof config === "string" ? { connectionString: config } : config;
+	const connectionTimeoutMillis = base.connectionTimeoutMillis ?? options.connectionTimeoutMs ?? DEFAULT_CONNECTION_TIMEOUT_MS;
+	return async () => {
+		const client = new Client({
+			...base,
+			connectionTimeoutMillis
+		});
+		let broken = false;
+		client.on("error", (error) => {
+			broken = true;
+			options.onError?.(error);
+		});
+		try {
+			await client.connect();
+		} catch (error) {
+			await client.end().catch(() => void 0);
+			throw error;
+		}
+		const end = once(() => client.end());
+		return {
+			db: drizzleOf(client),
+			close: end,
+			destroy: end,
+			isBroken: () => broken
+		};
+	};
+}
+/**
+* Checks clients out of a pool you own (Node, or a long-lived Worker-side pool). Set the pool's
+* `connectionTimeoutMillis`: the outbox bounds its own wait, but a checkout that never returns
+* still holds a pool slot. Also attach `pool.on('error', …)`: node-pg re-emits a returned
+* client's late errors (a FATAL after release) on the pool, which crashes the process unlistened.
+* `close()` returns the client; `destroy()` discards it
+* (`release(true)`), so a session abandoned mid-query is never reused.
+*/
+function createPgPoolConnector(pool, options = {}) {
+	return async () => {
+		const client = await pool.connect();
+		let broken = false;
+		const onError = (error) => {
+			broken = true;
+			options.onError?.(error);
+		};
+		client.on("error", onError);
+		const release = (destroy) => once(async () => {
+			client.off("error", onError);
+			client.release(destroy);
+		});
+		let ended;
+		const close = release(false);
+		const destroy = release(true);
+		return {
+			db: drizzleOf(client),
+			close: () => ended ??= broken ? destroy() : close(),
+			destroy: () => ended ??= destroy(),
+			isBroken: () => broken
+		};
+	};
+}
+const drizzleOf = (client) => drizzle({ client });
+function once(fn) {
+	let done;
+	return () => done ??= fn().catch(() => void 0);
+}
+export { createPgConnector, createPgPoolConnector };

package/dist/sql.d.mts

@@ -0,0 +1,7 @@
+/** Append-only: never edit a shipped migration. */
+interface OutboxMigration {
+  readonly id: string;
+  readonly statements: readonly string[];
+}
+export declare const OUTBOX_MIGRATIONS: readonly OutboxMigration[];
+export type { OutboxMigration };

package/dist/sql.mjs

@@ -0,0 +1 @@
+export { n as OUTBOX_MIGRATIONS } from "./migrations-CX7O2Lcq.mjs";

package/dist/status-BZhIWoE0.mjs

@@ -0,0 +1,30 @@
+// src/core/status.ts
+const JOB_STATUSES = [
+	"pending",
+	"processing",
+	"retrying",
+	"succeeded",
+	"dead",
+	"cancelled"
+];
+const CLAIMABLE_STATUSES = ["pending", "retrying"];
+const TERMINAL_STATUSES = [
+	"succeeded",
+	"dead",
+	"cancelled"
+];
+const REASONED_TERMINAL_STATUSES = ["dead", "cancelled"];
+const ATTEMPT_TRIGGERS = [
+	"nudge",
+	"sweep",
+	"drain"
+];
+const ATTEMPT_OUTCOMES = [
+	"succeeded",
+	"retry",
+	"failed",
+	"cancelled",
+	"timeout",
+	"lease_expired"
+];
+export { REASONED_TERMINAL_STATUSES as a, JOB_STATUSES as i, ATTEMPT_TRIGGERS as n, TERMINAL_STATUSES as o, CLAIMABLE_STATUSES as r, ATTEMPT_OUTCOMES as t };

package/dist/testing.d.mts

@@ -0,0 +1,49 @@
+import { n as LaneConnection, t as Clock } from "./types-ClomUJ_8.mjs";
+import { o as Outbox, v as OutcomeTally } from "./create-outbox-C4vdn6Dr.mjs";
+import { t as SqlRunner } from "./catalog-DzvOuOHQ.mjs";
+import { PGlite } from "@electric-sql/pglite";
+/**
+ * An in-memory pglite with the outbox schema applied. pglite is one session: it can't reproduce multi-connection races such as SKIP LOCKED contention.
+ */
+export declare function createOutboxTestDatabase(): Promise<{
+  db: import("drizzle-orm/pglite").PgliteDatabase<import("drizzle-orm").EmptyRelations> & {
+    $client: PGlite & (Record<string, never> | {
+      [x: string]: never;
+    });
+  };
+  client: PGlite & (Record<string, never> | {
+    [x: string]: never;
+  });
+  /** Pass as `createOutbox({ connect })`. */
+  connect: () => Promise<LaneConnection>;
+  reset: () => Promise<void>;
+  close: () => Promise<void>;
+}>;
+type OutboxTestDatabase = Awaited<ReturnType<typeof createOutboxTestDatabase>>;
+interface TestClock extends Clock {
+  /** Moves time forward; the database sees it too (`dbNow`), so due checks follow. */
+  advance(ms: number): void;
+  current(): Date;
+}
+/**
+ * A frozen clock for tests: pass it to `createOutbox({ clock })` and to `runUntilIdle`. Sleeps
+ * resolve at once; the runtime still bounds every wait in real time, so a frozen clock can't hang.
+ */
+export declare function createTestClock(start?: Date): TestClock;
+interface RunUntilIdleOptions {
+  /**
+   * With a test clock (the one the outbox was created with), time skips ahead to the next retry,
+   * delayed job or expired lease until nothing is left. Without one, only jobs due now run.
+   */
+  clock?: TestClock;
+  /** Reads the next due instant; required with `clock`. */
+  db?: SqlRunner;
+  /** Throws past this many rounds, so an always-retrying job can't hang a test. Default 100. */
+  maxRounds?: number;
+}
+interface IdleReport extends OutcomeTally {
+  rounds: number;
+}
+/** Runs every job this outbox can run, then returns the totals. */
+export declare function runUntilIdle(outbox: Outbox, options?: RunUntilIdleOptions): Promise<IdleReport>;
+export type { IdleReport, OutboxTestDatabase, RunUntilIdleOptions, TestClock };

package/dist/testing.mjs

@@ -0,0 +1,97 @@
+import { n as OUTBOX_MIGRATIONS } from "./migrations-CX7O2Lcq.mjs";
+import { t as queryRows } from "./catalog-G6w4wb_w.mjs";
+import { n as RUNTIME } from "./create-outbox-BTMmdvLs.mjs";
+import { sql } from "drizzle-orm";
+import { PGlite } from "@electric-sql/pglite";
+import { drizzle } from "drizzle-orm/pglite";
+// src/testing/create-outbox-test-database.ts
+/**
+* An in-memory pglite with the outbox schema applied. pglite is one session: it can't reproduce multi-connection races such as SKIP LOCKED contention.
+*/
+async function createOutboxTestDatabase() {
+	const client = await PGlite.create();
+	for (const migration of OUTBOX_MIGRATIONS) for (const statement of migration.statements) await client.exec(statement);
+	const db = drizzle({ client });
+	const lane = {
+		db,
+		close: async () => void 0,
+		destroy: async () => void 0
+	};
+	return {
+		db,
+		client,
+		/** Pass as `createOutbox({ connect })`. */
+		connect: async () => lane,
+		reset: async () => {
+			await db.execute(sql`TRUNCATE "outbox"."job" CASCADE`);
+		},
+		close: () => client.close()
+	};
+}
+// src/testing/test-clock.ts
+/**
+* A frozen clock for tests: pass it to `createOutbox({ clock })` and to `runUntilIdle`. Sleeps
+* resolve at once; the runtime still bounds every wait in real time, so a frozen clock can't hang.
+*/
+function createTestClock(start = /* @__PURE__ */ new Date()) {
+	let current = new Date(start.getTime());
+	return {
+		dbNow: () => current,
+		nowMs: () => current.getTime(),
+		sleep: async () => void 0,
+		advance: (ms) => {
+			current = new Date(current.getTime() + ms);
+		},
+		current: () => current
+	};
+}
+// src/testing/run-until-idle.ts
+const TALLY_KEYS = [
+	"claimed",
+	"succeeded",
+	"retrying",
+	"dead",
+	"cancelled",
+	"leaseLost",
+	"settleFailed"
+];
+const BUDGET = {
+	maxJobs: 1e4,
+	deadlineMs: 6e5
+};
+/** Runs every job this outbox can run, then returns the totals. */
+async function runUntilIdle(outbox, options = {}) {
+	const { clock, db, maxRounds = 100 } = options;
+	if (clock && !db) throw new Error("runUntilIdle: pass `db` with `clock`, to find the next due job");
+	const runtime = outbox[RUNTIME];
+	const totals = {
+		rounds: 0,
+		...Object.fromEntries(TALLY_KEYS.map((k) => [k, 0]))
+	};
+	const add = (report) => {
+		for (const key of TALLY_KEYS) totals[key] += report[key];
+	};
+	for (;;) {
+		if (totals.rounds >= maxRounds) throw new Error(`runUntilIdle: still busy after ${maxRounds} rounds (${JSON.stringify(totals)})`);
+		totals.rounds++;
+		const drained = await runtime.drain(BUDGET, "drain");
+		add(drained);
+		if (drained.claimed > 0) continue;
+		if (!clock || !db) return totals;
+		const recovered = await runtime.recover(BUDGET.maxJobs);
+		add(recovered);
+		if (TALLY_KEYS.some((key) => recovered[key] > 0)) continue;
+		const next = await nextWakeAt(db);
+		if (next === null || next <= clock.nowMs()) return totals;
+		clock.advance(next - clock.nowMs());
+	}
+}
+async function nextWakeAt(db) {
+	const [row] = await queryRows(db, sql`SELECT LEAST(
+          (SELECT min(COALESCE(next_attempt_at, available_at)) FROM "outbox"."job"
+            WHERE status IN ('pending', 'retrying')),
+          (SELECT min(leased_until) FROM "outbox"."job" WHERE status = 'processing')
+        ) AS at, now() AS read_at`);
+	return row?.at == null ? null : new Date(row.at).getTime();
+}
+export { createOutboxTestDatabase, createTestClock, runUntilIdle };

package/dist/types-ClomUJ_8.d.mts

@@ -0,0 +1,33 @@
+import { t as SqlRunner } from "./catalog-DzvOuOHQ.mjs";
+interface OutboxDb extends SqlRunner {
+  transaction<T>(fn: (tx: OutboxDb) => Promise<T>): Promise<T>;
+}
+/** One client per lane per invocation: lanes never share a Hyperdrive session. */
+interface LaneConnection {
+  db: OutboxDb;
+  /** Returns a healthy client (e.g. `client.release()`). */
+  close(): Promise<void>;
+  /**
+   * Discards the session: it must never be reused (e.g. `client.release(true)`, `client.end()`).
+   * Called for a runaway or timed-out lane, before its replacement is acquired, so a one-client
+   * pool can still reconnect. Must be idempotent, and make a later `close()` a no-op.
+   */
+  destroy(): Promise<void>;
+  /**
+   * Optional: true once the session is known dead (e.g. its socket errored while idle). The lane
+   * is then replaced before its next claim or settlement instead of failing a round trip first.
+   */
+  isBroken?(): boolean;
+}
+interface QueueSender {
+  send(body: unknown, options?: {
+    delaySeconds?: number;
+  }): Promise<unknown>;
+}
+interface Clock {
+  /** `null` = the database's own `now()`. */
+  dbNow(): Date | null;
+  nowMs(): number;
+  sleep(ms: number): Promise<void>;
+}
+export { QueueSender as i, LaneConnection as n, OutboxDb as r, Clock as t };