cairnq 0.11.0 → 0.13.0

package/dist/_protocol/migrations/postgres/0009_purge_queue_index.sql

@@ -0,0 +1,39 @@
+-- Give the retention sweep a queue dimension it can actually read.
+--
+-- purge gained an optional `:queue` filter, and without an index for it queue is
+-- a residual on cairnq_tasks_completed_idx (completed_at_ms) or
+-- cairnq_tasks_status_completed_idx (status, completed_at_ms): the scan walks in
+-- completion order and throws away every row belonging to another queue. `limit`
+-- bounds what comes back, not what is read — and the shape that makes the filter
+-- worth having in the first place is exactly the worst case for it. One store
+-- carrying an RPC queue kept for minutes and a durable queue kept for a week is
+-- the cross-language coordination this project recommends; sweeping the RPC
+-- queue then means walking the week's worth of older rows the other queue is
+-- deliberately holding onto, over and over, once per batch.
+--
+-- Partial, on the terminal statuses, for two reasons. It is the smaller half of
+-- the table — a busy queue's live rows never enter it — and, more to the point,
+-- rows enter it only when a task settles, so the index is not a tax on the claim
+-- path the way a full index on (queue, ...) would be. purge.sql always carries
+-- the literal `status in ('succeeded','failed','canceled')`, whether or not the
+-- caller narrowed to one status, so the predicate matches exactly and the
+-- planner never has to prove anything subtler to use it.
+--
+-- Measured on SQLite 3.39.4, 20k rows over two queues and four statuses, with
+-- 0002's and 0007's indexes present alongside it: every filter combination purge
+-- can issue is served by one index scan with the ORDER BY satisfied from the
+-- index (no temp b-tree), and the two pre-existing shapes — unfiltered, and
+-- status-only — still choose their old indexes, so nothing that worked before
+-- got slower. Postgres is reasoned from the same shape rather than benchmarked;
+-- see 0008 for why that caveat keeps appearing.
+--
+-- Unlike 0008 this only CREATES an index, so an older SDK is unaffected: it
+-- never passes `:queue`, its statements are unchanged, and it pays only the
+-- write-side cost of an index it does not read. The build still holds a lock for
+-- as long as it takes (no CONCURRENTLY — the ledger's check-and-apply is one
+-- transaction), but over terminal rows only, which is the smaller set.
+create index if not exists cairnq_tasks_queue_completed_idx
+    on cairnq_tasks (queue, completed_at_ms)
+    where status in ('succeeded', 'failed', 'canceled');
+
+update cairnq_meta set value = '9' where key = 'schema_version';

package/dist/_protocol/migrations/postgres/0010_drop_status_index.sql

@@ -0,0 +1,29 @@
+-- Drop cairnq_tasks_status_idx, which nothing can use.
+--
+-- 0001 shipped it for list's status filter. 0007 later added
+-- (status, completed_at_ms) for purge, and a one-column index on the same
+-- leading column is strictly contained in that: any lookup the narrow one could
+-- serve, the wider one serves from its prefix. Confirmed on the statements as
+-- they run — with the status filter specialized to an equality, SQLite picks
+-- cairnq_tasks_status_completed_idx for list and for purge, and never the
+-- narrow index, on a 20k-row table with statistics.
+--
+-- Until specialization existed neither was reachable at all, so this was
+-- invisible: both indexes looked equally unused, and dropping either looked
+-- equally safe or unsafe. It is only once the filters reach an index that one
+-- of them is demonstrably the one reached.
+--
+-- The write cost is what makes it worth removing rather than leaving: every
+-- insert and every status transition — submit, claim, each settle, each retry —
+-- maintains it, which is the hottest write path there is, for a structure no
+-- read consults. The other three of 0001's filter indexes (name, root_id,
+-- correlation_id) stay: each is the only index that serves its filter, and each
+-- is demonstrably read now.
+--
+-- Dropping an index needs no CONCURRENTLY on either dialect and holds a lock
+-- only long enough to unlink it, so unlike 0008 this is not an upgrade window
+-- to plan around. An older SDK is unaffected: it never named the index, and the
+-- statement that used to want it could not reach it anyway.
+drop index if exists cairnq_tasks_status_idx;
+
+update cairnq_meta set value = '10' where key = 'schema_version';

