cairnq 0.1.0 → 0.2.0

package/README.md

@@ -62,5 +62,33 @@ const { summary } = await tasks.call(summarize, { text }); // typed result, no c
 
 Opt-in: every API still accepts a plain name string (cross-language callers use it).
 
+## Running it in production
+
+```ts
+const worker = Worker.sqlite("tasks.db", {
+  concurrency: 4,
+  retryBackoffMs: 1_000,   // doubles per attempt, capped by retryBackoffMaxMs (30s); 0 disables
+  onError: (err, info) => log.warn({ err, ...info }), // claims/writes the loop survived
+});
+
+// Nothing else deletes rows. Sweep terminal tasks on a schedule.
+await tasks.purge({ olderThanMs: 7 * 24 * 3600_000 });
+```
+
+A handler that does real side effects should bail out when it loses its lease —
+the task is already running on another worker and nothing it writes is recorded:
+
+```ts
+worker.task("long.job", async (ctx) => {
+  const res = await fetch(url, { signal: ctx.signal }); // aborts on lease loss
+  if (ctx.lostLease || (await ctx.canceled())) return;
+});
+```
+
+## Multi-host
+
+Same code, Postgres instead of the file — `CairnQ.postgres(dsn)` /
+`Worker.postgres(dsn)`. Requires the optional `pg` peer dependency (`npm i pg`).
+
 The protocol (schema + canonical SQL) lives in `../cairnq-protocol` and is shared
 verbatim with the Python SDK. See `../cairnq-protocol/PROTOCOL.md`.

package/dist/_protocol/migrations/postgres/0002_purge_index.sql

@@ -0,0 +1,6 @@
+-- Serves purge.sql: scan terminal tasks in completion order. Without it the
+-- retention sweep is a full table scan of exactly the rows that accumulate most.
+create index if not exists cairnq_tasks_completed_idx
+    on cairnq_tasks (completed_at_ms);
+
+update cairnq_meta set value = '2' where key = 'schema_version';

package/dist/_protocol/migrations/postgres/0003_notify.sql

@@ -0,0 +1,38 @@
+-- Push-based wakeups (Postgres only). A row trigger emits:
+--   cairnq_queued  (payload: queue name)  when a task becomes claimable-soon:
+--                                         inserted queued, or requeued by a
+--                                         retryable fail / retry / recovery;
+--   cairnq_done    (payload: task id)     when a task reaches a terminal status.
+-- The trigger lives in the database, not in the SDKs, so every writer — either
+-- SDK, any version, even hand-run SQL — wakes listeners. See PROTOCOL.md
+-- ("Push wakeups") for the contract; in short, notifications only cut a poll
+-- sleep short and are never required for correctness. Additive:
+-- protocol_version stays 1.
+--
+-- Trigger guards, hottest write first:
+--   - WHEN keeps claim (-> 'running', the most frequent status write) from
+--     entering plpgsql at all;
+--   - UPDATE OF status keeps heartbeat/progress from firing the trigger;
+--   - the IS DISTINCT FROM checks skip a SET that rewrites the same value
+--     (e.g. cancel.sql on an already-running task).
+
+create or replace function cairnq_notify() returns trigger as $$
+begin
+    if new.status = 'queued'
+       and (tg_op = 'INSERT' or old.status is distinct from new.status) then
+        perform pg_notify('cairnq_queued', new.queue);
+    elsif tg_op = 'UPDATE'
+          and new.status in ('succeeded', 'failed', 'canceled')
+          and old.status not in ('succeeded', 'failed', 'canceled') then
+        perform pg_notify('cairnq_done', new.id);
+    end if;
+    return null;
+end;
+$$ language plpgsql;
+
+drop trigger if exists cairnq_tasks_notify on cairnq_tasks;
+create trigger cairnq_tasks_notify
+after insert or update of status on cairnq_tasks
+for each row
+when (new.status is distinct from 'running')
+execute function cairnq_notify();

package/dist/_protocol/migrations/sqlite/0002_purge_index.sql

