cairnq 0.1.0 → 0.3.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/0001_init.sql

@@ -46,7 +46,9 @@ create table if not exists cairnq_tasks (
 );
 
 -- Serves the claim query: WHERE queue=? AND status='queued' ORDER BY priority
--- desc, created_at_ms asc (run_at_ms applied as a residual filter).
+-- 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.
 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/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/postgres/0004_lease_index.sql

@@ -0,0 +1,16 @@
+-- Serves recover_leases.sql: find tasks whose lease expired. That statement runs
+-- on every worker's every poll, inside the claim transaction, so it is the one
+-- recovery read on the hot path. See the SQLite twin for the reasoning; it holds
+-- here too, and additionally keeps the FOR UPDATE SKIP LOCKED subquery from
+-- taking row locks it will immediately skip.
+--
+-- Not CONCURRENTLY: migrations run inside the same transaction as their
+-- bookkeeping insert (see PROTOCOL.md), and CREATE INDEX CONCURRENTLY cannot run
+-- in one. On a table this size the plain form's lock is brief; a deployment large
+-- enough to care can build it by hand ahead of the upgrade, and IF NOT EXISTS
+-- makes this migration a no-op then.
+create index if not exists cairnq_tasks_lease_idx
+    on cairnq_tasks (lease_until_ms)
+    where status = 'running' and lease_until_ms is not null;
+
+update cairnq_meta set value = '4' where key = 'schema_version';

package/dist/_protocol/migrations/postgres/0005_clear_terminal_lease.sql

@@ -0,0 +1,17 @@
+-- Make the lease invariant true of the whole table, not just of rows written from
+-- here on: `lease_until_ms is not null` if and only if `status = 'running'`.
+--
+-- succeed.sql and complete.sql used to leave the dead attempt's lease behind, so a
+-- succeeded task reported a lease into the future and nobody owned it. The crash
+-- path (recover_leases.sql) always cleared it, so the two ways out of 'running'
+-- disagreed on what a terminal row looks like. The statements now agree; this
+-- catches up the rows they already wrote.
+--
+-- Scoped to `status <> 'running'` rather than to the three terminal states: that is
+-- the invariant itself, and it also covers a 'queued' row should one ever be left
+-- holding a lease.
+update cairnq_tasks
+set lease_until_ms = null
+where status <> 'running' and lease_until_ms is not null;
+
+update cairnq_meta set value = '5' where key = 'schema_version';

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