package/dist/_protocol/migrations/sqlite/0009_purge_queue_index.sql

@@ -0,0 +1,39 @@
+-- Give the retention sweep a queue dimension it can actually read.
+--
+-- purge gained an optional `:queue` filter, and without an index for it queue is
+-- a residual on cairnq_tasks_completed_idx (completed_at_ms) or
+-- cairnq_tasks_status_completed_idx (status, completed_at_ms): the scan walks in
+-- completion order and throws away every row belonging to another queue. `limit`
+-- bounds what comes back, not what is read — and the shape that makes the filter
+-- worth having in the first place is exactly the worst case for it. One store
+-- carrying an RPC queue kept for minutes and a durable queue kept for a week is
+-- the cross-language coordination this project recommends; sweeping the RPC
+-- queue then means walking the week's worth of older rows the other queue is
+-- deliberately holding onto, over and over, once per batch.
+--
+-- Partial, on the terminal statuses, for two reasons. It is the smaller half of
+-- the table — a busy queue's live rows never enter it — and, more to the point,
+-- rows enter it only when a task settles, so the index is not a tax on the claim
+-- path the way a full index on (queue, ...) would be. purge.sql always carries
+-- the literal `status in ('succeeded','failed','canceled')`, whether or not the
+-- caller narrowed to one status, so the predicate matches exactly and the
+-- planner never has to prove anything subtler to use it.
+--
+-- Measured on SQLite 3.39.4, 20k rows over two queues and four statuses, with
+-- 0002's and 0007's indexes present alongside it: every filter combination purge
+-- can issue is served by one index scan with the ORDER BY satisfied from the
+-- index (no temp b-tree), and the two pre-existing shapes — unfiltered, and
+-- status-only — still choose their old indexes, so nothing that worked before
+-- got slower. Postgres is reasoned from the same shape rather than benchmarked;
+-- see 0008 for why that caveat keeps appearing.
+--
+-- Unlike 0008 this only CREATES an index, so an older SDK is unaffected: it
+-- never passes `:queue`, its statements are unchanged, and it pays only the
+-- write-side cost of an index it does not read. The build still holds a lock for
+-- as long as it takes (no CONCURRENTLY — the ledger's check-and-apply is one
+-- transaction), but over terminal rows only, which is the smaller set.
+create index if not exists cairnq_tasks_queue_completed_idx
+    on cairnq_tasks (queue, completed_at_ms)
+    where status in ('succeeded', 'failed', 'canceled');
+
+update cairnq_meta set value = '9' where key = 'schema_version';

package/dist/_protocol/migrations/sqlite/0010_drop_status_index.sql

@@ -0,0 +1,29 @@
+-- Drop cairnq_tasks_status_idx, which nothing can use.
+--
+-- 0001 shipped it for list's status filter. 0007 later added
+-- (status, completed_at_ms) for purge, and a one-column index on the same
+-- leading column is strictly contained in that: any lookup the narrow one could
+-- serve, the wider one serves from its prefix. Confirmed on the statements as
+-- they run — with the status filter specialized to an equality, SQLite picks
+-- cairnq_tasks_status_completed_idx for list and for purge, and never the
+-- narrow index, on a 20k-row table with statistics.
+--
+-- Until specialization existed neither was reachable at all, so this was
+-- invisible: both indexes looked equally unused, and dropping either looked
+-- equally safe or unsafe. It is only once the filters reach an index that one
+-- of them is demonstrably the one reached.
+--
+-- The write cost is what makes it worth removing rather than leaving: every
+-- insert and every status transition — submit, claim, each settle, each retry —
+-- maintains it, which is the hottest write path there is, for a structure no
+-- read consults. The other three of 0001's filter indexes (name, root_id,
+-- correlation_id) stay: each is the only index that serves its filter, and each
+-- is demonstrably read now.
+--
+-- Dropping an index needs no CONCURRENTLY on either dialect and holds a lock
+-- only long enough to unlink it, so unlike 0008 this is not an upgrade window
+-- to plan around. An older SDK is unaffected: it never named the index, and the
+-- statement that used to want it could not reach it anyway.
+drop index if exists cairnq_tasks_status_idx;
+
+update cairnq_meta set value = '10' where key = 'schema_version';

