cairnq 0.10.0 → 0.11.0

package/dist/_protocol/migrations/postgres/0001_init.sql

@@ -49,6 +49,8 @@ create table if not exists cairnq_tasks (
 -- desc, created_at_ms asc (run_at_ms applied as a residual filter). Only
 -- claim_one_queue.sql can read it in claim order; claim.sql's array-valued queue
 -- filter forces a sort, and past a few thousand queued rows a sequential scan.
+-- The shape as first shipped; migration 0008 rebuilds it around run_at_ms and
+-- says why.
 create index if not exists cairnq_tasks_claim_idx
     on cairnq_tasks (queue, status, priority desc, created_at_ms);
 create index if not exists cairnq_tasks_status_idx on cairnq_tasks (status);

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

@@ -19,6 +19,8 @@
 -- existing large cairnq_tasks this takes a write lock for the build. Deploying
 -- into a busy database is the case to watch; build it by hand with CONCURRENTLY
 -- first if that matters, and this statement then becomes a no-op.
+-- The measurements above belong to the shape defined here; migration 0008
+-- rebuilds it around run_at_ms and carries the current numbers.
 create index if not exists cairnq_tasks_claim_name_idx
     on cairnq_tasks (queue, status, name, priority desc, created_at_ms);
 

package/dist/_protocol/migrations/postgres/0008_claim_due_index.sql

@@ -0,0 +1,68 @@
+-- Serve the claim's whole ORDER BY from the index, and order by when a task
+-- became DUE rather than by when it was created.
+--
+-- The two halves are one fix. `run_at_ms <= :now_ms` was a residual on the old
+-- (queue, status, priority desc, created_at_ms) index, and a not-yet-due row —
+-- a retry waiting out its backoff, a task submitted with a delay — sorts by the
+-- created_at it has always had, which puts it AHEAD of the rows that are
+-- actually claimable. So every draw walked the whole backoff pile before
+-- reaching anything it could take, inside the transaction that holds the claim.
+-- The pile is largest exactly when a downstream dependency has just failed and
+-- thousands of tasks are backing off together.
+--
+-- Ordering by run_at_ms instead puts every not-yet-due row AFTER the due ones,
+-- so the scan reaches its rows first, and appending `id` lets the index carry the
+-- tie-break as well, which is what lets the planner satisfy the ORDER BY from the
+-- index alone.
+--
+-- The measurements behind this live in the SQLite twin of this file, and they are
+-- SQLite numbers: no Postgres was available where this was written, so this side
+-- is reasoned from the same index shape rather than benchmarked. What holds
+-- across both is the ordering — the due rows are now at the front of the index
+-- range instead of behind every not-yet-due one.
+--
+-- What this does NOT fix, in either dialect: an empty draw still walks the whole
+-- range looking for rows that are not there, and `claimable_probe` — whose
+-- two-armed EXISTS cannot use the index at all — is untouched. A queue deep in
+-- backoff still costs a worker real time per poll.
+--
+-- For a task that was never delayed or retried the change is invisible in
+-- practice: insert_task sets run_at_ms = now + delay, so the two columns hold the
+-- same millisecond for an ordinary submit. (On Postgres "the same millisecond" is
+-- not quite an identity — insert_task evaluates clock_timestamp() once per column
+-- and it advances within a statement, so a submit landing on a millisecond
+-- boundary can differ by 1ms. That reorders two tasks submitted in the same
+-- millisecond, which claim.sql already calls decided by the id's random half
+-- rather than by submit order.) It changes real ordering only for tasks whose
+-- delivery was deferred, and for those "oldest due first" is the fairer answer —
+-- a task that failed and backed off should not cut ahead of everything submitted
+-- while it waited, which is what its original created_at_ms bought it.
+--
+-- Both indexes are rebuilt inside the migration's transaction, which holds a
+-- lock that blocks writes to cairnq_tasks while they build — seconds on a large
+-- table. There is no CONCURRENTLY here: it cannot run inside a transaction, and
+-- the ledger's check-and-apply is one. Upgrade a large deployment in a window
+-- where that pause is affordable.
+--
+-- Same names, new definitions: these indexes ARE "the ones the claim reads", and
+-- every reference to them in the SQL comments and PROTOCOL.md still points at
+-- the right object.
+--
+-- An SDK older than this migration keeps working: it orders by created_at_ms,
+-- finds no index in that order, and sorts. Slower, exactly where this migration
+-- is faster — but note the sharper consequence while a fleet is mixed. Two SDK
+-- versions against one database then disagree about which task is NEXT for any
+-- delayed or retried work: each takes a valid claimable task, no task is lost or
+-- run twice, but the documented claim order holds only within one version. That
+-- is a difference in fairness, not in correctness, which is why protocol_version
+-- stays at 1 — and it is a reason to keep the mixed window short.
+drop index if exists cairnq_tasks_claim_idx;
+create index cairnq_tasks_claim_idx
+    on cairnq_tasks (queue, status, priority desc, run_at_ms, id);
+
+-- The per-name twin (see 0006), rebuilt on the same principle.
+drop index if exists cairnq_tasks_claim_name_idx;
+create index cairnq_tasks_claim_name_idx
+    on cairnq_tasks (queue, status, name, priority desc, run_at_ms, id);
+
+update cairnq_meta set value = '8' where key = 'schema_version';

package/dist/_protocol/migrations/sqlite/0001_init.sql

@@ -48,6 +48,8 @@ create table if not exists cairnq_tasks (
 -- queue+status then the ORDER BY columns is what lets claim_one_queue.sql read
 -- rows in claim order; claim.sql's list-valued queue filter has to merge several
 -- ranges of this index, so it sorts instead.
+-- The shape as first shipped; migration 0008 rebuilds it around run_at_ms and
+-- says why.
 create index if not exists cairnq_tasks_claim_idx
     on cairnq_tasks (queue, status, priority desc, created_at_ms);
 create index if not exists cairnq_tasks_status_idx on cairnq_tasks (status);

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

@@ -20,6 +20,8 @@
 -- bloom filter over the subquery and falls back to cairnq_tasks_claim_idx
 -- (measured 1446us, i.e. no improvement at all). That is why the per-name
 -- statements exist as separate files rather than the shared one being reused.
+-- The measurements above belong to the shape defined here; migration 0008
+-- rebuilds it around run_at_ms and carries the current numbers.
 create index if not exists cairnq_tasks_claim_name_idx
     on cairnq_tasks (queue, status, name, priority desc, created_at_ms);
 

package/dist/_protocol/migrations/sqlite/0008_claim_due_index.sql

@@ -0,0 +1,84 @@
+-- Serve the claim's whole ORDER BY from the index, and order by when a task
+-- became DUE rather than by when it was created.
+--
+-- The two halves are one fix. `run_at_ms <= :now_ms` was a residual on the old
+-- (queue, status, priority desc, created_at_ms) index, and a not-yet-due row —
+-- a retry waiting out its backoff, a task submitted with a delay — sorts by the
+-- created_at it has always had, which puts it AHEAD of the rows that are
+-- actually claimable. So every draw walked the whole backoff pile before
+-- reaching anything it could take, inside the transaction that holds the claim.
+-- The pile is largest exactly when a downstream dependency has just failed and
+-- thousands of tasks are backing off together.
+--
+-- Ordering by run_at_ms instead puts every not-yet-due row AFTER the due ones,
+-- so the scan reaches its rows first, and appending `id` lets the index carry the
+-- tie-break as well, which is what lets the planner satisfy the ORDER BY from the
+-- index alone. Measured through the real statement (`claim_one_queue`, one queue,
+-- four names, 20k queued rows backing off), one claim of one task, on the three
+-- SQLite builds that happened to be on the authoring machine:
+--
+--     SQLite   linked by                       one due row       an empty draw
+--     3.39.4   a system python3.11             1166us ->   22us  1110us ->  350us
+--     3.47.1   a python3.13 (this repo's venv)  3378us ->  116us  3128us -> 1006us
+--     3.53.4   better-sqlite3 13 (bundled)     1100us ->   72us  1060us ->   50us
+--
+-- Read the columns, not the rows: the win holds on every build, and the absolute
+-- cost swings more between SQLite versions than between before and after on some
+-- of them. better-sqlite3 bundles its own SQLite, so the TypeScript SDK's version
+-- is a dependency; the Python SDK links whatever the interpreter was built
+-- against, so its version belongs to the user's Python and cannot be assumed.
+--
+-- The plan differs by SQLite version and the win does not come from one single
+-- mechanism: 3.39 drops the sorter outright, while 3.53 keeps one and instead
+-- reaches the due rows through a skip-scan. What both have in common is the
+-- ordering — the due rows are now at the front of the range instead of behind
+-- every not-yet-due one. Numbers are SQLite; Postgres was not measured (no
+-- server in the authoring environment), so treat the Postgres side as reasoned
+-- rather than benchmarked.
+--
+-- What this does NOT fix: an empty draw still walks the whole range looking for
+-- rows that are not there (350us above), and `claimable_probe` — whose two-armed
+-- EXISTS cannot use the index at all — is unchanged at ~2.2ms on that backlog.
+-- A queue deep in backoff still costs a worker real time per poll.
+--
+-- For a task that was never delayed or retried the change is invisible in
+-- practice: insert_task sets run_at_ms = now + delay, so the two columns hold the
+-- same millisecond for an ordinary submit. (On Postgres "the same millisecond" is
+-- not quite an identity — insert_task evaluates clock_timestamp() once per column
+-- and it advances within a statement, so a submit landing on a millisecond
+-- boundary can differ by 1ms. That reorders two tasks submitted in the same
+-- millisecond, which claim.sql already calls decided by the id's random half
+-- rather than by submit order.) It changes real ordering only for tasks whose
+-- delivery was deferred, and for those "oldest due first" is the fairer answer —
+-- a task that failed and backed off should not cut ahead of everything submitted
+-- while it waited, which is what its original created_at_ms bought it.
+--
+-- Both indexes are rebuilt inside the migration's write transaction, so every
+-- other process's writes wait while they build — and they wait only as long as
+-- their busy budget (`busyTimeoutMs` / `busy_timeout_ms`, 5s by default) before
+-- failing. Measured on a warm local SSD: ~2.5s + ~3.4s for a 1M-row, 500MB
+-- database, i.e. past that default. Small databases do not notice; see
+-- "Upgrading" in the README for what to do about a large one.
+--
+-- Same names, new definitions: these indexes ARE "the ones the claim reads", and
+-- every reference to them in the SQL comments and PROTOCOL.md still points at
+-- the right object.
+--
+-- An SDK older than this migration keeps working: it orders by created_at_ms,
+-- finds no index in that order, and sorts. Slower, exactly where this migration
+-- is faster — but note the sharper consequence while a fleet is mixed. Two SDK
+-- versions against one database then disagree about which task is NEXT for any
+-- delayed or retried work: each takes a valid claimable task, no task is lost or
+-- run twice, but the documented claim order holds only within one version. That
+-- is a difference in fairness, not in correctness, which is why protocol_version
+-- stays at 1 — and it is a reason to keep the mixed window short.
+drop index if exists cairnq_tasks_claim_idx;
+create index cairnq_tasks_claim_idx
+    on cairnq_tasks (queue, status, priority desc, run_at_ms, id);
+
+-- The per-name twin (see 0006), rebuilt on the same principle.
+drop index if exists cairnq_tasks_claim_name_idx;
+create index cairnq_tasks_claim_name_idx
+    on cairnq_tasks (queue, status, name, priority desc, run_at_ms, id);
+
+update cairnq_meta set value = '8' where key = 'schema_version';

package/dist/_protocol/sql/postgres/claim.sql

@@ -29,10 +29,13 @@ from (
       and queue = any(:queues::text[])
       and (:names::text[] is null or name = any(:names::text[]))
       and run_at_ms <= (extract(epoch from clock_timestamp()) * 1000)::bigint
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
     for update skip locked
 ) sel

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

@@ -26,10 +26,13 @@ from (
       and queue = any(:queues::text[])
       and name = :name
       and run_at_ms <= (extract(epoch from clock_timestamp()) * 1000)::bigint
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
     for update skip locked
 ) sel

package/dist/_protocol/sql/postgres/claim_one_queue.sql

@@ -7,8 +7,9 @@
 -- + LIMIT over `= any(...)` the planner falls back to a sequential scan and a
 -- full sort of every claimable row (measured on 20k queued: Seq Scan 20000 rows,
 -- quicksort 1861kB), inside the transaction that holds the claim. The equality
--- form index-scans cairnq_tasks_claim_idx and only incrementally sorts the id
--- tie-break — 33 rows read for the same query.
+-- form index-scans cairnq_tasks_claim_idx, which since migration 0008 carries the
+-- id tie-break too and so needs no sort node at all — 33 rows read for the same
+-- query.
 --
 -- params: queue, names (text[] or null), worker_id, lease_ms, limit
 update cairnq_tasks t
@@ -24,10 +25,13 @@ from (
       and queue = :queue
       and (:names::text[] is null or name = any(:names::text[]))
       and run_at_ms <= (extract(epoch from clock_timestamp()) * 1000)::bigint
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
     for update skip locked
 ) sel

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

@@ -23,10 +23,13 @@ from (
       and queue = :queue
       and name = :name
       and run_at_ms <= (extract(epoch from clock_timestamp()) * 1000)::bigint
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
     for update skip locked
 ) sel

package/dist/_protocol/sql/sqlite/claim.sql

@@ -22,10 +22,13 @@ where id in (
       and queue in (select value from json_each(:queues))
       and (:names is null or name in (select value from json_each(:names)))
       and run_at_ms <= :now_ms
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
 )
 returning *;

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

@@ -27,10 +27,13 @@ where id in (
       and queue in (select value from json_each(:queues))
       and name = :name
       and run_at_ms <= :now_ms
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
 )
 returning *;

package/dist/_protocol/sql/sqlite/claim_one_queue.sql

@@ -8,9 +8,9 @@
 -- longer read rows in claim order; it materializes every claimable row into a
 -- temp B-tree just to take LIMIT of them. Cost then grows with the queued
 -- backlog, inside the write transaction, on every claim: measured at 21us / 239us
--- / 1792us for a backlog of 50 / 2000 / 20000. The equality form keeps
--- cairnq_tasks_claim_idx in claim order, needs only a partial sort for the id
--- tie-break, and stays flat at ~12us.
+-- / 1792us for a backlog of 50 / 2000 / 20000. The equality form reads
+-- cairnq_tasks_claim_idx in claim order — the whole ORDER BY, id tie-break
+-- included, since migration 0008 — so it needs no sort at all and stays flat.
 --
 -- params: queue, names (JSON array text or null), now_ms, worker_id,
 --         lease_until_ms, limit
@@ -27,10 +27,13 @@ where id in (
       and queue = :queue
       and (:names is null or name in (select value from json_each(:names)))
       and run_at_ms <= :now_ms
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
 )
 returning *;

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

@@ -7,7 +7,9 @@
 -- claim_one_name.sql's name equality, and each is there for the reason that file
 -- gives. Together they let cairnq_tasks_claim_name_idx be read in claim order
 -- with both leading columns pinned, so the draw is a seek that terminates at
--- :limit rows however deep the backlog is.
+-- :limit rows however deep the backlog is — including a backlog of tasks that are
+-- queued but not yet due, which since migration 0008 sort behind the due ones
+-- rather than ahead of them.
 -- params: queue, name, now_ms, worker_id, lease_until_ms, limit
 update cairnq_tasks
 set
@@ -22,10 +24,13 @@ where id in (
       and queue = :queue
       and name = :name
       and run_at_ms <= :now_ms
-    -- id breaks created_at_ms ties (same-millisecond submits), so claim order
-    -- is deterministic: FIFO at millisecond granularity; within one millisecond
+    -- Ordered by when a task became DUE, not when it was created: see migration
+    -- 0008 for why, for what it costs a mixed-version fleet, and for which of
+    -- these four statements the index can serve without a sort.
+    -- id breaks run_at_ms ties (same-millisecond submits), so claim order is
+    -- deterministic: FIFO at millisecond granularity; within one millisecond
     -- the id's random half decides, stably but not in submit order.
-    order by priority desc, created_at_ms asc, id asc
+    order by priority desc, run_at_ms asc, id asc
     limit :limit
 )
 returning *;

package/dist/errors.d.ts

@@ -101,6 +101,17 @@ export declare class LostLease extends CairnQError {
 export declare class ProtocolVersionMismatch extends CairnQError {
     constructor(message: string);
 }
+/**
+ * This store cannot do what was asked, and no argument would change that — the
+ * capability belongs to the backend, not to the call.
+ *
+ * Thrown by `completeIn` on a store with no driver session to share (SQLite has
+ * none). A CairnQError rather than a bare Error so the same catch works across
+ * both SDKs; the Python SDK raises the same named error.
+ */
+export declare class UnsupportedBackend extends CairnQError {
+    constructor(message: string);
+}
 /**
  * This connection is not pointed at the cairnq installation the rest of the
  * deployment is using — raised at connect, before any task is written.

package/dist/errors.js

@@ -187,6 +187,20 @@ export class ProtocolVersionMismatch extends CairnQError {
         this.name = "ProtocolVersionMismatch";
     }
 }
+/**
+ * This store cannot do what was asked, and no argument would change that — the
+ * capability belongs to the backend, not to the call.
+ *
+ * Thrown by `completeIn` on a store with no driver session to share (SQLite has
+ * none). A CairnQError rather than a bare Error so the same catch works across
+ * both SDKs; the Python SDK raises the same named error.
+ */
+export class UnsupportedBackend extends CairnQError {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedBackend";
+    }
+}
 /**
  * This connection is not pointed at the cairnq installation the rest of the
  * deployment is using — raised at connect, before any task is written.

package/dist/index.d.ts

@@ -20,5 +20,5 @@ export type { ListInput, PurgeInput, SubmitInput, Conflict, WatchOptions, WatchS
 export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
 export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, UnsupportedBackend, SerializationError, } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/dist/index.js

@@ -11,4 +11,4 @@ export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
 export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, UnsupportedBackend, SerializationError, } from "./errors.js";

package/dist/models.d.ts

@@ -31,6 +31,8 @@ export interface TaskRef {
     id: string;
     status: TaskStatus;
 }
+export declare const JSON_COLUMNS: readonly ["payload", "result", "error", "metadata"];
+export declare const MS_COLUMNS: readonly ["lease_until_ms", "run_at_ms", "cancel_requested_at_ms", "created_at_ms", "updated_at_ms", "completed_at_ms"];
 export declare const TERMINAL: readonly ["succeeded", "failed", "canceled"];
 export type TerminalStatus = (typeof TERMINAL)[number];
 export declare function isTerminalStatus(status: TaskStatus): status is TerminalStatus;

package/dist/models.js

@@ -3,13 +3,13 @@
 // truth is the status CHECK constraint in cairnq-protocol's migration, which the
 // conformance suite pins this set against.
 export const STATUSES = ["queued", "running", "succeeded", "failed", "canceled"];
-const JSON_COLUMNS = ["payload", "result", "error", "metadata"];
+export const JSON_COLUMNS = ["payload", "result", "error", "metadata"];
 // The bigint columns. `attempt` / `max_attempts` / `priority` are int4 and
 // `progress` is double precision, so every driver already gives those as numbers;
 // only int8 has a wire form worth normalizing. Nullability differs per column
 // (completed_at_ms may be null, created_at_ms may not), so the coercion has to
 // preserve null rather than turn it into 0.
-const MS_COLUMNS = [
+export const MS_COLUMNS = [
     "lease_until_ms",
     "run_at_ms",
     "cancel_requested_at_ms",

package/dist/retention.d.ts

@@ -46,7 +46,17 @@ export declare class RetentionSweeper {
     private active;
     /** Set by stop(), so a drain in progress can cut itself short too. */
     private stopping;
-    /** Resolves the current sleep early, so stop() need not wait out an interval. */
+    /**
+     * Resolved by stop(); every sleep races it. One signal rather than a handle to
+     * the current sleep, because there can be more than one: `sweep()` is public
+     * and meant to be called directly for an on-demand drain, and its
+     * between-batches yield is a sleep of its own. A single handle let that sleep
+     * overwrite the scheduled loop's — and then clear it — leaving stop() nothing
+     * to wake and close() blocked until the whole interval (an hour, by default)
+     * ran out. Same shape as Worker's `stopped$`, and as the Python twin's
+     * asyncio.Event.
+     */
+    private stopSignal;
     private wake;
     /** The loop itself, awaited by stop() so no purge outlives the store. */
     private loop;
@@ -57,6 +67,8 @@ export declare class RetentionSweeper {
     private readonly purgeInputs;
     constructor(store: TaskStore, opts: RetentionOptions);
     start(): void;
+    /** Mint a fresh stop signal. */
+    private arm;
     /** Stop sweeping and wait for the sweep in flight, if any. */
     stop(): Promise<void>;
     private run;

package/dist/retention.js

@@ -27,8 +27,18 @@ export class RetentionSweeper {
     active = false;
     /** Set by stop(), so a drain in progress can cut itself short too. */
     stopping = false;
-    /** Resolves the current sleep early, so stop() need not wait out an interval. */
-    wake = null;
+    /**
+     * Resolved by stop(); every sleep races it. One signal rather than a handle to
+     * the current sleep, because there can be more than one: `sweep()` is public
+     * and meant to be called directly for an on-demand drain, and its
+     * between-batches yield is a sleep of its own. A single handle let that sleep
+     * overwrite the scheduled loop's — and then clear it — leaving stop() nothing
+     * to wake and close() blocked until the whole interval (an hour, by default)
+     * ran out. Same shape as Worker's `stopped$`, and as the Python twin's
+     * asyncio.Event.
+     */
+    stopSignal;
+    wake;
     /** The loop itself, awaited by stop() so no purge outlives the store. */
     loop = null;
     intervalMs;
@@ -52,6 +62,7 @@ export class RetentionSweeper {
         if (!cutoffs.length) {
             throw new Error("retention.olderThanMs must name at least one status");
         }
+        this.arm();
         this.purgeInputs = cutoffs.map(([status, ms]) => ({
             olderThanMs: ms,
             status,
@@ -67,13 +78,19 @@ export class RetentionSweeper {
             return;
         this.active = true;
         this.stopping = false;
+        // A stopped sweeper can be started again, and the old signal is spent.
+        this.arm();
         this.loop = this.run();
     }
+    /** Mint a fresh stop signal. */
+    arm() {
+        this.stopSignal = new Promise((resolve) => (this.wake = resolve));
+    }
     /** Stop sweeping and wait for the sweep in flight, if any. */
     async stop() {
         this.stopping = true;
         this.active = false;
-        this.wake?.();
+        this.wake();
         await this.loop;
         this.loop = null;
     }
@@ -123,15 +140,13 @@ export class RetentionSweeper {
     /** Sleep, interruptible by stop(). Unref'd: retention is housekeeping, and a
      * pending sweep must never be the reason a process refuses to exit. */
     sleep(ms) {
-        return new Promise((resolve) => {
-            const timer = setTimeout(resolve, ms);
+        let timer;
+        const nap = new Promise((resolve) => {
+            timer = setTimeout(resolve, ms);
             timer.unref?.();
-            this.wake = () => {
-                clearTimeout(timer);
-                resolve();
-            };
-        }).finally(() => {
-            this.wake = null;
         });
+        // Clear the timer whichever side wins, so a stop is never followed by a
+        // leftover sweep timer.
+        return Promise.race([nap, this.stopSignal]).finally(() => clearTimeout(timer));
     }
 }

package/dist/store/base.d.ts

@@ -147,6 +147,12 @@ export declare abstract class TaskStore {
      * `watch` degrades to its timer alone.
      */
     protected subscribePush?(onSignal: (signal: WatchSignal) => void): () => void;
+    /**
+     * Tell a store with a push channel which queues this process will wait on, so
+     * it can buffer their notifications and ignore everyone else's. Optional: a
+     * store without a push channel has nothing to buffer.
+     */
+    protected registerWakeable?(queues: string[]): void;
     /**
      * Nudge the push channel back up if it has dropped. Called from `watch`'s
      * timer, which is the only thing keeping a client-side subscriber alive: a
@@ -289,9 +295,12 @@ export declare abstract class TaskStore {
      * `plan` runs with the write lock held, so it must await nothing but that
      * callback.
      *
-     * `names` is the union `plan` might ask for — the probe and the recovery are
-     * filtered by it. Returns undefined when the probe finds nothing claimable, in
-     * which case `plan` never runs and no transaction is opened.
+     * `names` is the union `plan` might ask for, and it filters the probe's
+     * queued-work arm. Lease recovery is deliberately NOT filtered by it — nor is
+     * the probe's expired-lease arm — because reclaiming a dead worker's task is
+     * every worker's job, whatever names it happens to handle. Returns undefined
+     * when the probe finds nothing claimable, in which case `plan` never runs and
+     * no transaction is opened.
      */
     claimSession<T>(input: {
         queues: string[];