cairnq 0.9.0 → 0.11.0

package/README.md

@@ -114,10 +114,18 @@ const executor: PgExecutor = { /* ~30 lines over your driver */ };
 const tasks = CairnQ.postgres(executor);
 ```
 
-`schema` (DSN form only) puts cairnq's tables in a schema of their own:
+`schema` puts cairnq's tables in a schema of their own:
 `CairnQ.postgres(dsn, { schema: "cairnq" })` creates it if absent and sets
 `search_path` per connection. The protocol's SQL names no schema, so nothing else
-changes. With your own executor, the search_path is yours to set.
+changes. With your own executor the search_path is yours to set, and `schema`
+becomes an assertion about where it lands.
+
+**Every process in a deployment must agree on it.** A queue whose API and worker
+resolve to different schemas is two empty queues, and — because every migration is
+`create table if not exists` — both sides come up healthy, pass their protocol
+version check, and never see each other's tasks. cairnq refuses to connect where
+it can see that about to happen (`SchemaMismatch`); the Python SDK applies the
+same rule.
 
 Two things an adapter must get right: `int8` has to come back as a JS number
 (every cairnq `*_ms` is an epoch or a counter, all inside the safe range), and

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/postgres/installations.sql

@@ -0,0 +1,33 @@
+-- Where cairnq already lives in this database, and where this connection is
+-- pointing. Read-only; runs once per connect, before migrations.
+--
+-- Exists because `search_path` is out-of-band configuration: two processes given
+-- the same DSN can still resolve to different schemas, and because every
+-- migration is `create table if not exists`, the second one to start does not
+-- fail — it quietly builds a parallel, empty installation. Nothing downstream can
+-- tell: protocol_version reads from whichever cairnq_meta the connection sees, so
+-- the version check passes on both sides while the API's tasks are invisible to
+-- the worker forever. The only way to catch that is to look OUTSIDE the
+-- connection's own search_path, which is what this does.
+--
+-- One row per installation, never zero: the LEFT JOIN keeps `current_schema`
+-- readable on a database that holds no cairnq yet, where `schema` is null.
+-- Deliberately NOT an array column — pg_namespace.nspname is `name`, and which
+-- drivers decode a `name[]` (or a text[]) into a list is exactly the kind of
+-- disagreement this protocol keeps out of the SDKs. Scalar columns behave the
+-- same everywhere.
+--
+-- `current_schema()` is null when the search_path names nothing that exists, in
+-- which case the caller cannot conclude anything.
+-- params: (none)
+select
+    current_schema()::text as current_schema,
+    found.schema
+from (select 1) one
+left join (
+    select n.nspname::text as schema
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where c.relname = 'cairnq_tasks' and c.relkind = 'r'
+) found on true
+order by found.schema;

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/context.d.ts

@@ -19,7 +19,7 @@ export interface TaskContextOptions {
 export declare class TaskContext {
     private readonly store;
     private readonly task;
-    readonly workerId: string;
+    private readonly ownerId;
     private readonly leaseMs;
     private readonly abort;
     private leaseLost;
@@ -27,8 +27,10 @@ export declare class TaskContext {
     private isSettled;
     private readonly backoffMs;
     private readonly backoffMaxMs;
-    constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number, opts?: TaskContextOptions);
+    constructor(store: TaskStore, task: Task, ownerId: string, leaseMs: number, opts?: TaskContextOptions);
     get taskId(): string;
+    /** The worker running this task — what `worker_id` on the row points at. */
+    get workerId(): string;
     get name(): string;
     get queue(): string;
     get attempt(): number;

package/dist/context.js

@@ -14,7 +14,7 @@ import { pollWait } from "./wait.js";
 export class TaskContext {
     store;
     task;
-    workerId;
+    ownerId;
     leaseMs;
     abort = new AbortController();
     leaseLost = false;
@@ -28,10 +28,10 @@ export class TaskContext {
     isSettled = false;
     backoffMs;
     backoffMaxMs;
-    constructor(store, task, workerId, leaseMs, opts = {}) {
+    constructor(store, task, ownerId, leaseMs, opts = {}) {
         this.store = store;
         this.task = task;
-        this.workerId = workerId;
+        this.ownerId = ownerId;
         this.leaseMs = leaseMs;
         this.backoffMs = opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
         this.backoffMaxMs = opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS;
@@ -39,6 +39,10 @@ export class TaskContext {
     get taskId() {
         return this.task.id;
     }
+    /** The worker running this task — what `worker_id` on the row points at. */
+    get workerId() {
+        return this.ownerId;
+    }
     get name() {
         return this.task.name;
     }
@@ -138,7 +142,7 @@ export class TaskContext {
     async progress(value, message = null) {
         return this.owned(() => this.store.progress({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             progress: value,
             message,
         }));
@@ -146,7 +150,7 @@ export class TaskContext {
     async heartbeat() {
         return this.owned(() => this.store.heartbeat({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             leaseMs: this.leaseMs,
         }));
     }
@@ -180,7 +184,7 @@ export class TaskContext {
     async succeed(result = null) {
         if (this.isSettled)
             return null;
-        const task = await this.owned(() => this.store.complete({ taskId: this.task.id, workerId: this.workerId, result }));
+        const task = await this.owned(() => this.store.complete({ taskId: this.task.id, workerId: this.ownerId, result }));
         this.markSettled();
         return task;
     }
@@ -211,7 +215,7 @@ export class TaskContext {
         if (this.isSettled)
             return null;
         const task = await this.owned(async () => {
-            const { task } = await this.store.completeIn({ taskId: this.task.id, workerId: this.workerId }, write);
+            const { task } = await this.store.completeIn({ taskId: this.task.id, workerId: this.ownerId }, write);
             return task;
         });
         this.markSettled();
@@ -229,7 +233,7 @@ export class TaskContext {
         const [envelope, retryable] = asEnvelope(error, opts.retryable ?? true);
         const task = await this.owned(() => this.store.fail({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             error: envelope,
             retryable,
             delayMs: failDelayMs(this.task.attempt, retryable, this.backoffMs, this.backoffMaxMs),

package/dist/errors.d.ts

@@ -101,6 +101,34 @@ 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.
+ *
+ * The schema a Postgres connection resolves to is out-of-band configuration
+ * (`search_path`, a `schema` option, an ORM's pool settings), so two processes
+ * given the same DSN can still land in different schemas. Every migration is
+ * `create table if not exists`, so the odd one out does not fail: it builds a
+ * second, empty installation and its protocol version check passes against the
+ * cairnq_meta it just created. Left undetected, an API and a worker then agree
+ * about everything except WHERE, and no task ever crosses.
+ *
+ * The Python SDK raises the same named error.
+ */
+export declare class SchemaMismatch extends CairnQError {
+    constructor(message: string);
+}
 /** A value could not be encoded for a protocol JSON column (non-finite number,
  * BigInt, circular structure, …). Raised at the boundary — submit rejects with
  * it, and a worker records a handler result that triggers it as a permanent

package/dist/errors.js

@@ -187,6 +187,40 @@ 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.
+ *
+ * The schema a Postgres connection resolves to is out-of-band configuration
+ * (`search_path`, a `schema` option, an ORM's pool settings), so two processes
+ * given the same DSN can still land in different schemas. Every migration is
+ * `create table if not exists`, so the odd one out does not fail: it builds a
+ * second, empty installation and its protocol version check passes against the
+ * cairnq_meta it just created. Left undetected, an API and a worker then agree
+ * about everything except WHERE, and no task ever crosses.
+ *
+ * The Python SDK raises the same named error.
+ */
+export class SchemaMismatch extends CairnQError {
+    constructor(message) {
+        super(message);
+        this.name = "SchemaMismatch";
+    }
+}
 /** A value could not be encoded for a protocol JSON column (non-finite number,
  * BigInt, circular structure, …). Raised at the boundary — submit rejects with
  * it, and a worker records a handler result that triggers it as a permanent

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, 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, 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;