package/dist/_protocol/sql/postgres/claimable_probe.sql

@@ -0,0 +1,47 @@
+-- Read-only check: is there anything worth opening the claim transaction for?
+-- Run before claim so an idle worker's poll costs one statement instead of a
+-- transaction. Mirrors claim.sql's filters, so the probe never promises work
+-- claim will skip. The expired-lease arm stays unfiltered on purpose: recovering
+-- a dead worker's task is every worker's job, whatever names it happens to
+-- handle.
+--
+-- The SQLite twin exists for a reason that does not apply here — keeping idle
+-- workers off the single write lock — and this dialect went without one on that
+-- basis. What survives the difference is the rest of the poll: without a probe
+-- every empty poll still opens a transaction, runs recover_leases, and then runs
+-- one claim statement per self-limiting name. A worker declaring a dozen such
+-- names pays a dozen statements to learn there is nothing to do, and on this
+-- dialect the empty poll is the COMMON case precisely because LISTEN wakes the
+-- worker on the rare one.
+--
+-- Two separate EXISTS, not one select with an OR: an OR across two different
+-- index shapes gets no index at all (see migration 0008's note on the SQLite
+-- twin), while each EXISTS here chooses its own — cairnq_tasks_claim_idx for the
+-- queued arm, cairnq_tasks_lease_idx (0004, partial on running rows) for the
+-- lease arm — and stops at the first row it finds.
+--
+-- Time is clock_timestamp() wrapped in a scalar subselect, for the reason spelled
+-- out at length in recover_leases.sql: inlined, a VOLATILE function becomes a
+-- per-row filter and the scan degrades to reading every candidate row. Wrapped,
+-- it is an InitPlan evaluated once and usable as an index bound.
+--
+-- What this does NOT make free: the queued arm still walks the (queue, status)
+-- range looking for a due row when every row in it is backing off, the same cost
+-- an empty claim draw pays. The saving is the transaction and the other N-1
+-- statements, not the range scan.
+-- params: queues (text[]), names (text[] or null)
+select (
+    exists (
+        select 1 from cairnq_tasks
+        where status = 'queued'
+          and queue = any(:queues::text[])
+          and (:names::text[] is null or name = any(:names::text[]))
+          and run_at_ms <= (select (extract(epoch from clock_timestamp()) * 1000)::bigint)
+    )
+    or exists (
+        select 1 from cairnq_tasks
+        where status = 'running'
+          and lease_until_ms is not null
+          and lease_until_ms <= (select (extract(epoch from clock_timestamp()) * 1000)::bigint)
+    )
+) as has_work;

package/dist/_protocol/sql/postgres/purge.sql

@@ -11,16 +11,36 @@
 -- live task. Locking the rows in the subselect freezes them terminal until the
 -- delete commits; a concurrent retry then re-evaluates against the deleted row
 -- and correctly finds nothing.