@@ -0,0 +1,6 @@
+-- Serves purge.sql: scan terminal tasks in completion order. Without it the
+-- retention sweep is a full table scan of exactly the rows that accumulate most.
+create index if not exists cairnq_tasks_completed_idx
+    on cairnq_tasks (completed_at_ms);
+
+update cairnq_meta set value = '2' where key = 'schema_version';

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

@@ -6,20 +6,33 @@
 -- recover_leases MUST run first in the SAME transaction. READ COMMITTED suffices:
 -- each UPDATE re-checks its WHERE against the latest committed row, so racing
 -- claims/recovers can neither double-dispatch a task nor double-recover a lease.
--- params: queues (text[]), worker_id, lease_ms, limit
+-- Time is clock_timestamp(), not now(): now() freezes at BEGIN, and this runs
+-- after recover_leases in a transaction that may have waited on row locks — a
+-- lease stamped from the transaction start would already be short by that wait.
+--
+-- :names is the set of task names the caller can actually run, or NULL for no
+-- filter. A worker passes its registered handler names: queues alone do not
+-- partition work, so without this a worker claims a task it has no handler for
+-- and fails it permanently — two workers with different handler sets on one queue
+-- would destroy each other's tasks. An empty array claims nothing.
+-- params: queues (text[]), names (text[] or null), worker_id, lease_ms, limit
 update cairnq_tasks t
 set
     status = 'running',
     worker_id = :worker_id,
-    lease_until_ms = (extract(epoch from now()) * 1000)::bigint + :lease_ms,
+    lease_until_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint + :lease_ms,
     attempt = attempt + 1,
-    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+    updated_at_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint
 from (
     select id from cairnq_tasks
     where status = 'queued'
       and queue = any(:queues::text[])
-      and run_at_ms <= (extract(epoch from now()) * 1000)::bigint
-    order by priority desc, created_at_ms asc
+      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
+    -- the id's random half decides, stably but not in submit order.
+    order by priority desc, created_at_ms asc, id asc
     limit :limit
     for update skip locked
 ) sel

package/dist/_protocol/sql/postgres/fail.sql

@@ -1,18 +1,38 @@
--- Fail a task (Postgres dialect). Ownership-checked. Single CASE-based statement
--- handles both branches atomically: retryable && attempt < max_attempts -> requeue
--- with backoff (run_at = now + :delay_ms); otherwise -> terminal 'failed'.
+-- Fail a task (Postgres dialect). Ownership-checked. One CASE-based statement
+-- decides all three outcomes atomically:
+--   1. a cancel was requested while it ran -> terminal 'canceled'. Cancel wins,
+--      exactly as in complete.sql: a task the user cancelled must never be
+--      redelivered, whether the attempt ended in a return or in an exception.
+--   2. retryable && attempt < max_attempts -> requeue with backoff
+--      (run_at = now + :delay_ms).
+--   3. otherwise -> terminal 'failed'.
+-- The error envelope is recorded on every branch, so a canceled-while-failing
+-- task still carries why its last attempt failed. progress/message describe the
+-- attempt in flight, so only the requeue branch clears them: a terminal record
+-- keeps how far the last attempt got, a re-queued one must not advertise a dead
+-- attempt's progress bar until the next attempt overwrites it.
 -- :retryable is a native boolean. :error is bound as jsonb. Time from the DB clock.
 -- params: id, worker_id, error (jsonb), retryable (boolean), delay_ms
 update cairnq_tasks
 set
-    status = case when :retryable and attempt < max_attempts then 'queued' else 'failed' end,
+    status = case
+        when cancel_requested_at_ms is not null then 'canceled'
+        when :retryable and attempt < max_attempts then 'queued'
+        else 'failed'
+    end,
     error = :error::jsonb,
-    worker_id = case when :retryable and attempt < max_attempts then null else worker_id end,
-    lease_until_ms = case when :retryable and attempt < max_attempts then null else lease_until_ms end,
-    run_at_ms = case when :retryable and attempt < max_attempts
+    worker_id = case when cancel_requested_at_ms is null and :retryable and attempt < max_attempts
+                     then null else worker_id end,
+    lease_until_ms = case when cancel_requested_at_ms is null and :retryable and attempt < max_attempts
+                          then null else lease_until_ms end,
+    run_at_ms = case when cancel_requested_at_ms is null and :retryable and attempt < max_attempts
                      then (extract(epoch from now()) * 1000)::bigint + :delay_ms else run_at_ms end,
