cairnq 0.4.0 → 0.6.0

package/README.md

@@ -66,8 +66,9 @@ Opt-in: every API still accepts a plain name string (cross-language callers use
 
 ```ts
 const worker = Worker.sqlite("tasks.db", {
-  concurrency: 4,
-  retryBackoffMs: 1_000,   // doubles per attempt, capped by retryBackoffMaxMs (30s); 0 disables
+  concurrency: 4,          // handler calls at once; use maxInFlightBytes to bound memory
+  retryBackoffMs: 1_000,   // window doubles per attempt, capped at retryBackoffMaxMs (30s),
+                           // jittered over its upper half; 0 disables
   onError: (err, info) => log.warn({ err, ...info }), // claims/writes the loop survived
 });
 

package/dist/_protocol/migrations/postgres/0006_claim_name_index.sql

@@ -0,0 +1,25 @@
+-- Serves the per-name claim: claim_one_name.sql and claim_one_queue_one_name.sql,
+-- which a worker uses to draw a separate quota for each task name that sizes
+-- itself (a `batch`, or its own concurrency). See "Batch delivery" in PROTOCOL.md.
+--
+-- cairnq_tasks_claim_idx does not cover it: `name` is not in that index, so a
+-- name filter is a residual applied while walking the queue in claim order. The
+-- cost lands hardest on a name with *nothing* queued — the claim walks every
+-- claimable row in the queue looking for `limit` matches and finds none — and a
+-- worker makes one such draw per registered name, per poll, inside the claim's
+-- transaction, holding its FOR UPDATE row locks for the whole of it.
+--
+-- Both indexes are needed. `name` sits before the ORDER BY columns here, so this
+-- one can only be read in claim order when `name` is an equality — exactly the
+-- per-name draws. A claim with no name filter, or an array-valued one, still
+-- reads cairnq_tasks_claim_idx and is unaffected.
+--
+-- NOT built CONCURRENTLY: migrations run inside a transaction (see the runner's
+-- `lock table cairnq_migrations`), and CREATE INDEX CONCURRENTLY cannot. On an
+-- existing large cairnq_tasks this takes a write lock for the build. Deploying
+-- into a busy database is the case to watch; build it by hand with CONCURRENTLY
+-- first if that matters, and this statement then becomes a no-op.
+create index if not exists cairnq_tasks_claim_name_idx
+    on cairnq_tasks (queue, status, name, priority desc, created_at_ms);
+
+update cairnq_meta set value = '6' where key = 'schema_version';

package/dist/_protocol/migrations/sqlite/0006_claim_name_index.sql

@@ -0,0 +1,26 @@
+-- Serves the per-name claim: claim_one_name.sql and claim_one_queue_one_name.sql,
+-- which a worker uses to draw a separate quota for each task name that sizes
+-- itself (a `batch`, or its own concurrency). See "Batch delivery" in PROTOCOL.md.
+--
+-- cairnq_tasks_claim_idx does not cover it: `name` is not in that index, so a
+-- name filter is a residual applied while walking the queue in claim order. The
+-- cost lands hardest on a name with *nothing* queued — the claim walks every
+-- claimable row in the queue looking for `limit` matches and finds none — and a
+-- worker makes one such draw per registered name, per poll, inside the claim's
+-- write transaction. Measured on a 20k backlog: 1116us for an empty name's draw
+-- against cairnq_tasks_claim_idx, 8.8us against this one.
+--
+-- Both indexes are needed. `name` sits before the ORDER BY columns here, so this
+-- one can only be read in claim order when `name` is an equality — exactly the
+-- per-name draws. A claim with no name filter, or a list-valued one, still reads
+-- cairnq_tasks_claim_idx and is unaffected (measured flat at ~13-16us either way).
+--
+-- The equality is what makes it usable: `name in (select value from json_each(?))`
+-- does NOT reach this index even for a single-element list — SQLite builds a
+-- bloom filter over the subquery and falls back to cairnq_tasks_claim_idx
+-- (measured 1446us, i.e. no improvement at all). That is why the per-name
+-- statements exist as separate files rather than the shared one being reused.
+create index if not exists cairnq_tasks_claim_name_idx
+    on cairnq_tasks (queue, status, name, priority desc, created_at_ms);
+
+update cairnq_meta set value = '6' where key = 'schema_version';

package/dist/_protocol/sql/postgres/claim_one_name.sql

@@ -0,0 +1,37 @@
+-- claim, for a caller drawing exactly ONE task name (Postgres dialect).
+-- Byte-for-byte claim.sql except that the name filter is an equality on :name
+-- instead of `= any(:names)` — a drift-guard test asserts precisely that, so
+-- treat claim.sql as the source and re-derive this file when it changes.
+--
+-- It exists so the draw can reach cairnq_tasks_claim_name_idx, whose leading
+-- columns are (queue, status, name): an array-valued name filter cannot be read
+-- in claim order against it, so the name falls back to a residual on
+-- cairnq_tasks_claim_idx and a draw for a name with nothing queued scans the
+-- whole claimable backlog — inside the transaction, holding its row locks. See
+-- migration 0006.
+--
+-- Used for the per-name quotas a worker draws for names that size themselves —
+-- a `batch`, or their own concurrency. See "Batch delivery" in PROTOCOL.md.
+-- params: queues (text[]), name, worker_id, lease_ms, limit
+update cairnq_tasks t
+set
+    status = 'running',
+    worker_id = :worker_id,
+    lease_until_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint + :lease_ms,
+    attempt = attempt + 1,
+    updated_at_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint
+from (
+    select id from cairnq_tasks
+    where status = 'queued'
+      and queue = any(:queues::text[])
+      and name = :name
+      and run_at_ms <= (extract(epoch from clock_timestamp()) * 1000)::bigint
+    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
+    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- the id's random half decides, stably but not in submit order.
+    order by priority desc, created_at_ms asc, id asc
+    limit :limit
+    for update skip locked
+) sel
+where t.id = sel.id
+returning t.*;

package/dist/_protocol/sql/postgres/claim_one_queue_one_name.sql

@@ -0,0 +1,34 @@
+-- claim, for a caller watching ONE queue and drawing ONE task name (Postgres
+-- dialect) — the common shape for a batched worker. Byte-for-byte claim.sql
+-- except that both the queue and the name filters are equalities; a drift-guard
+-- test asserts precisely that, so treat claim.sql as the source and re-derive
+-- this file when it changes.
+--
+-- It is the combination of claim_one_queue.sql's queue equality and
+-- claim_one_name.sql's name equality, and each is there for the reason that file
+-- gives. Together they pin both leading columns of cairnq_tasks_claim_name_idx,
+-- so the draw is an index scan in claim order that stops at :limit rows however
+-- deep the backlog is.
+-- params: queue, name, worker_id, lease_ms, limit
+update cairnq_tasks t
+set
+    status = 'running',
+    worker_id = :worker_id,
+    lease_until_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint + :lease_ms,
+    attempt = attempt + 1,
+    updated_at_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint
+from (
+    select id from cairnq_tasks
+    where status = 'queued'
+      and queue = :queue
+      and name = :name
+      and run_at_ms <= (extract(epoch from clock_timestamp()) * 1000)::bigint
+    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
+    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- the id's random half decides, stably but not in submit order.
+    order by priority desc, created_at_ms asc, id asc
+    limit :limit
+    for update skip locked
+) sel
+where t.id = sel.id
+returning t.*;

package/dist/_protocol/sql/postgres/heartbeat_batch.sql

@@ -0,0 +1,24 @@
+-- Extend the lease on several tasks at once (Postgres dialect) — the heartbeat
+-- for batch delivery. Ownership-checked per row, exactly as heartbeat.sql: a task
+-- whose lease this worker no longer holds simply does not come back, so the
+-- caller learns which ones it lost by which ids are absent from the result rather
+-- than by an error. One statement per beat replaces one round trip per leased
+-- task, which for a 256-task batch is the difference between one write and 256.
+--
+-- Returns only what the beat needs, unlike heartbeat.sql's `returning *`: the
+-- singular statement hands its row to the caller as `ctx.heartbeat()`'s public
+-- return value, while this one's rows never leave the worker — they answer "still
+-- mine?" (presence) and "cancelled?" (the one column). Whole rows here would pull
+-- every payload back on every beat: 256 tasks * 4KB is a megabyte re-read every
+-- lease/3 for the life of the call, and a JSON parse per row to discard it.
+--
+-- New lease (now + :lease_ms) and time come from the DB clock.
+-- params: ids (text[]), worker_id, lease_ms
+update cairnq_tasks
+set lease_until_ms = (extract(epoch from now()) * 1000)::bigint + :lease_ms,
+    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+where id = any(:ids::text[])
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > (extract(epoch from now()) * 1000)::bigint
+returning id, cancel_requested_at_ms;

package/dist/_protocol/sql/postgres/queue_depth.sql

@@ -0,0 +1,22 @@
+-- How many more tasks fit in one queue under :max_depth. Read-only.
+--
+-- Returns headroom, not depth: a producer needs "may I enqueue, and how many
+-- more" — and bounding the scan at :max_depth is what keeps this affordable.
+-- COUNT over the whole backlog would read every queued row, so the cost of
+-- asking would grow with exactly the pile-up the caller is trying to stop.
+-- Wrapped as a LIMIT subquery it reads at most :max_depth index entries off
+-- cairnq_tasks_claim_idx (queue, status leading), and headroom saturates at 0
+-- once the queue is full — which is all a gate needs to know.
+--
+-- Counts 'queued' only. A running task already has a worker and is bounded by
+-- that worker's concurrency; the backlog worth pushing back on is the work
+-- nobody has picked up. Delayed tasks (run_at_ms in the future) count: they are
+-- queued work that will run, and excluding them would let an unbounded pile of
+-- them through the gate.
+-- params: queue, max_depth
+select :max_depth - count(*) as headroom
+from (
+    select 1 from cairnq_tasks
+    where queue = :queue and status = 'queued'
+    limit :max_depth
+) probe;

package/dist/_protocol/sql/sqlite/claim_one_name.sql

@@ -0,0 +1,36 @@
+-- claim, for a caller drawing exactly ONE task name. Byte-for-byte claim.sql
+-- except that the name filter is an equality on :name instead of an IN over
+-- :names — a drift-guard test asserts precisely that, so treat claim.sql as the
+-- source and re-derive this file when it changes.
+--
+-- It exists because `name in (select value from json_each(:names))` cannot reach
+-- cairnq_tasks_claim_name_idx, even for a single-element list: SQLite builds a
+-- bloom filter over the subquery and falls back to cairnq_tasks_claim_idx, where
+-- the name is a residual and a draw for a name with nothing queued walks the
+-- whole claimable backlog. Measured on a 20k backlog: 1446us for the json_each
+-- form, 8.8us for this one. See migration 0006.
+--
+-- Used for the per-name quotas a worker draws for names that size themselves —
+-- a `batch`, or their own concurrency. See "Batch delivery" in PROTOCOL.md.
+-- params: queues (JSON array text), name, now_ms, worker_id, lease_until_ms,
+--         limit
+update cairnq_tasks
+set
+    status = 'running',
+    worker_id = :worker_id,
+    lease_until_ms = :lease_until_ms,
+    attempt = attempt + 1,
+    updated_at_ms = :now_ms
+where id in (
+    select id from cairnq_tasks
+    where status = 'queued'
+      and queue in (select value from json_each(:queues))
+      and name = :name
+      and run_at_ms <= :now_ms
+    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
+    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- the id's random half decides, stably but not in submit order.
+    order by priority desc, created_at_ms asc, id asc
+    limit :limit
+)
+returning *;

package/dist/_protocol/sql/sqlite/claim_one_queue_one_name.sql

@@ -0,0 +1,31 @@
+-- claim, for a caller watching ONE queue and drawing ONE task name — the common
+-- shape for a batched worker. Byte-for-byte claim.sql except that both the queue
+-- and the name filters are equalities; a drift-guard test asserts precisely that,
+-- so treat claim.sql as the source and re-derive this file when it changes.
+--
+-- It is the combination of claim_one_queue.sql's queue equality and
+-- claim_one_name.sql's name equality, and each is there for the reason that file
+-- gives. Together they let cairnq_tasks_claim_name_idx be read in claim order
+-- with both leading columns pinned, so the draw is a seek that terminates at
+-- :limit rows however deep the backlog is.
+-- params: queue, name, now_ms, worker_id, lease_until_ms, limit
+update cairnq_tasks
+set
+    status = 'running',
+    worker_id = :worker_id,
+    lease_until_ms = :lease_until_ms,
+    attempt = attempt + 1,
+    updated_at_ms = :now_ms
+where id in (
+    select id from cairnq_tasks
+    where status = 'queued'
+      and queue = :queue
+      and name = :name
+      and run_at_ms <= :now_ms
+    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
+    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- the id's random half decides, stably but not in submit order.
+    order by priority desc, created_at_ms asc, id asc
+    limit :limit
+)
+returning *;

package/dist/_protocol/sql/sqlite/heartbeat_batch.sql

@@ -0,0 +1,29 @@
+-- Extend the lease on several tasks at once — the heartbeat for batch delivery.
+-- Ownership-checked per row, exactly as heartbeat.sql: a task whose lease this
+-- worker no longer holds simply does not come back, so the caller learns which
+-- ones it lost by which ids are absent from the result rather than by an error.
+-- One statement per beat is the point: a batch handler holding 256 leases would
+-- otherwise write 256 rows every heartbeat interval, which on SQLite means 256
+-- turns of the single write lock for work nobody is waiting on.
+--
+-- Returns only what the beat needs, unlike heartbeat.sql's `returning *`: the
+-- singular statement hands its row to the caller as `ctx.heartbeat()`'s public
+-- return value, while this one's rows never leave the worker — they answer "still
+-- mine?" (presence) and "cancelled?" (the one column). Whole rows here would pull
+-- every payload back on every beat: 256 tasks * 4KB is a megabyte re-read every
+-- lease/3 for the life of the call, and a JSON parse per row to discard it.
+-- Unlike heartbeat.sql, this one's plan depends on statistics: json_each() hides
+-- the id list's length, so without sqlite_stat1 the planner drives the update off
+-- cairnq_tasks_status_idx and walks every 'running' row in the database per beat
+-- instead of doing primary-key lookups. Both SDKs ANALYZE on open and revisit
+-- once a minute per connection (see "Planner statistics" in PROTOCOL.md), so this
+-- is a warm-up window rather than a standing cost — but the statement it replaced
+-- had no such dependency, which is why it is called out here.
+-- params: ids (JSON array text), worker_id, now_ms, lease_until_ms
+update cairnq_tasks
+set lease_until_ms = :lease_until_ms, updated_at_ms = :now_ms
+where id in (select value from json_each(:ids))
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > :now_ms
+returning id, cancel_requested_at_ms;

package/dist/_protocol/sql/sqlite/queue_depth.sql

@@ -0,0 +1,26 @@
+-- How many more tasks fit in one queue under :max_depth. Read-only.
+--
+-- Returns headroom, not depth: a producer needs "may I enqueue, and how many
+-- more" — and bounding the scan at :max_depth is what keeps this affordable.
+-- COUNT over the whole backlog would read every queued row, so the cost of
+-- asking would grow with exactly the pile-up the caller is trying to stop.
+-- Wrapped as a LIMIT subquery it reads at most :max_depth index entries off
+-- cairnq_tasks_claim_idx (queue, status leading), and headroom saturates at 0
+-- once the queue is full — which is all a gate needs to know.
+--
+-- Counts 'queued' only. A running task already has a worker and is bounded by
+-- that worker's concurrency; the backlog worth pushing back on is the work
+-- nobody has picked up. Delayed tasks (run_at_ms in the future) count: they are
+-- queued work that will run, and excluding them would let an unbounded pile of
+-- them through the gate.
+--
+-- Read-only, and it must stay that way: isWriteStatement/_is_write_statement
+-- route a non-select into the group commit, which would put a gate probe behind
+-- SQLite's write lock — the opposite of what a backpressure check is for.
+-- params: queue, max_depth
+select :max_depth - count(*) as headroom
+from (
+    select 1 from cairnq_tasks
+    where queue = :queue and status = 'queued'
+    limit :max_depth
+) probe;

package/dist/backoff.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Retry backoff, in its own module because two callers need it.
+ *
+ * The worker computes it when a handler's failure ends an attempt; TaskContext
+ * computes it when a handler fails one task of a batch itself. Keeping it in
+ * worker.ts would make context.ts import the module that imports it.
+ */
+export declare const DEFAULT_RETRY_BACKOFF_MS = 1000;
+export declare const DEFAULT_RETRY_BACKOFF_MAX_MS = 30000;
+/**
+ * Exponential backoff with equal jitter: the window doubles per attempt up to
+ * `maxMs`, and the delay lands uniformly in its upper half, `[w/2, w)`.
+ *
+ * The jitter is what keeps a fleet from retrying in lockstep. Failures align
+ * when the downstream fails fast enough that a whole concurrency batch raises
+ * at once (connection refused, DNS gone), and capped exponential backoff then
+ * *preserves* that alignment — once every task sits at `maxMs`, they all retry
+ * on the same beat forever. Spreading over half the window breaks it; keeping
+ * the lower half as a floor means jitter never shortens the wait to less than
+ * half of what plain exponential backoff would have asked for.
+ *
+ * `rand` is injected so tests can pin an exact delay.
+ */
+export declare function retryDelayMs(attempt: number, baseMs: number, maxMs: number, rand?: () => number): number;
+/**
+ * The delay a `fail` write should carry. Not just the backoff: a permanent
+ * failure is never re-run, so it always delays 0. Both settlement paths — the
+ * worker's and a handler's `ctx.fail` — go through this, so they cannot end up
+ * backing off differently.
+ */
+export declare function failDelayMs(attempt: number, retryable: boolean, baseMs: number, maxMs: number, rand?: () => number): number;

package/dist/backoff.js

@@ -0,0 +1,40 @@
+/**
+ * Retry backoff, in its own module because two callers need it.
+ *
+ * The worker computes it when a handler's failure ends an attempt; TaskContext
+ * computes it when a handler fails one task of a batch itself. Keeping it in
+ * worker.ts would make context.ts import the module that imports it.
+ */
+export const DEFAULT_RETRY_BACKOFF_MS = 1_000;
+export const DEFAULT_RETRY_BACKOFF_MAX_MS = 30_000;
+/**
+ * Exponential backoff with equal jitter: the window doubles per attempt up to
+ * `maxMs`, and the delay lands uniformly in its upper half, `[w/2, w)`.
+ *
+ * The jitter is what keeps a fleet from retrying in lockstep. Failures align
+ * when the downstream fails fast enough that a whole concurrency batch raises
+ * at once (connection refused, DNS gone), and capped exponential backoff then
+ * *preserves* that alignment — once every task sits at `maxMs`, they all retry
+ * on the same beat forever. Spreading over half the window breaks it; keeping
+ * the lower half as a floor means jitter never shortens the wait to less than
+ * half of what plain exponential backoff would have asked for.
+ *
+ * `rand` is injected so tests can pin an exact delay.
+ */
+export function retryDelayMs(attempt, baseMs, maxMs, rand = Math.random) {
+    if (baseMs <= 0)
+        return 0;
+    const exponent = Math.max(0, attempt - 1);
+    const window = Math.min(maxMs, baseMs * 2 ** exponent);
+    const floor = Math.floor(window / 2);
+    return floor + Math.floor(rand() * (window - floor));
+}
+/**
+ * The delay a `fail` write should carry. Not just the backoff: a permanent
+ * failure is never re-run, so it always delays 0. Both settlement paths — the
+ * worker's and a handler's `ctx.fail` — go through this, so they cannot end up
+ * backing off differently.
+ */
+export function failDelayMs(attempt, retryable, baseMs, maxMs, rand = Math.random) {
+    return retryable ? retryDelayMs(attempt, baseMs, maxMs, rand) : 0;
+}

package/dist/backpressure.d.ts

@@ -0,0 +1,59 @@
+import type { TaskStore } from "./store/base.js";
+/** Per-queue depth limits. A number applies one limit to every queue; a record
+ * gates only the queues it names and leaves the rest unbounded. */
+export type QueueDepthLimit = number | Record<string, number>;
+export interface BackpressureOptions {
+    /** Queued tasks a queue may hold before `submit` blocks. */
+    maxQueueDepth: QueueDepthLimit;
+    /** How long a blocked submit waits before raising QueueFull. Default 600_000. */
+    maxQueueWaitMs?: number;
+    /** First backoff between depth probes; doubles to a 5s ceiling. Default 250. */
+    queuePollIntervalMs?: number;
+}
+/**
+ * Blocks `submit` while a queue is at its depth limit.
+ *
+ * Without one of these a producer that outruns its workers is only bounded by
+ * disk: the backlog grows, every task's queue wait grows with it, and the
+ * failure is a database that filled up rather than a producer that slowed down.
+ * A queue is the wrong place to buffer an overload — pushing back on the
+ * producer is the point.
+ *
+ * **A soft limit under several producers.** The check is a read followed by a
+ * write that other producers can interleave with, and each holds its own grant,
+ * so N producers can overshoot the limit by up to (N-1) * MAX_GRANT tasks. Made
+ * exact it would need the depth check inside insert_task's transaction, which
+ * puts an unbounded-scan predicate on the hot path of every submit and turns
+ * concurrent submits into lock contention — a steep price for a bound whose
+ * whole purpose is approximate. Size the limit for the pushback you want, not as
+ * a capacity assertion.
+ */
+export declare class QueueDepthGate {
+    private readonly store;
+    /** Remaining grant per queue: submits allowed before the next probe. */
+    private readonly headroom;
+    /** In-flight probe per queue, so concurrent submits share one read rather
+     * than each issuing their own against a queue that is already known full. */
+    private readonly probing;
+    private readonly limits;
+    private readonly maxWaitMs;
+    private readonly initialProbeMs;
+    constructor(store: TaskStore, opts: BackpressureOptions);
+    private validate;
+    /** The limit for `queue`, or null when it is not gated. */
+    limitFor(queue: string): number | null;
+    /**
+     * Consume one unit of headroom for `queue`, waiting for room if it is full.
+     * Returns immediately for an ungated queue. Raises QueueFull on timeout,
+     * having enqueued nothing.
+     */
+    acquire(queue: string): Promise<void>;
+    /**
+     * Refresh `queue`'s grant from the store, at most one probe in flight.
+     *
+     * Callers re-read `headroom` afterwards rather than using a returned value:
+     * only the caller that started the probe writes the grant, so waiters that
+     * joined it cannot overwrite the units already handed out.
+     */
+    private probe;
+}

package/dist/backpressure.js

@@ -0,0 +1,122 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { QueueFull } from "./errors.js";
+/**
+ * Most tasks a producer may enqueue on one probe's word.
+ *
+ * The gate probes only when its headroom runs out, so this is what the check
+ * costs amortized: one bounded index read per MAX_GRANT submits. It also bounds
+ * how far the limit can be overshot — see the class docstring on why several
+ * producers make this a soft limit, and why that overshoot is (N-1) * MAX_GRANT
+ * rather than unbounded.
+ */
+const MAX_GRANT = 64;
+// Named for probing, not polling: wait.ts exports DEFAULT_POLL_MS / MAX_POLL_MS
+// for the get() loop behind wait(), an order of magnitude tighter and answering
+// a different question. Two constants of the same name in one SDK would be read
+// as one policy.
+const INITIAL_PROBE_INTERVAL_MS = 250;
+const MAX_PROBE_INTERVAL_MS = 5_000;
+const DEFAULT_MAX_WAIT_MS = 600_000;
+/**
+ * Blocks `submit` while a queue is at its depth limit.
+ *
+ * Without one of these a producer that outruns its workers is only bounded by
+ * disk: the backlog grows, every task's queue wait grows with it, and the
+ * failure is a database that filled up rather than a producer that slowed down.
+ * A queue is the wrong place to buffer an overload — pushing back on the
+ * producer is the point.
+ *
+ * **A soft limit under several producers.** The check is a read followed by a
+ * write that other producers can interleave with, and each holds its own grant,
+ * so N producers can overshoot the limit by up to (N-1) * MAX_GRANT tasks. Made
+ * exact it would need the depth check inside insert_task's transaction, which
+ * puts an unbounded-scan predicate on the hot path of every submit and turns
+ * concurrent submits into lock contention — a steep price for a bound whose
+ * whole purpose is approximate. Size the limit for the pushback you want, not as
+ * a capacity assertion.
+ */
+export class QueueDepthGate {
+    store;
+    /** Remaining grant per queue: submits allowed before the next probe. */
+    headroom = new Map();
+    /** In-flight probe per queue, so concurrent submits share one read rather
+     * than each issuing their own against a queue that is already known full. */
+    probing = new Map();
+    limits;
+    maxWaitMs;
+    initialProbeMs;
+    constructor(store, opts) {
+        this.store = store;
+        this.limits = opts.maxQueueDepth;
+        this.maxWaitMs = opts.maxQueueWaitMs ?? DEFAULT_MAX_WAIT_MS;
+        this.initialProbeMs = opts.queuePollIntervalMs ?? INITIAL_PROBE_INTERVAL_MS;
+        if (typeof this.limits === "number")
+            this.validate("*", this.limits);
+        else
+            for (const [q, v] of Object.entries(this.limits))
+                this.validate(q, v);
+    }
+    validate(queue, limit) {
+        // A limit of 0 would block every submit forever, which is never what a
+        // caller means; catching it here beats a first submit that hangs for
+        // maxQueueWaitMs and then raises.
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new Error(`maxQueueDepth for ${queue} must be an integer >= 1, got ${limit}`);
+        }
+    }
+    /** The limit for `queue`, or null when it is not gated. */
+    limitFor(queue) {
+        if (typeof this.limits === "number")
+            return this.limits;
+        return this.limits[queue] ?? null;
+    }
+    /**
+     * Consume one unit of headroom for `queue`, waiting for room if it is full.
+     * Returns immediately for an ungated queue. Raises QueueFull on timeout,
+     * having enqueued nothing.
+     */
+    async acquire(queue) {
+        const limit = this.limitFor(queue);
+        if (limit == null)
+            return;
+        const startedAt = Date.now();
+        let waitMs = this.initialProbeMs;
+        for (;;) {
+            const left = this.headroom.get(queue) ?? 0;
+            if (left > 0) {
+                this.headroom.set(queue, left - 1);
+                return;
+            }
+            await this.probe(queue, limit);
+            if ((this.headroom.get(queue) ?? 0) > 0)
+                continue;
+            const waited = Date.now() - startedAt;
+            if (waited >= this.maxWaitMs)
+                throw new QueueFull(queue, limit, waited);
+            // Back off: a queue at its limit will not drain within one poll interval,
+            // and re-probing tightly adds read load to a database already behind.
+            await delay(Math.min(waitMs, this.maxWaitMs - waited));
+            waitMs = Math.min(waitMs * 2, MAX_PROBE_INTERVAL_MS);
+        }
+    }
+    /**
+     * Refresh `queue`'s grant from the store, at most one probe in flight.
+     *
+     * Callers re-read `headroom` afterwards rather than using a returned value:
+     * only the caller that started the probe writes the grant, so waiters that
+     * joined it cannot overwrite the units already handed out.
+     */
+    probe(queue, limit) {
+        let p = this.probing.get(queue);
+        if (!p) {
+            p = this.store
+                .queueDepth(queue, limit)
+                .then((headroom) => {
+                this.headroom.set(queue, Math.min(headroom, MAX_GRANT));
+            })
+                .finally(() => this.probing.delete(queue));
+            this.probing.set(queue, p);
+        }
+        return p;
+    }
+}

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import type { BackpressureOptions } from "./backpressure.js";
 import { type Task, type TaskStatus } from "./models.js";
 import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
@@ -6,23 +7,35 @@ export interface CallOptions extends SubmitOptions {
     waitTimeoutMs?: number;
     pollMs?: number;
 }
+/** Options this handle configures on the store it wraps, rather than the
+ * store's own constructor arguments. */
+export type ClientOptions = Partial<BackpressureOptions>;
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export declare class CairnQ {
     private readonly _store;
-    constructor(_store: TaskStore);
+    constructor(_store: TaskStore, opts?: ClientOptions);
     static sqlite(path: string, opts?: {
         busyTimeoutMs?: number;
-    }): CairnQ;
+    } & ClientOptions): CairnQ;
     /** Multi-host backend. `dsn` is a libpq connection string; requires the
      * optional `pg` package. */
     static postgres(dsn: string, opts?: {
         max?: number;
-    }): CairnQ;
+    } & ClientOptions): CairnQ;
     get store(): TaskStore;
     connect(): Promise<void>;
     close(): Promise<void>;
+    /** Enqueue a task. With `maxQueueDepth` configured this blocks while the
+     * target queue is at its limit, and raises QueueFull if it stays there for
+     * `maxQueueWaitMs` — see QueueDepthGate for why that bound is approximate
+     * across several producers. */
     submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;
     submit<P, R>(task: TaskDef<P, R>, payload?: P, opts?: SubmitOptions): Promise<Task>;
+    /** How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
+     * The non-blocking read behind `maxQueueDepth`, for a producer that would
+     * rather shed load or pick another queue than wait. Cheaper than `stats()`:
+     * bounded at `maxDepth` index entries instead of aggregating the table. */
+    queueDepth(queue: string, maxDepth: number): Promise<number>;
     get(taskId: string): Promise<Task | null>;
     getByKey(key: string): Promise<Task | null>;
     list(input?: ListInput): Promise<Task[]>;

package/dist/client.js

@@ -7,16 +7,23 @@ import { pollWait } from "./wait.js";
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export class CairnQ {
     _store;
-    constructor(_store) {
+    constructor(_store, opts = {}) {
         this._store = _store;
+        // Installed on the store, not held here: every submit path goes through the
+        // store, including TaskContext.submit, which this handle never sees.
+        if (opts.maxQueueDepth != null) {
+            _store.useBackpressure(opts);
+        }
     }
-    static sqlite(path, opts) {
-        return new CairnQ(new SQLiteStore(path, opts));
+    static sqlite(path, opts = {}) {
+        const { busyTimeoutMs, ...client } = opts;
+        return new CairnQ(new SQLiteStore(path, { busyTimeoutMs }), client);
     }
     /** Multi-host backend. `dsn` is a libpq connection string; requires the
      * optional `pg` package. */
-    static postgres(dsn, opts) {
-        return new CairnQ(new PostgresStore(dsn, opts));
+    static postgres(dsn, opts = {}) {
+        const { max, ...client } = opts;
+        return new CairnQ(new PostgresStore(dsn, { max }), client);
     }
     get store() {
         return this._store;
@@ -30,6 +37,13 @@ export class CairnQ {
     submit(task, payload, opts = {}) {
         return this._store.submit({ name: taskName(task), payload, ...opts });
     }
+    /** How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
+     * The non-blocking read behind `maxQueueDepth`, for a producer that would
+     * rather shed load or pick another queue than wait. Cheaper than `stats()`:
+     * bounded at `maxDepth` index entries instead of aggregating the table. */
+    queueDepth(queue, maxDepth) {
+        return this._store.queueDepth(queue, maxDepth);
+    }
     get(taskId) {
         return this._store.get(taskId);
     }