--- The status/name filters are optional (pass NULL to skip; `::text` pins the
--- param's type, as in list.sql): retention needs are tiered — a succeeded row
--- is spent once its result is consumed, while a failed one is worth keeping
--- for diagnosis — and without them the shortest-lived tier sets the retention
--- for every row.
--- params: older_than_ms, status, name, limit
+-- The queue/status/name filters are optional (pass NULL to skip; `::text` pins
+-- the param's type, as in list.sql): retention needs are tiered — a succeeded row is spent once its result is
+-- consumed, while a failed one is worth keeping for diagnosis — and without them
+-- the shortest-lived tier sets the retention for every row. `queue` is the same
+-- argument one level up: a single installation is how this project recommends
+-- two languages coordinate, so it routinely carries two workloads whose rows
+-- have nothing to do with each other's lifetimes — an RPC result read once and a
+-- durable job's log kept for a week. Migration 0009 adds the index that makes
+-- the queue filter read only its own queue's rows rather than skipping past
+-- every other queue's.
+-- Three specializations exist for the two filters that DO have indexes —
+-- purge_one_queue.sql, purge_one_status.sql, purge_one_queue_one_status.sql —
+-- and the SDK picks one per call. This file's optional form is the one it uses
+-- when neither filter is set, because `(:p is null or col = :p)` is planned
+-- before the parameter has a value: SQLite must plan both branches, reaches no
+-- index at all, and walks every row past the cutoff in completion order.
+--
+-- Both dialects ship every variant. Postgres does not need them — it re-plans
+-- with the parameter values for a statement's first executions and folds the
+-- null branch away — but a caller that had to know which dialect indexes which
+-- form would be a worse contract than four extra files.
+--
+-- :name has no specialization: no index covers it, so it is a residual predicate
+-- either way and an equality form would buy nothing.
+-- params: older_than_ms, queue, status, name, limit
 delete from cairnq_tasks
 where id in (
     select id from cairnq_tasks
     where status in ('succeeded', 'failed', 'canceled')
+      and (:queue::text is null or queue = :queue)
       and (:status::text is null or status = :status)
       and (:name::text is null or name = :name)
       and completed_at_ms is not null

package/dist/_protocol/sql/postgres/stats.sql

@@ -1,8 +1,23 @@
--- Queue depth at a glance: task counts grouped by queue and status. Read-only.
+-- Task counts grouped by queue and status. Read-only.
 -- A queue appears only while it has rows — terminal tasks count until purge
 -- removes them. The SDK zero-fills the statuses a queue has no rows in.
--- params: (none)
+--
+-- :queue is optional (pass NULL for every queue; `::text` pins the param's type,
+-- as in list.sql). Unfiltered, this reads every row in the table, so its cost
+-- grows with everything the installation has ever run — and one store carrying
+-- two workloads is the coordination cairnq recommends, so a caller asking about
+-- its own queue should not pay for the other's backlog. Filtered to one queue it
+-- can be served from cairnq_tasks_claim_idx's (queue, status) prefix instead.
+--
+-- Filtered or not, this still COUNTS: the cost is proportional to the rows being
+-- counted, which is the whole queue, terminal rows included. That is fine for a
+-- dashboard and wrong for a poll loop — queue_depth.sql is the bounded question,
+-- and the one to ask on an interval.
+-- stats_one_queue.sql is the equality form the SDK uses when a queue is
+-- named; see purge.sql for why the optional filter here cannot be indexed.
+-- params: queue
 select queue, status, count(*) as count
 from cairnq_tasks
+where (:queue::text is null or queue = :queue)
 group by queue, status
 order by queue asc, status asc;

package/dist/_protocol/sql/sqlite/purge.sql

@@ -5,15 +5,36 @@
 -- task goes with it via cairnq_task_keys' ON DELETE CASCADE.
 -- The LIMIT lives in a subquery: plain `delete ... limit` needs a non-default
 -- SQLite build option.
--- The status/name filters are optional (pass NULL to skip, as in list.sql):
--- retention needs are tiered — a succeeded row is spent once its result is
--- consumed, while a failed one is worth keeping for diagnosis — and without
--- them the shortest-lived tier sets the retention for every row.
--- params: before_ms, status, name, limit
+-- The queue/status/name filters are optional (pass NULL to skip, as in
+-- list.sql): retention needs are tiered — a succeeded row is spent once its
+-- result is consumed, while a failed one is worth keeping for diagnosis — and
+-- without them the shortest-lived tier sets the retention for every row.
+-- `queue` is the same argument one level up: a single installation is how this
+-- project recommends two languages coordinate, so it routinely carries two
+-- workloads whose rows have nothing to do with each other's lifetimes — an RPC
+-- result read once and a durable job's log kept for a week. Migration 0009 adds
+-- the index that makes the queue filter read only its own queue's rows rather
+-- than skipping past every other queue's.
+-- Three specializations exist for the two filters that DO have indexes —
+-- purge_one_queue.sql, purge_one_status.sql, purge_one_queue_one_status.sql —
+-- and the SDK picks one per call. This file's optional form is the one it uses
+-- when neither filter is set, because `(:p is null or col = :p)` is planned
+-- before the parameter has a value: SQLite must plan both branches, reaches no
+-- index at all, and walks every row past the cutoff in completion order.
+--
+-- Both dialects ship every variant. Postgres does not need them — it re-plans
+-- with the parameter values for a statement's first executions and folds the
+-- null branch away — but a caller that had to know which dialect indexes which
+-- form would be a worse contract than four extra files.
+--
+-- :name has no specialization: no index covers it, so it is a residual predicate
+-- either way and an equality form would buy nothing.
+-- params: before_ms, queue, status, name, limit
 delete from cairnq_tasks
 where id in (
     select id from cairnq_tasks
     where status in ('succeeded', 'failed', 'canceled')
+      and (:queue is null or queue = :queue)
       and (:status is null or status = :status)
       and (:name is null or name = :name)
       and completed_at_ms is not null

package/dist/_protocol/sql/sqlite/stats.sql

@@ -1,8 +1,23 @@
--- Queue depth at a glance: task counts grouped by queue and status. Read-only.
+-- Task counts grouped by queue and status. Read-only.
 -- A queue appears only while it has rows — terminal tasks count until purge
 -- removes them. The SDK zero-fills the statuses a queue has no rows in.
--- params: (none)
+--
+-- :queue is optional (pass NULL for every queue). Unfiltered, this reads every
+-- row in the table, so its cost grows with everything the installation has ever
+-- run — and one store carrying two workloads is the coordination cairnq
+-- recommends, so a caller asking about its own queue should not pay for the
+-- other's backlog. Filtered to one queue it can be served from
+-- cairnq_tasks_claim_idx's (queue, status) prefix instead.
+--
+-- Filtered or not, this still COUNTS: the cost is proportional to the rows being
+-- counted, which is the whole queue, terminal rows included. That is fine for a
+-- dashboard and wrong for a poll loop — queue_depth.sql is the bounded question,
+-- and the one to ask on an interval.
+-- stats_one_queue.sql is the equality form the SDK uses when a queue is
+-- named; see purge.sql for why the optional filter here cannot be indexed.
+-- params: queue
 select queue, status, count(*) as count
 from cairnq_tasks
+where (:queue is null or queue = :queue)
 group by queue, status
 order by queue asc, status asc;

package/dist/client.d.ts

@@ -72,11 +72,20 @@ export declare class CairnQ {
     /** Delete terminal tasks that finished more than `olderThanMs` ago and return
      * their ids. Nothing else in CairnQ removes rows, so a long-lived database
      * needs this on a schedule. Each call is bounded by `limit` to keep the write
-     * short; loop until it returns fewer than `limit`. */
+     * short; loop until it returns fewer than `limit`.
+     *
+     * `queue` / `status` / `name` narrow the sweep — one installation carrying two
+     * workloads needs a retention per workload, not one for the whole database. */
     purge(input?: PurgeInput): Promise<string[]>;
     /** Task counts per queue, keyed by status and zero-filled across all statuses
-     * — `(await stats()).default.queued` is the backlog of a queue. */
-    stats(): Promise<Record<string, Record<TaskStatus, number>>>;
+     * — `(await stats()).default.queued` is the backlog of a queue. `queue` narrows
+     * the aggregate to one queue, which is also what keeps a caller from paying for
+     * the other workloads sharing the installation; a named queue is always
+     * present, zero-filled if it has no rows.
+     *
+     * This counts rows, so it costs what it counts — use it for a dashboard, and
+     * poll `queueDepth()` instead, which is bounded. */
+    stats(queue?: string): Promise<Record<string, Record<TaskStatus, number>>>;
     /**
      * Call `onSignal` when the tasks on `queues` may have changed. Returns an
      * unsubscribe.

package/dist/client.js

@@ -92,14 +92,23 @@ export class CairnQ {
     /** Delete terminal tasks that finished more than `olderThanMs` ago and return
      * their ids. Nothing else in CairnQ removes rows, so a long-lived database
      * needs this on a schedule. Each call is bounded by `limit` to keep the write
-     * short; loop until it returns fewer than `limit`. */
+     * short; loop until it returns fewer than `limit`.
+     *
+     * `queue` / `status` / `name` narrow the sweep — one installation carrying two
+     * workloads needs a retention per workload, not one for the whole database. */
     purge(input) {
         return this._store.purge(input);
     }
     /** Task counts per queue, keyed by status and zero-filled across all statuses
-     * — `(await stats()).default.queued` is the backlog of a queue. */
-    stats() {
-        return this._store.stats();
+     * — `(await stats()).default.queued` is the backlog of a queue. `queue` narrows
+     * the aggregate to one queue, which is also what keeps a caller from paying for
+     * the other workloads sharing the installation; a named queue is always
+     * present, zero-filled if it has no rows.
+     *
+     * This counts rows, so it costs what it counts — use it for a dashboard, and
+     * poll `queueDepth()` instead, which is bounded. */
+    stats(queue) {
+        return this._store.stats(queue);
     }
     /**
      * Call `onSignal` when the tasks on `queues` may have changed. Returns an

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { CallOptions, ClientOptions, SubmitOptions, WaitOptions } from "./c
 export { QueueDepthGate } from "./backpressure.js";
 export type { BackpressureOptions, QueueDepthLimit } from "./backpressure.js";
 export { RetentionSweeper } from "./retention.js";
-export type { RetentionCutoffs, RetentionOptions } from "./retention.js";
+export type { RetentionCutoffs, RetentionOptions, RetentionRule } from "./retention.js";
 export { Worker } from "./worker.js";
 export type { BatchHandler, Handler, TypedHandler, WorkerOptions } from "./worker.js";
 export { TaskContext } from "./context.js";

package/dist/retention.d.ts

@@ -3,17 +3,46 @@ import { type TaskStore } from "./store/base.js";
 /** Per-status cutoffs. A status left out is never swept — granular retention is
  * an explicit statement of what may go, not a default for what wasn't named. */
 export type RetentionCutoffs = Partial<Record<TerminalStatus, number>>;
+/**
+ * One "these rows may go after this long" statement. Each field left out widens
+ * what the rule covers; `olderThanMs` is the only required one.
+ *
+ * A rule is one `purge` call's filters, so the fields are exactly `PurgeInput`'s
+ * — deliberately, since a rule the sweeper can express but the store cannot
+ * enforce would be a lie about what is being deleted.
+ */
+export interface RetentionRule {
+    /** Only this queue. Absent means every queue. */
+    queue?: string;
+    /** Only this terminal status. Absent means all three. */
+    status?: TerminalStatus;
+    /** Only this task name. Absent means every name. */
+    name?: string;
+    /** How long a row matching this rule is kept after it finished. */
+    olderThanMs: number;
+}
 export interface RetentionOptions {
     /**
      * How long a terminal task is kept after it finished. Required: there is no
      * safe default for how long someone else's results stay readable.
      *
-     * A number keeps every terminal status the same time. Retention needs are
-     * often tiered — a succeeded row is spent once its result is consumed, while
-     * a failed one is worth keeping for diagnosis — so a per-status map sets a
-     * cutoff per status instead: `{ succeeded: 300_000, failed: 86_400_000 }`.
+     * Three forms, widening as the deployment does:
+     *
+     * - A number keeps every terminal row the same time.
+     * - A per-status map tiers by outcome — a succeeded row is spent once its
+     *   result is consumed, a failed one is worth keeping for diagnosis:
+     *   `{ succeeded: 300_000, failed: 86_400_000 }`. A status left out is never
+     *   swept.
+     * - An array of rules tiers by anything `purge` can filter on, which is what a
+     *   store shared by two workloads needs — the recommended way for two
+     *   languages to coordinate is one installation, and an RPC queue read once
+     *   has nothing in common with a durable queue kept for a week:
+     *   `[{ queue: "rpc", olderThanMs: 300_000 },
+     *      { queue: "jobs", status: "failed", olderThanMs: 604_800_000 }]`.
+     *   Rules are independent, each its own sweep — nothing a rule does not match
+     *   is swept, and rules that overlap simply delete the same row once.
      */
-    olderThanMs: number | RetentionCutoffs;
+    olderThanMs: number | RetentionCutoffs | RetentionRule[];
     /** Time between sweeps. Default 3_600_000 (one hour). */
     intervalMs?: number;
     /** Rows deleted per statement while draining. Default 1_000. */
@@ -63,7 +92,8 @@ export declare class RetentionSweeper {
     private readonly intervalMs;
     /** Rows per purge statement while draining — see DEFAULT_LIMIT. */
     private readonly limit;
-    /** One purge per cutoff: a lone entry for a number, one per status for a map. */
+    /** One purge per rule: a lone entry for a number, one per status for a map,
+     * one per element for an array. */
     private readonly purgeInputs;
     constructor(store: TaskStore, opts: RetentionOptions);
     start(): void;

package/dist/retention.js

@@ -6,6 +6,19 @@ const DEFAULT_INTERVAL_MS = 3_600_000;
 /** Rows per purge statement. The same bound `purge` defaults to: big enough that
  * a backlog drains in few statements, small enough that each is a short write. */
 const DEFAULT_LIMIT = 1_000;
+/** The three `olderThanMs` forms as the one form the sweep runs on. The number
+ * and the per-status map are the rule array's common cases spelled shorter, so
+ * they are widened here rather than handled separately downstream. */
+function toRules(spec) {
+    if (typeof spec === "number")
+        return [{ olderThanMs: spec }];
+    if (Array.isArray(spec))
+        return spec;
+    return Object.entries(spec).map(([status, olderThanMs]) => ({
+        status,
+        olderThanMs,
+    }));
+}
 /**
  * Deletes terminal tasks on a schedule, for as long as the handle is open.
  *
@@ -44,7 +57,8 @@ export class RetentionSweeper {
     intervalMs;
     /** Rows per purge statement while draining — see DEFAULT_LIMIT. */
     limit;
-    /** One purge per cutoff: a lone entry for a number, one per status for a map. */
+    /** One purge per rule: a lone entry for a number, one per status for a map,
+     * one per element for an array. */
     purgeInputs;
     constructor(store, opts) {
         this.store = store;
@@ -54,20 +68,15 @@ export class RetentionSweeper {
             throw new Error(`retention.intervalMs must be >= 1, got ${this.intervalMs}`);
         }
         this.limit = opts.limit ?? DEFAULT_LIMIT;
-        const cutoffs = typeof opts.olderThanMs === "number"
-            ? [[undefined, opts.olderThanMs]]
-            : Object.entries(opts.olderThanMs);
-        // An empty map retains nothing and sweeps nothing — almost certainly a bug
-        // upstream of this call, so refuse it rather than silently never purging.
-        if (!cutoffs.length) {
-            throw new Error("retention.olderThanMs must name at least one status");
+        const rules = toRules(opts.olderThanMs);
+        // An empty map or array retains nothing and sweeps nothing — almost
+        // certainly a bug upstream of this call, so refuse it rather than silently
+        // never purging.
+        if (!rules.length) {
+            throw new Error("retention.olderThanMs must name at least one rule");
         }
         this.arm();
-        this.purgeInputs = cutoffs.map(([status, ms]) => ({
-            olderThanMs: ms,
-            status,
-            limit: this.limit,
-        }));
+        this.purgeInputs = rules.map((rule) => ({ ...rule, limit: this.limit }));
         // Fail fast on the store's own purge rules (terminal status, cutoff >= 0):
         // the sweep runs an hour from now, and its errors only surface via onError.
         for (const input of this.purgeInputs)

package/dist/store/base.d.ts

@@ -45,6 +45,14 @@ export interface ListInput {
 export declare function validatePurgeInput(input: PurgeInput): void;
 export interface PurgeInput {
     olderThanMs?: number;
+    /** Restrict the sweep to one queue. Absent means every queue.
+     *
+     * The same tiering argument as `status`, one level up: a single installation
+     * is how this project recommends two languages coordinate, so it routinely
+     * carries two workloads whose rows have nothing to do with each other's
+     * lifetimes — an RPC result read once, a durable job's log kept for a week.
+     * Without this the shorter-lived queue sets the retention for both. */
+    queue?: string;
     /** Restrict the sweep to one terminal status. Retention needs are tiered —
      * succeeded rows are spent once their result is consumed, failed ones are
      * worth keeping for diagnosis — and without this the shortest-lived tier
@@ -62,6 +70,24 @@ export declare const LEASE_EXPIRED_ERROR_JSON: string;
 export declare const COMMENT: RegExp;
 /** A `:name` placeholder. The lookbehind spares Postgres `::type` casts. */
 export declare const NAMED: RegExp;
+/**
+ * The statement as it should run for these arguments: every optional filter the
+ * caller actually supplied rewritten to an equality.
+ *
+ * `(:p is null or col = :p)` cannot use an index. SQLite plans a statement when
+ * it is prepared, before any parameter has a value, so it must plan for both
+ * branches and settles for a scan; that is not a tuning detail but the whole
+ * difference between `list(root_id=…)` seeking cairnq_tasks_root_idx and reading
+ * the table. Postgres re-plans with the values for a statement's first
+ * executions and folds the branch away on its own, so this is a no-op there —
+ * but it costs nothing, and one behaviour is easier to reason about than two.
+ *
+ * Filters the caller did NOT supply are left alone rather than removed: a
+ * constant-true term costs a per-row evaluation the planner mostly discards, and
+ * leaving them keeps the parameter set identical to the file's, so the binding
+ * path below needs to know nothing about any of this.
+ */
+export declare function specialize(sql: string, params: Params): string;
 /**
  * The parameter names a statement binds, in first-appearance order.
  *
@@ -161,11 +187,19 @@ export declare abstract class TaskStore {
      */
     protected warmPush?(): void;
     /**
-     * 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
-     * writers, so it just says yes.
+     * Whether it is worth opening the claim transaction at all — the read-only
+     * `claimable_probe`, which every dialect ships.
+     *
+     * Both dialects want it, for different reasons: SQLite so an idle worker never
+     * takes its single write lock and idle workers stop serializing against each
+     * other, Postgres so an empty poll costs one statement instead of a
+     * transaction plus `recover_leases` plus one claim statement per
+     * self-limiting name. Neither reason is dialect-specific enough to live in a
+     * dialect: what differs is the SQL, which is where the protocol keeps dialect
+     * differences already. A backend whose probe would cost more than the claim it
+     * guards overrides this with `return true`.
      */
-    protected hasClaimableWork(_params: Params): Promise<boolean>;
+    protected hasClaimableWork(params: Params): Promise<boolean>;
     /** Resolves when a task may have become claimable on one of `queues`. The
      * timer is unref'd: the worker races this against its own stop-aware, ref'd
      * sleep, so it must neither hold the process open nor need clearing. */
@@ -220,6 +254,9 @@ export declare abstract class TaskStore {
      * their ids. Nothing else removes rows, so a long-lived database needs this
      * called periodically. Bounded by `limit` to keep each sweep a short write;
      * call it in a loop until it returns fewer than `limit`.
+     *
+     * `queue` / `status` / `name` narrow the sweep, which is what makes tiered
+     * retention expressible at all — see PurgeInput.
      */
     purge(input?: PurgeInput): Promise<string[]>;
     /**
@@ -227,8 +264,20 @@ export declare abstract class TaskStore {
      * `(await stats()).default.queued` is the backlog of a queue. A queue appears
      * only while it has rows; terminal tasks keep counting until `purge` removes
      * them.
+     *
+     * `queue` restricts the aggregate to one queue, which is also what stops the
+     * caller paying for every other queue's rows: one installation carrying two
+     * workloads is the coordination this project recommends, and the unfiltered
+     * form reads the whole table. A named queue is always present in the result,
+     * zero-filled if it has no rows at all — asking about a specific queue and
+     * getting `undefined` back would make every caller write the same fallback.
+     *
+     * Filtered or not, this COUNTS, so it costs what it counts: a whole queue,
+     * terminal rows included. Right for a dashboard, wrong on an interval — poll
+     * `queueDepth`, which is bounded, and keep this for when the real numbers are
+     * the point.
      */
-    stats(): Promise<Record<string, Record<TaskStatus, number>>>;
+    stats(queue?: string): Promise<Record<string, Record<TaskStatus, number>>>;
     /**
      * Call `onSignal` when the tasks on `queues` may have changed — something was
      * queued, or something finished.