cairnq 0.11.0 → 0.12.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/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/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,22 @@
 -- 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.
+-- 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/purge_one_queue.sql

@@ -0,0 +1,42 @@
+-- purge, for a sweep bounded to ONE queue. Byte-for-byte purge.sql except that
+-- the queue filter is an equality instead of an optional `is null or` — a drift-
+-- guard test asserts precisely that, so treat purge.sql as the source and re-
+-- derive this file when it changes.
+--
+-- It exists because the optional-filter form cannot be indexed. SQLite plans a
+-- statement when it is prepared, before any parameter has a value, so `(:queue
+-- is null or queue = :queue)` has to be planned for BOTH branches and the
+-- planner falls back to cairnq_tasks_completed_idx, walking every row past the
+-- cutoff in completion order and discarding the ones belonging to another queue.
+-- `limit` bounds what comes back, never what is read, so the cost grows with
+-- exactly the rows the filter was meant to skip — and the deployment the filter
+-- exists for (one installation, two workloads on different clocks) is the one
+-- where those rows are most numerous. Measured on 20k rows over two queues and
+-- four statuses: the optional form chooses cairnq_tasks_completed_idx for every
+-- filter combination, the equality form chooses cairnq_tasks_queue_completed_idx
+-- (0009) and reads only its own range. Same reason claim.sql has
+-- specializations, same shape.
+--
+-- Postgres does not have SQLite's problem — it re-plans with the parameter
+-- values for the first executions and folds the null branch away — but it ships
+-- the variant too, because both dialects carry the same statement set and a
+-- caller that had to know which dialect indexes which form would be a worse
+-- contract.
+--
+-- :name stays optional in every variant: nothing indexes it, so it is a residual
+-- predicate either way and specializing it 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 = :queue
+      and (:status::text is null or status = :status)
+      and (:name::text is null or name = :name)
+      and completed_at_ms is not null
+      and completed_at_ms < (extract(epoch from now()) * 1000)::bigint - :older_than_ms
+    order by completed_at_ms asc
+    limit :limit
+    for update skip locked
+)
+returning id;

package/dist/_protocol/sql/postgres/purge_one_queue_one_status.sql

@@ -0,0 +1,42 @@
+-- purge, for a sweep bounded to one queue AND one terminal status. Byte-for-byte
+-- purge.sql except that the queue and status filters are an equality instead of
+-- an optional `is null or` — a drift-guard test asserts precisely that, so treat
+-- purge.sql as the source and re-derive this file when it changes.
+--
+-- It exists because the optional-filter form cannot be indexed. SQLite plans a
+-- statement when it is prepared, before any parameter has a value, so `(:queue
+-- is null or queue = :queue)` has to be planned for BOTH branches and the
+-- planner falls back to cairnq_tasks_completed_idx, walking every row past the
+-- cutoff in completion order and discarding the ones belonging to another queue.
+-- `limit` bounds what comes back, never what is read, so the cost grows with
+-- exactly the rows the filter was meant to skip — and the deployment the filter
+-- exists for (one installation, two workloads on different clocks) is the one
+-- where those rows are most numerous. Measured on 20k rows over two queues and
+-- four statuses: the optional form chooses cairnq_tasks_completed_idx for every
+-- filter combination, the equality form chooses cairnq_tasks_queue_completed_idx
+-- (0009) and reads only its own range. Same reason claim.sql has
+-- specializations, same shape.
+--
+-- Postgres does not have SQLite's problem — it re-plans with the parameter
+-- values for the first executions and folds the null branch away — but it ships
+-- the variant too, because both dialects carry the same statement set and a
+-- caller that had to know which dialect indexes which form would be a worse
+-- contract.
+--
+-- :name stays optional in every variant: nothing indexes it, so it is a residual
+-- predicate either way and specializing it 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 = :queue
+      and status = :status
+      and (:name::text is null or name = :name)
+      and completed_at_ms is not null
+      and completed_at_ms < (extract(epoch from now()) * 1000)::bigint - :older_than_ms
+    order by completed_at_ms asc
+    limit :limit
+    for update skip locked
+)
+returning id;

package/dist/_protocol/sql/postgres/purge_one_status.sql

