cairnq 0.3.0 → 0.5.0

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/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/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);
     }

package/dist/errors.d.ts

@@ -16,6 +16,16 @@ export declare class AlreadyExists extends CairnQError {
     key: string;
     constructor(key: string);
 }
+/** 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 declare class QueueFull extends CairnQError {
+    queue: string;
+    maxDepth: number;
+    waitedMs: number;
+    constructor(queue: string, maxDepth: number, waitedMs: number);
+}
 /** wait/call did not reach a terminal status in time. The task keeps running.
  * `task` is the last snapshot wait() observed (null if get() found nothing), and
  * the message says what state it was stuck in — a queued-never-claimed task is

package/dist/errors.js

@@ -29,6 +29,23 @@ export class AlreadyExists extends CairnQError {
         this.name = "AlreadyExists";
     }
 }
+/** 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 {
+    queue;
+    maxDepth;
+    waitedMs;
+    constructor(queue, maxDepth, waitedMs) {
+        super(`queue ${queue} still holds ${maxDepth} or more queued tasks after ` +
+            `${waitedMs}ms; refusing to enqueue more`);
+        this.queue = queue;
+        this.maxDepth = maxDepth;
+        this.waitedMs = waitedMs;
+        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/dist/index.d.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";
@@ -11,4 +13,4 @@ export { TaskStore } from "./store/base.js";
 export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
 export type { Task, TaskStatus } from "./models.js";
 export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { CairnQ } from "./client.js";
+export { QueueDepthGate } from "./backpressure.js";
 export { Worker } from "./worker.js";
 export { TaskContext } from "./context.js";
 export { defineTask } from "./task.js";
@@ -6,4 +7,4 @@ export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
 export { TaskStore } from "./store/base.js";
 export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/store/base.d.ts

@@ -1,4 +1,5 @@
 import { type Task, type TaskStatus } from "../models.js";
+import { type BackpressureOptions } from "../backpressure.js";
 /** Encode a value for a protocol JSON column, raising SerializationError on
  * anything JSON cannot represent. Refuses what JSON.stringify would silently
  * mangle into `null`: NaN/Infinity anywhere, undefined/function/symbol inside an
@@ -12,6 +13,9 @@ export declare function dumpJson(value: unknown): string;
 export declare function checkProtocolVersion(version: number): void;
 declare const CONFLICTS: readonly ["reuse", "reject", "replace"];
 export type Conflict = (typeof CONFLICTS)[number];
+/** The queue a submit lands on when it names none. Owned here, where the
+ * default is applied, so nothing above has to re-derive it. */
+export declare const DEFAULT_QUEUE = "default";
 export interface SubmitInput {
     name: string;
     payload: unknown;
@@ -69,6 +73,8 @@ export declare function statementParams(sql: string): readonly string[];
  * behavior; the shared SQL already stops them from drifting in wording.
  */
 export declare abstract class TaskStore {
+    /** Set by useBackpressure; null means submit is ungated. */
+    private gate;
     abstract connect(): Promise<void>;
     abstract close(): Promise<void>;
     abstract protocolVersion(): Promise<number>;
@@ -103,6 +109,15 @@ export declare abstract class TaskStore {
      */
     private ownedWrite;
     private static one;
+    /**
+     * Bound how deep a queue may get before `submit` blocks. Off unless set.
+     *
+     * It hangs here rather than on `CairnQ` because the store is the one choke
+     * point every submit passes through — a handler spawning children via
+     * `TaskContext.submit` is the shape most likely to outrun its workers, and
+     * gating only the client would leave exactly that path unbounded.
+     */
+    useBackpressure(opts: BackpressureOptions): void;
     submit(input: SubmitInput): Promise<Task>;
     get(taskId: string): Promise<Task | null>;
     getByKey(key: string): Promise<Task | null>;
@@ -136,6 +151,15 @@ export declare abstract class TaskStore {
      * them.
      */
     stats(): Promise<Record<string, Record<TaskStatus, number>>>;
+    /**
+     * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
+     *
+     * The cheap half of backpressure: bounded at `maxDepth` index entries, unlike
+     * `stats()`, which aggregates the whole table (terminal rows included) and so
+     * costs more the longer a database has been running. Use it directly to shed
+     * load or shape a producer; `QueueDepthGate` builds the blocking form on top.
+     */
+    queueDepth(queue: string, maxDepth: number): Promise<number>;
     /**
      * Take up to `limit` claimable tasks. `names` restricts the claim to task names
      * this caller can actually run — a worker passes its registered handlers.

package/dist/store/base.js

@@ -1,6 +1,7 @@
 import { newId } from "../ids.js";
 import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, } from "../errors.js";
 import { rowToTask, STATUSES } from "../models.js";
+import { QueueDepthGate } from "../backpressure.js";
 const rejectMangled = function (_key, v) {
     if (typeof v === "number" && !Number.isFinite(v)) {
         throw new SerializationError(`non-finite number ${v} is not JSON-serializable`);
@@ -51,6 +52,9 @@ export function checkProtocolVersion(version) {
 // runtime guard in submit() and the type can't drift apart (same pattern as
 // STATUSES/TaskStatus in models.ts).
 const CONFLICTS = ["reuse", "reject", "replace"];
+/** The queue a submit lands on when it names none. Owned here, where the
+ * default is applied, so nothing above has to re-derive it. */
+export const DEFAULT_QUEUE = "default";
 export const LEASE_EXPIRED_ERROR_JSON = dumpJson(errorEnvelope({
     type: "LeaseExpired",
     code: "lease_expired",
@@ -97,6 +101,8 @@ export function statementParams(sql) {
  * behavior; the shared SQL already stops them from drifting in wording.
  */
 export class TaskStore {
+    /** Set by useBackpressure; null means submit is ungated. */
+    gate = null;
     /**
      * Whether it is worth opening the claim transaction at all. SQLite gates its
      * single write lock behind a read-only probe; Postgres readers don't block
@@ -137,12 +143,23 @@ export class TaskStore {
         return rows.length ? rowToTask(rows[0]) : null;
     }
     // ------------------------------------------------------------- client side
+    /**
+     * Bound how deep a queue may get before `submit` blocks. Off unless set.
+     *
+     * It hangs here rather than on `CairnQ` because the store is the one choke
+     * point every submit passes through — a handler spawning children via
+     * `TaskContext.submit` is the shape most likely to outrun its workers, and
+     * gating only the client would leave exactly that path unbounded.
+     */
+    useBackpressure(opts) {
+        this.gate = new QueueDepthGate(this, opts);
+    }
     async submit(input) {
         const id = newId("task");
         const ins = {
             id,
             name: input.name,
-            queue: input.queue ?? "default",
+            queue: input.queue ?? DEFAULT_QUEUE,
             payload: dumpJson(input.payload ?? {}),
             metadata: dumpJson(input.metadata ?? {}),
             max_attempts: input.maxAttempts ?? 3,
@@ -169,6 +186,11 @@ export class TaskStore {
         if (input.runAtDelayMs != null && input.runAtDelayMs < 0) {
             throw new Error(`runAtDelayMs must be >= 0, got ${input.runAtDelayMs}`);
         }
+        // After validation and before the first write: bad arguments should fail
+        // now, not after waiting out a full queue. Reads the resolved queue, so the
+        // gate cannot throttle one queue while the row lands on another.
+        if (this.gate)
+            await this.gate.acquire(ins.queue);
         if (key === null)
             return rowToTask((await this.fetch("insert_task", ins))[0]);
         // A key makes submit a read-then-write, so it has to be one transaction —
@@ -284,6 +306,21 @@ export class TaskStore {
         }
         return out;
     }
+    /**
+     * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
+     *
+     * The cheap half of backpressure: bounded at `maxDepth` index entries, unlike
+     * `stats()`, which aggregates the whole table (terminal rows included) and so
+     * costs more the longer a database has been running. Use it directly to shed
+     * load or shape a producer; `QueueDepthGate` builds the blocking form on top.
+     */
+    async queueDepth(queue, maxDepth) {
+        if (!Number.isInteger(maxDepth) || maxDepth < 0) {
+            throw new Error(`maxDepth must be a non-negative integer, got ${maxDepth}`);
+        }
+        const rows = await this.fetch("queue_depth", { queue, max_depth: maxDepth });
+        return Number(rows[0]?.headroom ?? 0);
+    }
     // ------------------------------------------------------------- worker side
     /**
      * Take up to `limit` claimable tasks. `names` restricts the claim to task names

package/dist/store/sqlite.d.ts

@@ -35,6 +35,12 @@ export declare class SQLiteStore extends TaskStore {
     private readonly busyBudgetMs;
     /** When this connection may next revisit its planner statistics. */
     private nextStatsRefreshAt;
+    /** Which statements are writes — see isWriteStatement. */
+    private readonly writes;
+    /** Writes waiting to be group-committed — see flush(). */
+    private pending;
+    /** Whether a flusher is already queued to drain `pending`. */
+    private flushing;
     constructor(path: string, opts?: {
         busyTimeoutMs?: number;
     });
@@ -94,6 +100,35 @@ export declare class SQLiteStore extends TaskStore {
      * interval try, instead of spending an operation's whole retry budget on them.
      */
     private maybeRefreshStatistics;
+    /**
+     * 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.
+     */
+    private flush;
+    /**
+     * 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.
+     */
+    private scheduleFlush;
     protected fetch(name: string, params: Params): Promise<any[]>;
     protected tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
     protected hasClaimableWork(params: Params): Promise<boolean>;