-    completed_at_ms = case when :retryable and attempt < max_attempts
+    completed_at_ms = case when cancel_requested_at_ms is null and :retryable and attempt < max_attempts
                            then null else (extract(epoch from now()) * 1000)::bigint end,
+    progress = case when cancel_requested_at_ms is null and :retryable and attempt < max_attempts
+                    then null else progress end,
+    message = case when cancel_requested_at_ms is null and :retryable and attempt < max_attempts
+                   then null else message end,
     updated_at_ms = (extract(epoch from now()) * 1000)::bigint
 where id = :id
   and status = 'running'

package/dist/_protocol/sql/postgres/insert_task.sql

@@ -2,6 +2,9 @@
 -- :root_id (= :id for top-level tasks). Time comes from the DB clock, so the SDK
 -- passes a relative :delay_ms (not an absolute run_at_ms): run_at = now + delay.
 -- :payload / :metadata are bound as jsonb.
+-- Time is clock_timestamp(), not now(): a keyed submit runs this after waiting
+-- on the key's advisory lock, and now() freezes at BEGIN — a delayed task's
+-- run_at stamped from the transaction start would fire early by that wait.
 -- params: id, name, queue, payload, metadata, max_attempts, priority,
 --         delay_ms, parent_id, root_id, correlation_id
 insert into cairnq_tasks (
@@ -12,9 +15,9 @@ insert into cairnq_tasks (
 ) values (
     :id, :name, :queue, 'queued', :payload::jsonb, :metadata::jsonb,
     :max_attempts, :priority,
-    (extract(epoch from now()) * 1000)::bigint + :delay_ms,
+    (extract(epoch from clock_timestamp()) * 1000)::bigint + :delay_ms,
     :parent_id, :root_id, :correlation_id,
-    (extract(epoch from now()) * 1000)::bigint,
-    (extract(epoch from now()) * 1000)::bigint
+    (extract(epoch from clock_timestamp()) * 1000)::bigint,
+    (extract(epoch from clock_timestamp()) * 1000)::bigint
 )
 returning *;

package/dist/_protocol/sql/postgres/list.sql

@@ -9,5 +9,7 @@ where (:status::text is null or status = :status)
   and (:name::text is null or name = :name)
   and (:root_id::text is null or root_id = :root_id)
   and (:correlation_id::text is null or correlation_id = :correlation_id)
-order by created_at_ms desc
+-- id breaks created_at_ms ties, as in claim.sql: without it, paginating with
+-- offset across same-millisecond rows could repeat or skip a task.
+order by created_at_ms desc, id desc
 limit :limit offset :offset;

package/dist/_protocol/sql/postgres/lock_key.sql

@@ -0,0 +1,9 @@
+-- Serialize all keyed operations on one key (submit-with-key and the *_by_key
+-- ops). READ COMMITTED gives those read-then-write sequences nothing to lock
+-- when the key row does not exist yet, so two concurrent same-key submits could
+-- both see "no existing task" and both insert — two live tasks under one key.
+-- An advisory transaction lock on the key's hash closes that window; it
+-- releases with the transaction. A hash collision only over-serializes two
+-- unrelated keys — it can never under-lock.
+-- params: key
+select pg_advisory_xact_lock(hashtextextended(:key::text, 0));

package/dist/_protocol/sql/postgres/progress.sql

@@ -1,9 +1,10 @@
 -- Update progress/message (Postgres dialect). Ownership-checked. Does not change
--- status. message is coalesced so progress(value) without a message keeps the
--- prior one. Time comes from the DB clock.
+-- status. Both fields are coalesced, symmetrically: progress(value) keeps the
+-- prior message, progress(null, message) keeps the prior fraction. Passing null
+-- means "leave this alone", never "clear it". Time comes from the DB clock.
 -- params: id, worker_id, progress, message
 update cairnq_tasks
-set progress = :progress,
+set progress = coalesce(:progress, progress),
     message = coalesce(:message, message),
     updated_at_ms = (extract(epoch from now()) * 1000)::bigint
 where id = :id

package/dist/_protocol/sql/postgres/protocol_version.sql

@@ -0,0 +1,4 @@
+-- The storage's protocol major, from cairnq_meta (written by the migrations).
+-- Returns no row on a database from before the first migration.
+-- params: (none)
+select value from cairnq_meta where key = 'protocol_version';

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

@@ -0,0 +1,25 @@
+-- Retention: delete terminal tasks that completed before a cutoff (Postgres
+-- dialect). Nothing else ever removes rows, so without this a long-lived database
+-- only grows. Bounded by :limit so a large backlog is drained in short
+-- transactions. The key pointer of a purged task goes with it via
+-- cairnq_task_keys' ON DELETE CASCADE. The cutoff is relative (:older_than_ms)
+-- because time comes from the DB clock.
+-- FOR UPDATE SKIP LOCKED matters for correctness, not just throughput: without
+-- it the subselect materializes on the statement snapshot and the outer
+-- DELETE's only re-checked qual is the immutable id — so a task retried (and
+-- even re-claimed) after the snapshot would still be deleted, destroying a
+-- 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.
+-- params: older_than_ms, limit
+delete from cairnq_tasks
+where id in (
+    select id from cairnq_tasks
+    where status in ('succeeded', 'failed', 'canceled')
+      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/recover_leases.sql

@@ -1,20 +1,44 @@
 -- Reclaim tasks whose lease expired (Postgres dialect). Run inside the same write
--- transaction as claim, just before it. attempt < max_attempts -> back to 'queued'
--- for redelivery; otherwise -> 'failed' with a lease-expired error envelope. Time
--- comes from the DB clock.
+-- transaction as claim, just before it. Three outcomes, mirroring fail.sql:
+--   1. a cancel was requested before the worker died -> terminal 'canceled'
+--      (a cancelled task must never be redelivered by the crash path either);
+--   2. attempt < max_attempts -> back to 'queued' for redelivery;
+--   3. otherwise -> terminal 'failed' with a lease-expired error envelope.
+-- Time is clock_timestamp() (see claim.sql). FOR UPDATE SKIP LOCKED keeps every
+-- worker's recovery pass non-blocking: a row another worker is already
+-- recovering — or that its owner is finalizing right now — is simply skipped,
+-- that transaction's outcome stands, and (unlike a plain set UPDATE, whose
+-- lock order follows the scan) no two recoverers can deadlock.
 -- params: lease_expired_error (jsonb envelope)
 update cairnq_tasks
 set