@@ -0,0 +1,42 @@
+-- purge, for a sweep bounded to ONE terminal status. Byte-for-byte purge.sql
+-- except that the status filter is an equality instead of an optional `is null
+-- or` — a drift-guard test asserts precisely that, so treat purge.sql as the
+-- source and re-derive this file when it changes.
+--
+-- It exists because the optional-filter form cannot be indexed. SQLite plans a
+-- statement when it is prepared, before any parameter has a value, so `(:status
+-- is null or status = :status)` has to be planned for BOTH branches and the
+-- planner falls back to cairnq_tasks_completed_idx, walking every row past the
+-- cutoff in completion order and discarding the ones belonging to another
+-- status. `limit` bounds what comes back, never what is read, so the cost grows
+-- with exactly the rows the filter was meant to skip — and the deployment the
+-- filter exists for (one installation, two workloads on different clocks) is the
+-- one where those rows are most numerous. Measured on 20k rows over two queues
+-- and four statuses: the optional form chooses cairnq_tasks_completed_idx for
+-- every filter combination, the equality form chooses
+-- cairnq_tasks_status_completed_idx (0007) and reads only its own range. Same
+-- reason claim.sql has specializations, same shape.
+--
+-- Postgres does not have SQLite's problem — it re-plans with the parameter
+-- values for the first executions and folds the null branch away — but it ships
+-- the variant too, because both dialects carry the same statement set and a
+-- caller that had to know which dialect indexes which form would be a worse
+-- contract.
+--
+-- :name stays optional in every variant: nothing indexes it, so it is a residual
+-- predicate either way and specializing it 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 = :status
+      and (:name::text is null or name = :name)
+      and completed_at_ms is not null
+      and completed_at_ms < (extract(epoch from now()) * 1000)::bigint - :older_than_ms
+    order by completed_at_ms asc
+    limit :limit
+    for update skip locked
+)
+returning id;

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

@@ -1,8 +1,21 @@
--- 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.
+-- 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/postgres/stats_one_queue.sql

@@ -0,0 +1,21 @@
+-- stats, for a caller asking about ONE queue. Byte-for-byte stats.sql except
+-- that the queue filter is an equality instead of an optional `is null or` — a
+-- drift-guard test asserts precisely that, so treat stats.sql as the source and
+-- re-derive this file when it changes.
+--
+-- It exists for the same reason purge_one_queue.sql does. SQLite plans a
+-- statement before its parameters have values, so the optional form has to be
+-- planned for both branches: it reads the whole table (as a covering index
+-- scan) and groups it, which is exactly the cost narrowing to one queue was
+-- meant to avoid. The equality form seeks the (queue, status) prefix of
+-- cairnq_tasks_claim_idx and reads only that queue's entries.
+--
+-- This still COUNTS what it reports, so it costs what it counts: one queue's
+-- rows, terminal ones included. Narrower than the unfiltered form, still not a
+-- poll-loop question — queue_depth.sql is the bounded one.
+-- params: queue
+select queue, status, count(*) as count
+from cairnq_tasks
+where queue = :queue
+group by queue, status
+order by queue asc, status asc;

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

@@ -5,15 +5,22 @@
 -- 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.
+-- 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/purge_one_queue.sql

@@ -0,0 +1,41 @@
+-- purge, for a sweep bounded to ONE queue. Byte-for-byte purge.sql except that
+-- the queue filter is an equality instead of an optional `is null or` — a drift-
+-- guard test asserts precisely that, so treat purge.sql as the source and re-
+-- derive this file when it changes.
+--
+-- It exists because the optional-filter form cannot be indexed. SQLite plans a
+-- statement when it is prepared, before any parameter has a value, so `(:queue
+-- is null or queue = :queue)` has to be planned for BOTH branches and the
+-- planner falls back to cairnq_tasks_completed_idx, walking every row past the
+-- cutoff in completion order and discarding the ones belonging to another queue.
+-- `limit` bounds what comes back, never what is read, so the cost grows with
+-- exactly the rows the filter was meant to skip — and the deployment the filter
+-- exists for (one installation, two workloads on different clocks) is the one
+-- where those rows are most numerous. Measured on 20k rows over two queues and
+-- four statuses: the optional form chooses cairnq_tasks_completed_idx for every
+-- filter combination, the equality form chooses cairnq_tasks_queue_completed_idx
+-- (0009) and reads only its own range. Same reason claim.sql has
+-- specializations, same shape.
+--
+-- Postgres does not have SQLite's problem — it re-plans with the parameter
+-- values for the first executions and folds the null branch away — but it ships
+-- the variant too, because both dialects carry the same statement set and a
+-- caller that had to know which dialect indexes which form would be a worse
+-- contract.
+--
+-- :name stays optional in every variant: nothing indexes it, so it is a residual
+-- predicate either way and specializing it 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 = :queue
+      and (:status is null or status = :status)
+      and (:name is null or name = :name)
+      and completed_at_ms is not null
+      and completed_at_ms < :before_ms
+    order by completed_at_ms asc
+    limit :limit
+)
+returning id;

package/dist/_protocol/sql/sqlite/purge_one_queue_one_status.sql