@@ -45,7 +45,9 @@ create table if not exists cairnq_tasks (
 
 -- Serves the claim query: WHERE queue=? AND status='queued' ORDER BY priority
 -- desc, created_at_ms asc (run_at_ms applied as a residual filter). Leading with
--- queue+status then the ORDER BY columns avoids a sort for single-queue claims.
+-- 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.
 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/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/sqlite/0004_lease_index.sql

@@ -0,0 +1,22 @@
+-- Serves recover_leases.sql: find tasks whose lease expired. That statement runs
+-- on every worker's every poll, inside the claim transaction, so it is the one
+-- recovery read on the hot path.
+--
+-- Partial, because the rows it looks for are a tiny slice of the table: only
+-- 'running' rows can hold a lease, and their count is bounded by total worker
+-- concurrency, while terminal rows accumulate until purge. A partial index stays
+-- that small no matter how large the table grows, and — unlike the plain
+-- cairnq_tasks_status_idx it replaces on this path — it carries lease_until_ms,
+-- so the expiry test is a range scan rather than a row visit per running task.
+--
+-- Both predicate terms appear verbatim in recover_leases.sql's WHERE clause:
+-- SQLite only uses a partial index when it can match each term syntactically.
+-- It also needs statistics to prefer it, which is why both SDKs run
+-- `PRAGMA optimize` when they open a database.
+--
+-- On the missing 0003 and the schema_version jump, see PROTOCOL.md §Versioning.
+create index if not exists cairnq_tasks_lease_idx
+    on cairnq_tasks (lease_until_ms)
+    where status = 'running' and lease_until_ms is not null;
+
+update cairnq_meta set value = '4' where key = 'schema_version';

package/dist/_protocol/migrations/sqlite/0005_clear_terminal_lease.sql

@@ -0,0 +1,17 @@
+-- Make the lease invariant true of the whole table, not just of rows written from
+-- here on: `lease_until_ms is not null` if and only if `status = 'running'`.
+--
+-- succeed.sql and complete.sql used to leave the dead attempt's lease behind, so a
+-- succeeded task reported a lease into the future and nobody owned it. The crash
+-- path (recover_leases.sql) always cleared it, so the two ways out of 'running'
+-- disagreed on what a terminal row looks like. The statements now agree; this
+-- catches up the rows they already wrote.
+--
+-- Scoped to `status <> 'running'` rather than to the three terminal states: that is
+-- the invariant itself, and it also covers a 'queued' row should one ever be left
+-- holding a lease.
+update cairnq_tasks
+set lease_until_ms = null
+where status <> 'running' and lease_until_ms is not null;
+
+update cairnq_meta set value = '5' 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/claim_one_queue.sql

@@ -0,0 +1,35 @@
+-- claim, for a caller watching exactly ONE queue. Byte-for-byte claim.sql except
+-- that the queue filter is an equality on :queue instead of `= any(:queues)` — a
+-- drift-guard test asserts precisely that, so treat claim.sql as the source and
+-- re-derive this file when it changes.
+--
+-- It exists because the array form cannot be read in claim order: with ORDER BY
+-- + 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.
+--
+-- params: queue, 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 clock_timestamp()) * 1000)::bigint + :lease_ms,
+    attempt = attempt + 1,
+    updated_at_ms = (extract(epoch from clock_timestamp()) * 1000)::bigint
+from (
+    select id from cairnq_tasks
+    where status = 'queued'
+      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
+    -- 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
+where t.id = sel.id
+returning t.*;

package/dist/_protocol/sql/postgres/complete.sql

@@ -8,6 +8,9 @@ set
     status = case when cancel_requested_at_ms is not null then 'canceled' else 'succeeded' end,
     result = case when cancel_requested_at_ms is not null then result else :result::jsonb end,
     progress = case when cancel_requested_at_ms is not null then progress else 1.0 end,
+    -- Terminal on both branches, so unconditional: a lease describes an attempt in
+    -- flight and this one just ended (see succeed.sql).
+    lease_until_ms = null,
     completed_at_ms = (extract(epoch from now()) * 1000)::bigint,
     updated_at_ms = (extract(epoch from now()) * 1000)::bigint
 where id = :id

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

@@ -1,18 +1,40 @@
--- 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,
+    -- Unconditional, unlike worker_id above: all three branches end the attempt
+    -- that held the lease — two terminally, one to wait for redelivery — and none
+    -- of them leaves anyone owning it (see succeed.sql).
+    lease_until_ms = null,
+    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,55 @@
 -- 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
+      -- The scalar subselect is load-bearing, not noise: clock_timestamp() is
+      -- VOLATILE, so inlined here it becomes a per-row filter and this scan
+      -- degrades to reading every running task (20k in flight: Seq Scan 20000
+      -- rows, 19997 removed by filter). Wrapped, it is an InitPlan evaluated once
+      -- and usable as an index bound on cairnq_tasks_lease_idx — same 20k table,
+      -- 3 rows read. Do not "simplify" it away.
+      --
+      -- Deliberately not now(): that is STABLE and would also index, but it
+      -- freezes at BEGIN, and this runs in a transaction that may have waited on
+      -- row locks — the cutoff would then be older than the caller thinks and
+      -- leave expired leases behind for another poll.
+      and lease_until_ms <= (select (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/postgres/succeed.sql

@@ -7,6 +7,10 @@ set
     result = :result::jsonb,
     progress = 1.0,
     message = coalesce(:message, message),
+    -- A lease describes an attempt in flight; this one just ended. worker_id is
+    -- what carries the audit trail (who ran it), so nothing is lost by clearing
+    -- it, and the terminal-lease invariant holds — see PROTOCOL.md §Lease model.
+    lease_until_ms = null,
     completed_at_ms = (extract(epoch from now()) * 1000)::bigint,
     updated_at_ms = (extract(epoch from now()) * 1000)::bigint
 where id = :id

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/claim_one_queue.sql

@@ -0,0 +1,36 @@
+-- claim, for a caller watching exactly ONE queue. Byte-for-byte claim.sql except
+-- that the queue filter is an equality on :queue instead of an IN over :queues —
+-- a drift-guard test asserts precisely that, so treat claim.sql as the source and
+-- re-derive this file when it changes.
+--
+-- It exists because the IN form costs a full sort. json_each() hides the list's
+-- length from the planner, so SQLite must merge several index ranges and can no
+-- 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.
+--
+-- params: queue, names (JSON array text or null), now_ms, worker_id,
+--         lease_until_ms, limit
+update cairnq_tasks
+set
+    status = 'running',
+    worker_id = :worker_id,
+    lease_until_ms = :lease_until_ms,
+    attempt = attempt + 1,
+    updated_at_ms = :now_ms
+where id in (
+    select id from cairnq_tasks
+    where status = 'queued'
+      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
+    -- 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/complete.sql

@@ -9,6 +9,9 @@ set
     status = case when cancel_requested_at_ms is not null then 'canceled' else 'succeeded' end,
     result = case when cancel_requested_at_ms is not null then result else :result end,
     progress = case when cancel_requested_at_ms is not null then progress else 1.0 end,
+    -- Terminal on both branches, so unconditional: a lease describes an attempt in
+    -- flight and this one just ended (see succeed.sql).
+    lease_until_ms = null,
     completed_at_ms = :now_ms,
     updated_at_ms = :now_ms
 where id = :id