-    status = case when attempt < max_attempts then 'queued' else 'failed' end,
-    worker_id = case when attempt < max_attempts then null else worker_id end,
+    status = case
+        when cancel_requested_at_ms is not null then 'canceled'
+        when attempt < max_attempts then 'queued'
+        else 'failed'
+    end,
+    worker_id = case when cancel_requested_at_ms is null and attempt < max_attempts
+                     then null else worker_id end,
     lease_until_ms = null,
-    run_at_ms = case when attempt < max_attempts
-                     then (extract(epoch from now()) * 1000)::bigint else run_at_ms end,
-    error = case when attempt >= max_attempts then :lease_expired_error::jsonb else error end,
-    completed_at_ms = case when attempt >= max_attempts
-                           then (extract(epoch from now()) * 1000)::bigint else completed_at_ms end,
-    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
-where status = 'running'
-  and lease_until_ms is not null
-  and lease_until_ms <= (extract(epoch from now()) * 1000)::bigint
+    run_at_ms = case when cancel_requested_at_ms is null and attempt < max_attempts
+                     then (extract(epoch from clock_timestamp()) * 1000)::bigint else run_at_ms end,
+    -- Only the failed branch records lease expiry: a canceled task did not fail.
+    error = case when cancel_requested_at_ms is null and attempt >= max_attempts
+                 then :lease_expired_error::jsonb else error end,
+    completed_at_ms = case when cancel_requested_at_ms is null and attempt < max_attempts
+                           then completed_at_ms else (extract(epoch from clock_timestamp()) * 1000)::bigint end,
+    -- Only the requeue branch clears them: they describe the dead attempt, and a
+    -- task waiting to be redelivered must not report its progress bar.
+    progress = case when cancel_requested_at_ms is null and attempt < max_attempts
+                    then null else progress end,
+    message = case when cancel_requested_at_ms is null and attempt < max_attempts
+                   then null else message end,
+    updated_at_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint
+where id in (
+    select id from cairnq_tasks
+    where status = 'running'
+      and lease_until_ms is not null
+      and lease_until_ms <= (extract(epoch from clock_timestamp()) * 1000)::bigint
+    for update skip locked
+)
 returning *;

