cairnq 0.3.0 → 0.5.0

package/dist/store/sqlite.js

@@ -3,7 +3,7 @@ import { dirname, resolve } from "node:path";
 import Database from "better-sqlite3";
 import { nowMs } from "../ids.js";
 import { loadMigrations, loadStatements } from "../sql.js";
-import { checkProtocolVersion, statementParams, TaskStore, } from "./base.js";
+import { checkProtocolVersion, COMMENT, statementParams, TaskStore, } from "./base.js";
 const WAL_RETRY_DELAY_MS = 50;
 const WAL_RETRY_BUDGET_MS = 5_000;
 const BUSY_RETRY_BASE_MS = 1;
@@ -14,7 +14,7 @@ const BUSY_RETRY_MAX_DELAY_MS = 50;
  * Bounds how long the planner can work from a stale table shape; a minute is
  * arbitrary but small next to the days a worker holds its connection. It does not
  * set how often an ANALYZE actually runs — SQLite decides that itself, and only
- * when a table has outgrown its statistics by roughly 24x, so a shorter interval
+ * once the table has diverged from its statistics by 10x, so a shorter interval
  * costs more no-ops (a few microseconds each) rather than more analyzing.
  */
 const STATS_REFRESH_INTERVAL_MS = 60_000;
@@ -43,6 +43,20 @@ function isBusy(err) {
 function isMemory(path) {
     return path === ":memory:" || path.includes("mode=memory");
 }
+/**
+ * Whether this statement writes, and so belongs in a group commit.
+ *
+ * Read from the SQL rather than from a list of statement names, which would be a
+ * second place to remember when the protocol gains a statement. Every protocol
+ * statement is a single top-level `select`, `insert`, `update` or `delete`.
+ *
+ * Reads must stay out of the batch: `claimable_probe` exists precisely so an idle
+ * worker never takes SQLite's write lock, and a BEGIN IMMEDIATE around it would
+ * hand that back.
+ */
+function isWriteStatement(sql) {
+    return !/^\s*select/i.test(sql.replace(COMMENT, ""));
+}
 /**
  * Whether cairnq_tasks has been analyzed at all.
  *
@@ -170,11 +184,18 @@ export class SQLiteStore extends TaskStore {
     busyBudgetMs;
     /** When this connection may next revisit its planner statistics. */
     nextStatsRefreshAt = 0;
+    /** Which statements are writes — see isWriteStatement. */
+    writes;
+    /** Writes waiting to be group-committed — see flush(). */
+    pending = [];
+    /** Whether a flusher is already queued to drain `pending`. */
+    flushing = false;
     constructor(path, opts = {}) {
         super();
         this.path = path;
         this.busyBudgetMs = opts.busyTimeoutMs ?? 5000;
         this.statements = loadStatements("sqlite");
+        this.writes = Object.fromEntries(Object.entries(this.statements).map(([name, sql]) => [name, isWriteStatement(sql)]));
         // Only a bare ":memory:" is guaranteed private to its connection, so only
         // it gets a lock of its own. A "mode=memory" URI stays path-keyed: with
         // cache=shared it names ONE shared database, and on a build without URI
@@ -389,10 +410,146 @@ export class SQLiteStore extends TaskStore {
                 throw err;
         }
     }
+    /**
+     * Group commit: one transaction for every write already waiting on the lock.
+     *
+     * A write costs microseconds to execute and a transaction costs a WAL commit, so
+     * N concurrent writes spend nearly all their time on N commits they could have
+     * shared. Measured at 200 finalizes: 80µs each one-transaction-apiece against
+     * 10µs each in one transaction (`bench/sweep` sweep B).
+     *
+     * Nothing waits to form a batch — a flusher takes whatever arrived while the
+     * previous one held the lock, so this trades no latency for the throughput. What
+     * it does trade is atomicity: two callers' writes now land together or not at
+     * all. Under at-least-once that is not observable (a lost batch is a
+     * redelivery), and it is why every member is resolved only after COMMIT.
+     */
+    flush(db) {
+        // One writer waiting is the uncontended case, and it stays exactly as cheap as
+        // before: wrapping a single statement in BEGIN/COMMIT would add two statements
+        // to every write on an idle store.
+        if (this.pending.length === 1) {
+            const only = this.pending[0];
+            let rows;
+            try {
+                rows = this.runNow(only.name, only.params);
+            }
+            catch (err) {
+                // Leave it pending on a lost write lock: withLock re-runs this flusher.
+                if (isBusy(err))
+                    throw err;
+                this.pending.shift();
+                only.reject(err);
+                return;
+            }
+            this.pending.shift();
+            only.resolve(rows);
+            return;
+        }
+        // BEGIN before consuming, so a lost write lock leaves the batch where the
+        // retry will find it — with anything that arrived meanwhile.
+        db.exec("BEGIN IMMEDIATE");
+        const batch = this.pending;
+        this.pending = [];
+        const out = [];
+        try {
+            for (const w of batch) {
+                try {
+                    out.push({ rows: this.runNow(w.name, w.params) });
+                }
+                catch (err) {
+                    // A statement error aborts that statement, not the transaction, so the
+                    // rest of the batch is still good and this one waiter carries the error.
+                    // If SQLite tore the transaction down instead, nothing in it survived
+                    // and every member has to hear about it.
+                    if (!db.inTransaction)
+                        throw err;
+                    out.push({ err });
+                }
+            }
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            if (db.inTransaction) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    // Raced with SQLite's own rollback; the transaction is gone either way.
+                }
+            }
+            if (isBusy(err)) {
+                // Back to the head of the queue, ahead of later arrivals, so the retry
+                // preserves the order the writes were issued in.
+                this.pending = batch.concat(this.pending);
+                throw err;
+            }
+            for (const w of batch)
+                w.reject(err);
+            return;
+        }
+        // Only now: before COMMIT a rollback could still take the write back, and a
+        // caller holding its row would have observed a write that never happened.
+        for (let i = 0; i < batch.length; i++) {
+            // Presence, not truthiness — a thrown value is not guaranteed to be one.
+            if ("err" in out[i])
+                batch[i].reject(out[i].err);
+            else
+                batch[i].resolve(out[i].rows);
+        }
+    }
+    /**
+     * Make sure some flusher is draining `pending`, without ever running two.
+     *
+     * The flusher loops instead of re-arming itself per batch. A caller that awaits
+     * its writes one at a time resumes and issues the next one *before* the flusher
+     * gets its turn back, so re-arming would cost that write an extra trip through
+     * the lock queue — measured as ~2x on sequential writes, which is most of them.
+     * Looping picks it up in the same session for free.
+     *
+     * The exit is safe because the last `pending` check and clearing the flag happen
+     * in one synchronous step: a write that arrives before it keeps the loop going,
+     * and one that arrives after sees the flag down and starts a new flusher.
+     */
+    scheduleFlush(db) {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        void (async () => {
+            try {
+                while (this.pending.length) {
+                    try {
+                        await this.withLock(() => this.flush(db));
+                    }
+                    catch (err) {
+                        // flush only throws on a lost write lock, and only after putting its
+                        // batch back — so reaching here means withLock spent the whole budget
+                        // and those writes are still queued with nobody else coming for them.
+                        // Anything that arrived behind them is failed with the same error
+                        // rather than left hanging: this store cannot write at all right now,
+                        // which is what a lone write would have been told too.
+                        const stranded = this.pending;
+                        this.pending = [];
+                        for (const w of stranded)
+                            w.reject(err);
+                    }
+                }
+            }
+            finally {
+                this.flushing = false;
+            }
+        })();
+    }
     async fetch(name, params) {
         const db = this.ensure();
         await this.maybeRefreshStatistics(db);
-        return this.withLock(() => this.runNow(name, params));
+        // Reads keep their own turn on the lock — see isWriteStatement.
+        if (!this.writes[name])
+            return this.withLock(() => this.runNow(name, params));
+        return new Promise((resolve, reject) => {
+            this.pending.push({ name, params, resolve, reject });
+            this.scheduleFlush(db);
+        });
     }
     async tx(fn) {
         const db = this.ensure();

package/dist/worker.d.ts

@@ -1,3 +1,4 @@
+import type { BackpressureOptions } from "./backpressure.js";
 import { TaskContext } from "./context.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
@@ -6,7 +7,12 @@ export type Handler = (ctx: TaskContext, payload: any) => unknown | Promise<unkn
 export type TypedHandler<P, R> = (ctx: TaskContext, payload: P) => R | Promise<R>;
 /** Where an error the worker recovered from came from. */
 export type ErrorPhase = "claim" | "execute";
-export interface WorkerOptions {
+/**
+ * Backpressure is accepted here too, not only on CairnQ: a handler spawning
+ * children through TaskContext.submit is a producer, and in a worker process
+ * there is usually no CairnQ handle to have configured the store.
+ */
+export interface WorkerOptions extends Partial<BackpressureOptions> {
     concurrency?: number;
     leaseMs?: number;
     heartbeatIntervalMs?: number;
@@ -25,6 +31,25 @@ export interface WorkerOptions {
      * a retryable `handler_timeout` failure. Unset disables the ceiling.
      */
     maxRunMs?: number;
+    /**
+     * Resident payload bytes allowed across running handlers, independent of
+     * their count.
+     *
+     * `concurrency` bounds tasks, not memory, so a worker sized for small payloads
+     * holds concurrency * largest-payload bytes the moment a batch of big ones
+     * arrives — for payloads that carry media inline, that is the difference
+     * between megabytes and gigabytes resident. Once the budget is spent the
+     * worker stops claiming until running handlers give it back.
+     *
+     * The bound is on tasks already executing. A claim commits to a whole batch
+     * before any size is known, so one batch can overshoot by up to `claimBatch`
+     * payloads; lower `claimBatch` to tighten that. A single payload larger than
+     * the entire budget still runs — alone, rather than deadlocking the worker.
+     *
+     * Costs one JSON serialization per task to measure, so it is only computed
+     * when set. Unset disables the budget.
+     */
+    maxInFlightBytes?: number;
     /**
      * Called for errors the worker survived — a claim that threw, a store write
      * that failed while finalizing a task. Without it these are silent: the run
@@ -44,6 +69,8 @@ export declare class Worker {
     private readonly opts;
     private readonly handlers;
     private readonly workerId;
+    /** Payload bytes charged to running handlers — see maxInFlightBytes. */
+    private inFlightBytes;
     private stopped;
     private stopWake;
     private readonly stopped$;

package/dist/worker.js

@@ -41,12 +41,38 @@ function timeoutEnvelope(name, maxRunMs) {
     });
 }
 const TIMED_OUT = Symbol("cairnq.timedOut");
+/**
+ * Resident size of a task's payload, for the maxInFlightBytes budget.
+ *
+ * Re-serializes because by this point the wire form is gone: `pg` parses a jsonb
+ * column with JSON.parse and discards the text, so on Postgres there is nothing
+ * cheaper to read. On SQLite the column does arrive as a string that rowToTask
+ * sees before parsing — capturing its length there would make this free, at the
+ * cost of carrying a non-protocol field on Task in both SDKs. Left for when the
+ * measurement shows up in a profile.
+ *
+ * What the budget is really after is the memory a payload pins while its handler
+ * runs, and its JSON length tracks that closely enough to size one by.
+ */
+function payloadBytes(task) {
+    try {
+        return Buffer.byteLength(JSON.stringify(task.payload) ?? "");
+    }
+    catch {
+        // Unmeasurable, and it came out of the store, so it is already resident:
+        // charging nothing under-counts, but failing the claim over an accounting
+        // detail would drop a task the worker can otherwise run.
+        return 0;
+    }
+}
 export class Worker {
     store;
     queues;
     opts;
     handlers = new Map();
     workerId = newId("worker");
+    /** Payload bytes charged to running handlers — see maxInFlightBytes. */
+    inFlightBytes = 0;
     stopped = false;
     stopWake;
     // Resolved once by stop(); every sleep races against it. A stopped worker
@@ -62,6 +88,14 @@ export class Worker {
         if (opts.maxRunMs != null && opts.maxRunMs <= 0) {
             throw new Error(`maxRunMs must be > 0, got ${opts.maxRunMs}`);
         }
+        // 0 would make the budget permanently spent, so the worker would claim
+        // nothing and look hung. Rejected here, as the Python SDK does.
+        if (opts.maxInFlightBytes != null && opts.maxInFlightBytes <= 0) {
+            throw new Error(`maxInFlightBytes must be > 0, got ${opts.maxInFlightBytes}`);
+        }
+        if (opts.maxQueueDepth != null) {
+            store.useBackpressure(opts);
+        }
     }
     static sqlite(path, opts = {}) {
         const { queues = ["default"], busyTimeoutMs, ...rest } = opts;
@@ -146,9 +180,16 @@ export class Worker {
     }
     async loop(concurrency, batch, leaseMs, running) {
         const pollMs = this.opts.pollIntervalMs ?? 500;
+        const byteBudget = this.opts.maxInFlightBytes;
         while (!this.stopped) {
             const free = concurrency - running.size;
-            if (free <= 0) {
+            // Two ceilings, either of which stops the claim: task count and resident
+            // payload bytes. The byte arm is guarded on running.size because it must
+            // never be the reason we race an empty set — Promise.race([]) is pending
+            // forever, past even stop(). With nothing running, nothing is resident, so
+            // the budget cannot be the thing holding us back anyway.
+            const overBudget = byteBudget != null && this.inFlightBytes >= byteBudget;
+            if (running.size > 0 && (free <= 0 || overBudget)) {
                 // Wait for a slot rather than spinning. execute() never rejects, so
                 // racing these is safe.
                 await Promise.race([...running]);
@@ -180,7 +221,14 @@ export class Worker {
                 continue;
             }
             for (const task of claimed) {
-                const p = this.execute(task, leaseMs).finally(() => running.delete(p));
+                // Charged before the handler starts and refunded when it settles, so the
+                // budget covers exactly the span the payload is pinned in memory.
+                const bytes = byteBudget == null ? 0 : payloadBytes(task);
+                this.inFlightBytes += bytes;
+                const p = this.execute(task, leaseMs).finally(() => {
+                    this.inFlightBytes -= bytes;
+                    running.delete(p);
+                });
                 running.add(p);
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",
@@ -31,15 +31,16 @@
     }
   },
   "files": ["dist", "src"],
-  "engines": { "node": ">=20" },
+  "engines": { "node": ">=22" },
   "scripts": {
     "bench": "tsx bench/run.ts",
+    "bench:sweep": "tsx bench/sweep.ts",
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "better-sqlite3": "^11.3.0"
+    "better-sqlite3": "^13.0.2"
   },
   "peerDependencies": {
     "pg": "^8.13.0"
@@ -55,8 +56,8 @@
     "@types/pg": "^8.11.10",
     "pg": "^8.13.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "pnpm": {
     "onlyBuiltDependencies": ["better-sqlite3", "esbuild"]

package/src/backpressure.ts

@@ -0,0 +1,140 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { QueueFull } from "./errors.js";
+import type { TaskStore } from "./store/base.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;
+
+/** 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 class QueueDepthGate {
+  /** Remaining grant per queue: submits allowed before the next probe. */
+  private readonly headroom = new Map<string, number>();
+  /** 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 = new Map<string, Promise<void>>();
+  private readonly limits: QueueDepthLimit;
+  private readonly maxWaitMs: number;
+  private readonly initialProbeMs: number;
+
+  constructor(
+    private readonly store: TaskStore,
+    opts: BackpressureOptions,
+  ) {
+    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);
+  }
+
+  private validate(queue: string, limit: number): void {
+    // 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: string): number | null {
+    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: string): Promise<void> {
+    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.
+   */
+  private probe(queue: string, limit: number): Promise<void> {
+    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/src/client.ts

@@ -1,3 +1,4 @@
+import type { BackpressureOptions } from "./backpressure.js";
 import { TaskCanceled, TaskFailed } from "./errors.js";
 import { isFailed, isSucceeded, type Task, type TaskStatus } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
@@ -12,18 +13,33 @@ export interface CallOptions extends SubmitOptions {
   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 class CairnQ {
-  constructor(private readonly _store: TaskStore) {}
+  constructor(
+    private readonly _store: TaskStore,
+    opts: ClientOptions = {},
+  ) {
+    // 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 as BackpressureOptions);
+    }
+  }
 
-  static sqlite(path: string, opts?: { busyTimeoutMs?: number }): CairnQ {
-    return new CairnQ(new SQLiteStore(path, opts));
+  static sqlite(path: string, opts: { busyTimeoutMs?: number } & ClientOptions = {}): CairnQ {
+    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: string, opts?: { max?: number }): CairnQ {
-    return new CairnQ(new PostgresStore(dsn, opts));
+  static postgres(dsn: string, opts: { max?: number } & ClientOptions = {}): CairnQ {
+    const { max, ...client } = opts;
+    return new CairnQ(new PostgresStore(dsn, { max }), client);
   }
 
   get store(): TaskStore {
@@ -38,12 +54,24 @@ export class CairnQ {
     return this._store.close();
   }
 
+  /** 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>;
   submit(task: string | TaskDef, payload?: unknown, opts: SubmitOptions = {}): Promise<Task> {
     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: string, maxDepth: number): Promise<number> {
+    return this._store.queueDepth(queue, maxDepth);
+  }
+
   get(taskId: string): Promise<Task | null> {
     return this._store.get(taskId);
   }

package/src/errors.ts

@@ -37,6 +37,24 @@ export class AlreadyExists extends CairnQError {
   }
 }
 
+/** A gated submit waited out `maxWaitMs` without the queue draining below its
+ * depth limit. Nothing was enqueued. Distinct from a slow submit on purpose: a
+ * queue this far behind is a capacity problem, and a caller that silently
+ * retries forever converts it into an invisible one. */
+export class QueueFull extends CairnQError {
+  constructor(
+    public queue: string,
+    public maxDepth: number,
+    public waitedMs: number,
+  ) {
+    super(
+      `queue ${queue} still holds ${maxDepth} or more queued tasks after ` +
+        `${waitedMs}ms; refusing to enqueue more`,
+    );
+    this.name = "QueueFull";
+  }
+}
+
 /** One line of "why hasn't this finished" from the last snapshot wait()
  * observed. No worker running, no handler for the name, wrong queue, and two
  * processes on different database files all look identical from the API side —

package/src/index.ts

@@ -1,5 +1,7 @@
 export { CairnQ } from "./client.js";
-export type { CallOptions, SubmitOptions } from "./client.js";
+export type { CallOptions, ClientOptions, SubmitOptions } from "./client.js";
+export { QueueDepthGate } from "./backpressure.js";
+export type { BackpressureOptions, QueueDepthLimit } from "./backpressure.js";
 export { Worker } from "./worker.js";
 export type { Handler, TypedHandler, WorkerOptions } from "./worker.js";
 export { TaskContext } from "./context.js";
@@ -23,6 +25,7 @@ export {
 export {
   CairnQError,
   AlreadyExists,
+  QueueFull,
   TaskTimeout,
   TaskFailed,
   TaskCanceled,