@@ -0,0 +1,41 @@
+-- purge, for a sweep bounded to one queue AND one terminal status. Byte-for-byte
+-- purge.sql except that the queue and status filters are an equality instead of
+-- an optional `is null or` — a drift-guard test asserts precisely that, so treat
+-- purge.sql as the source and re-derive this file when it changes.
+--
+-- It exists because the optional-filter form cannot be indexed. SQLite plans a
+-- statement when it is prepared, before any parameter has a value, so `(:queue
+-- is null or queue = :queue)` has to be planned for BOTH branches and the
+-- planner falls back to cairnq_tasks_completed_idx, walking every row past the
+-- cutoff in completion order and discarding the ones belonging to another queue.
+-- `limit` bounds what comes back, never what is read, so the cost grows with
+-- exactly the rows the filter was meant to skip — and the deployment the filter
+-- exists for (one installation, two workloads on different clocks) is the one
+-- where those rows are most numerous. Measured on 20k rows over two queues and
+-- four statuses: the optional form chooses cairnq_tasks_completed_idx for every
+-- filter combination, the equality form chooses cairnq_tasks_queue_completed_idx
+-- (0009) and reads only its own range. Same reason claim.sql has
+-- specializations, same shape.
+--
+-- Postgres does not have SQLite's problem — it re-plans with the parameter
+-- values for the first executions and folds the null branch away — but it ships
+-- the variant too, because both dialects carry the same statement set and a
+-- caller that had to know which dialect indexes which form would be a worse
+-- contract.
+--
+-- :name stays optional in every variant: nothing indexes it, so it is a residual
+-- predicate either way and specializing it 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 = :queue
+      and status = :status
+      and (:name is null or name = :name)
+      and completed_at_ms is not null
+      and completed_at_ms < :before_ms
+    order by completed_at_ms asc
+    limit :limit
+)
+returning id;

package/dist/_protocol/sql/sqlite/purge_one_status.sql

@@ -0,0 +1,41 @@
+-- purge, for a sweep bounded to ONE terminal status. Byte-for-byte purge.sql
+-- except that the status filter is an equality instead of an optional `is null
+-- or` — a drift-guard test asserts precisely that, so treat purge.sql as the
+-- source and re-derive this file when it changes.
+--
+-- It exists because the optional-filter form cannot be indexed. SQLite plans a
+-- statement when it is prepared, before any parameter has a value, so `(:status
+-- is null or status = :status)` has to be planned for BOTH branches and the
+-- planner falls back to cairnq_tasks_completed_idx, walking every row past the
+-- cutoff in completion order and discarding the ones belonging to another
+-- status. `limit` bounds what comes back, never what is read, so the cost grows
+-- with exactly the rows the filter was meant to skip — and the deployment the
+-- filter exists for (one installation, two workloads on different clocks) is the
+-- one where those rows are most numerous. Measured on 20k rows over two queues
+-- and four statuses: the optional form chooses cairnq_tasks_completed_idx for
+-- every filter combination, the equality form chooses
+-- cairnq_tasks_status_completed_idx (0007) and reads only its own range. Same
+-- reason claim.sql has specializations, same shape.
+--
+-- Postgres does not have SQLite's problem — it re-plans with the parameter
+-- values for the first executions and folds the null branch away — but it ships
+-- the variant too, because both dialects carry the same statement set and a
+-- caller that had to know which dialect indexes which form would be a worse
+-- contract.
+--
+-- :name stays optional in every variant: nothing indexes it, so it is a residual
+-- predicate either way and specializing it 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 = :status
+      and (:name is null or name = :name)
+      and completed_at_ms is not null
+      and completed_at_ms < :before_ms
+    order by completed_at_ms asc
+    limit :limit
+)
+returning id;

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

@@ -1,8 +1,21 @@
--- 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.
+-- 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/_protocol/sql/sqlite/stats_one_queue.sql

@@ -0,0 +1,21 @@
+-- stats, for a caller asking about ONE queue. Byte-for-byte stats.sql except
+-- that the queue filter is an equality instead of an optional `is null or` — a
+-- drift-guard test asserts precisely that, so treat stats.sql as the source and
+-- re-derive this file when it changes.
+--
+-- It exists for the same reason purge_one_queue.sql does. SQLite plans a
+-- statement before its parameters have values, so the optional form has to be
+-- planned for both branches: it reads the whole table (as a covering index
+-- scan) and groups it, which is exactly the cost narrowing to one queue was
+-- meant to avoid. The equality form seeks the (queue, status) prefix of
+-- cairnq_tasks_claim_idx and reads only that queue's entries.
+--
+-- This still COUNTS what it reports, so it costs what it counts: one queue's
+-- rows, terminal ones included. Narrower than the unfiltered form, still not a
+-- poll-loop question — queue_depth.sql is the bounded one.
+-- params: queue
+select queue, status, count(*) as count
+from cairnq_tasks
+where 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";