package/dist/_protocol/sql/postgres/retry.sql

@@ -11,6 +11,9 @@ set
     run_at_ms = (extract(epoch from now()) * 1000)::bigint,
     cancel_requested_at_ms = null,
     completed_at_ms = null,
+    -- The previous attempt's progress bar dies with the attempt.
+    progress = null,
+    message = null,
     attempt = case when :reset_attempt then 0 else attempt end,
     updated_at_ms = (extract(epoch from now()) * 1000)::bigint
 where id = :id and status in ('failed', 'canceled')

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

@@ -0,0 +1,8 @@
+-- Queue depth at a glance: 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)
+select queue, status, count(*) as count
+from cairnq_tasks
+group by queue, status
+order by queue asc, status asc;

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

@@ -1,7 +1,14 @@
 -- Atomic claim. :queues is a JSON array of queue names. :lease_until_ms is
 -- precomputed by the SDK (= now_ms + lease_ms). Single UPDATE ... RETURNING
 -- under BEGIN IMMEDIATE is the SQLite equivalent of FOR UPDATE SKIP LOCKED.
--- params: queues (JSON array text), now_ms, worker_id, lease_until_ms, limit
+--
+-- :names is a JSON array of the task names the caller can actually run, or NULL
+-- for no filter. A worker passes its registered handler names: queues alone do
+-- not partition work, so without this a worker claims a task it has no handler
+-- for and fails it permanently — two workers with different handler sets on one
+-- queue would destroy each other's tasks. An empty array claims nothing.
+-- params: queues (JSON array text), names (JSON array text or null), now_ms,
+--         worker_id, lease_until_ms, limit
 update cairnq_tasks
 set
     status = 'running',
@@ -13,8 +20,12 @@ where id in (
     select id from cairnq_tasks
     where status = 'queued'
       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
-    order by priority desc, created_at_ms asc
+    -- id breaks created_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
     limit :limit
 )
 returning *;

package/dist/_protocol/sql/sqlite/claimable_probe.sql

@@ -1,12 +1,16 @@
 -- Read-only check: is there anything worth opening a write transaction for?
 -- Run before claim so idle workers don't take a write lock every poll (which
 -- would serialize all idle workers on SQLite's single writer). Returns has_work
--- = 1 if any task in these queues is claimable, or any lease has expired.
--- params: queues (JSON array text), now_ms
+-- = 1 if any task this caller can run is claimable, or any lease has expired.
+-- 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.
+-- params: queues (JSON array text), names (JSON array text or null), now_ms
 select exists(
     select 1 from cairnq_tasks
     where (status = 'queued'
            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)
        or (status = 'running'
            and lease_until_ms is not null

package/dist/_protocol/sql/sqlite/fail.sql

@@ -1,16 +1,38 @@
--- Fail a task. Ownership-checked. Single CASE-based statement handles both
--- branches atomically: retryable && attempt < max_attempts -> requeue with
--- backoff (run_at = now + delay_ms); otherwise -> terminal 'failed'.
+-- Fail a task. Ownership-checked. One CASE-based statement decides all three
+-- outcomes atomically:
+--   1. a cancel was requested while it ran -> terminal 'canceled'. Cancel wins,
+--      exactly as in complete.sql: a task the user cancelled must never be
+--      redelivered, whether the attempt ended in a return or in an exception.
+--   2. retryable && attempt < max_attempts -> requeue with backoff
+--      (run_at = now + delay_ms).
+--   3. otherwise -> terminal 'failed'.
+-- The error envelope is recorded on every branch, so a canceled-while-failing
+-- task still carries why its last attempt failed. progress/message describe the
+-- attempt in flight, so only the requeue branch clears them: a terminal record
+-- keeps how far the last attempt got, a re-queued one must not advertise a dead
+-- attempt's progress bar until the next attempt overwrites it.
 -- :retryable is 0/1. :error is a JSON envelope text.
 -- params: id, worker_id, now_ms, error, retryable, delay_ms
 update cairnq_tasks
 set
-    status = case when :retryable = 1 and attempt < max_attempts then 'queued' else 'failed' end,
+    status = case
+        when cancel_requested_at_ms is not null then 'canceled'
+        when :retryable = 1 and attempt < max_attempts then 'queued'
+        else 'failed'
+    end,
     error = :error,
-    worker_id = case when :retryable = 1 and attempt < max_attempts then null else worker_id end,
-    lease_until_ms = case when :retryable = 1 and attempt < max_attempts then null else lease_until_ms end,
-    run_at_ms = case when :retryable = 1 and attempt < max_attempts then :now_ms + :delay_ms else run_at_ms end,
-    completed_at_ms = case when :retryable = 1 and attempt < max_attempts then null else :now_ms end,
+    worker_id = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                     then null else worker_id end,
+    lease_until_ms = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                          then null else lease_until_ms end,
+    run_at_ms = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                     then :now_ms + :delay_ms else run_at_ms end,
+    completed_at_ms = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                           then null else :now_ms end,
+    progress = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                    then null else progress end,
+    message = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                   then null else message end,
     updated_at_ms = :now_ms
 where id = :id
   and status = 'running'

package/dist/_protocol/sql/sqlite/list.sql

@@ -7,5 +7,7 @@ where (:status is null or status = :status)
   and (:name is null or name = :name)
   and (:root_id is null or root_id = :root_id)
   and (:correlation_id is null or correlation_id = :correlation_id)
-order by created_at_ms desc
+-- id breaks created_at_ms ties, as in claim.sql: without it, paginating with
+-- offset across same-millisecond rows could repeat or skip a task.
+order by created_at_ms desc, id desc
 limit :limit offset :offset;

package/dist/_protocol/sql/sqlite/lock_key.sql

@@ -0,0 +1,5 @@
+-- No-op on SQLite: BEGIN IMMEDIATE already serializes every keyed transaction
+-- on the database's single write lock, so there is nothing further to lock.
+-- Exists so the shared TaskStore logic can take the key lock unconditionally;
+-- see the postgres dialect for the real one.
+select 1 as locked;

package/dist/_protocol/sql/sqlite/progress.sql

@@ -1,8 +1,12 @@
 -- Update progress/message. Ownership-checked. Does not change status.
 -- params: id, worker_id, now_ms, progress, message
--- message is coalesced so progress(value) without a message keeps the prior one.
+-- Both fields are coalesced, symmetrically: progress(value) keeps the prior
+-- message, progress(null, message) keeps the prior fraction. Passing null means
+-- "leave this alone", never "clear it".
 update cairnq_tasks
-set progress = :progress, message = coalesce(:message, message), updated_at_ms = :now_ms
+set progress = coalesce(:progress, progress),
+    message = coalesce(:message, message),
+    updated_at_ms = :now_ms
 where id = :id
   and status = 'running'
   and worker_id = :worker_id

package/dist/_protocol/sql/sqlite/protocol_version.sql

@@ -0,0 +1,4 @@
+-- The storage's protocol major, from cairnq_meta (written by the migrations).
+-- Returns no row on a database from before the first migration.
+-- params: (none)
+select value from cairnq_meta where key = 'protocol_version';

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

@@ -0,0 +1,18 @@
+-- Retention: delete terminal tasks that completed before a cutoff. Nothing else
+-- ever removes rows, so without this a long-lived database only grows.
+-- Bounded by :limit so a large backlog is drained in short transactions instead
+-- of one long write that blocks every other writer. The key pointer of a purged
+-- 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.
+-- params: before_ms, limit
+delete from cairnq_tasks
+where id in (
+    select id from cairnq_tasks
+    where status in ('succeeded', 'failed', 'canceled')
+      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/recover_leases.sql

@@ -1,15 +1,33 @@
 -- Reclaim tasks whose lease expired. Run inside the same write transaction as
--- claim, just before it. attempt < max_attempts -> back to 'queued' for redelivery;
--- otherwise -> 'failed' with a lease-expired error envelope.
+-- claim, just before it. Three outcomes, mirroring fail.sql:
+--   1. a cancel was requested before the worker died -> terminal 'canceled'
+--      (a cancelled task must never be redelivered by the crash path either);
+--   2. attempt < max_attempts -> back to 'queued' for redelivery;
+--   3. otherwise -> terminal 'failed' with a lease-expired error envelope.
 -- params: now_ms, lease_expired_error (JSON envelope text)
 update cairnq_tasks
 set
-    status = case when attempt < max_attempts then 'queued' else 'failed' end,
-    worker_id = case when attempt < max_attempts then null else worker_id end,
+    status = case
+        when cancel_requested_at_ms is not null then 'canceled'
+        when attempt < max_attempts then 'queued'
+        else 'failed'
+    end,
+    worker_id = case when cancel_requested_at_ms is null and attempt < max_attempts
+                     then null else worker_id end,
     lease_until_ms = null,
-    run_at_ms = case when attempt < max_attempts then :now_ms else run_at_ms end,
-    error = case when attempt >= max_attempts then :lease_expired_error else error end,
-    completed_at_ms = case when attempt >= max_attempts then :now_ms else completed_at_ms end,
+    run_at_ms = case when cancel_requested_at_ms is null and attempt < max_attempts
+                     then :now_ms else run_at_ms end,
+    -- Only the failed branch records lease expiry: a canceled task did not fail.
+    error = case when cancel_requested_at_ms is null and attempt >= max_attempts
+                 then :lease_expired_error else error end,
+    completed_at_ms = case when cancel_requested_at_ms is null and attempt < max_attempts
+                           then completed_at_ms else :now_ms end,
+    -- Only the requeue branch clears them: they describe the dead attempt, and a
+    -- task waiting to be redelivered must not report its progress bar.
+    progress = case when cancel_requested_at_ms is null and attempt < max_attempts
+                    then null else progress end,
+    message = case when cancel_requested_at_ms is null and attempt < max_attempts
+                   then null else message end,
     updated_at_ms = :now_ms
 where status = 'running'
   and lease_until_ms is not null

package/dist/_protocol/sql/sqlite/retry.sql

@@ -10,6 +10,9 @@ set
     run_at_ms = :now_ms,
     cancel_requested_at_ms = null,
     completed_at_ms = null,
+    -- The previous attempt's progress bar dies with the attempt.
+    progress = null,
+    message = null,
     attempt = case when :reset_attempt = 1 then 0 else attempt end,
     updated_at_ms = :now_ms
 where id = :id and status in ('failed', 'canceled')

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

@@ -0,0 +1,8 @@
+-- Queue depth at a glance: 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)
+select queue, status, count(*) as count
+from cairnq_tasks
+group by queue, status
+order by queue asc, status asc;

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { type Task } from "./models.js";
-import type { ListInput, SubmitInput, TaskStore } from "./store/base.js";
+import { type Task, type TaskStatus } from "./models.js";
+import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
 export type SubmitOptions = Omit<SubmitInput, "name" | "payload">;
 export interface CallOptions extends SubmitOptions {
@@ -34,6 +34,14 @@ export declare class CairnQ {
     retryByKey(key: string, opts?: {
         resetAttempt?: boolean;
     }): Promise<Task | null>;
+    /** 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`. */
+    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>>>;
     wait(taskId: string, opts?: {
         timeoutMs?: number;
         pollMs?: number;

package/dist/client.js

@@ -51,6 +51,18 @@ export class CairnQ {
     retryByKey(key, opts) {
         return this._store.retryByKey(key, opts);
     }
+    /** 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`. */
+    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();
+    }
     wait(taskId, opts = {}) {
         return pollWait(this._store, taskId, {
             timeoutMs: opts.timeoutMs ?? 30_000,