cairnq 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jannchie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# cairnq (TypeScript / Node)
+
+SQLite-first, cross-language, storage-centered durable task runtime. The
+TypeScript SDK (Node ≥ 20, `better-sqlite3`). API and worker processes coordinate
+only through a shared SQLite file.
+
+```ts
+import { CairnQ, Worker } from "cairnq";
+
+// Worker side — a handler always receives (ctx, payload).
+const worker = Worker.sqlite("tasks.db", { queues: ["gpu"] });
+worker.task("image.generate", async (ctx, payload) => {
+  await ctx.progress(0.1, "starting");
+  return { url: await generate(payload.prompt) };
+});
+await worker.serve(); // runs until SIGINT/SIGTERM, then closes the store
+
+// API side
+const tasks = CairnQ.sqlite("tasks.db");
+const task = await tasks.submit("image.generate", { prompt }, {
+  key: `user:${userId}:image:${requestId}`,
+  queue: "gpu",
+  conflict: "reuse",
+});
+```
+
+Synchronous call (submit + wait):
+
+```ts
+import { TaskFailed, TaskTimeout } from "cairnq";
+
+try {
+  const result = await tasks.call("summary.create", { text }, { waitTimeoutMs: 10_000 });
+} catch (err) {
+  if (err instanceof TaskFailed) log(err.code, err.message, err.retryable); // envelope fields
+  else if (err instanceof TaskTimeout) {
+    /* err.taskId keeps running */
+  }
+}
+```
+
+Inspect a task by id/key without matching status strings:
+
+```ts
+import { isSucceeded } from "cairnq"; // also isFailed/isCanceled/isRunning/isQueued/isTerminal
+
+const task = await tasks.getByKey(key);
+if (task && isSucceeded(task)) use(task.result);
+```
+
+Optionally define a task once and share the symbol across both ends — no string
+drift, the editor finds every caller, and payload + result are fully typed:
+
+```ts
+import { defineTask } from "cairnq";
+
+export const summarize = defineTask<{ text: string }, { summary: string }>("summarize");
+
+worker.task(summarize, async (ctx, payload) => ({ summary: await run(payload.text) }));
+const { summary } = await tasks.call(summarize, { text }); // typed result, no cast
+```
+
+Opt-in: every API still accepts a plain name string (cross-language callers use it).
+
+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

@@ -0,0 +1,75 @@
+-- CairnQ canonical schema (Postgres dialect) — protocol_version 1
+-- Single source of truth for the task table on Postgres. Idempotent; safe to
+-- re-run. Time is stored as bigint epoch milliseconds (`*_ms`), generated by the
+-- DB clock inside each statement (NOT supplied by the SDK — see sql/postgres/*).
+-- JSON columns are jsonb. Status is a CHECK constraint (not a PG enum) so the
+-- conformance status-set check matches across dialects. Ordered migrations are
+-- canonical; there is no separate schema.sql.
+
+create table if not exists cairnq_tasks (
+    id text primary key,
+
+    name text not null,
+    queue text not null default 'default',
+
+    status text not null check (
+        status in ('queued', 'running', 'succeeded', 'failed', 'canceled')
+    ),
+
+    payload jsonb not null,
+    result jsonb,
+    error jsonb,
+    metadata jsonb not null default '{}'::jsonb,
+
+    progress double precision,
+    message text,
+
+    attempt integer not null default 0,
+    max_attempts integer not null default 3,
+
+    priority integer not null default 0,
+
+    worker_id text,
+    lease_until_ms bigint,
+
+    run_at_ms bigint not null,
+
+    cancel_requested_at_ms bigint,
+
+    parent_id text,
+    root_id text,
+    correlation_id text,
+
+    created_at_ms bigint not null,
+    updated_at_ms bigint not null,
+    completed_at_ms bigint
+);
+
+-- 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).
+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);
+create index if not exists cairnq_tasks_name_idx on cairnq_tasks (name);
+create index if not exists cairnq_tasks_root_idx on cairnq_tasks (root_id);
+create index if not exists cairnq_tasks_correlation_idx on cairnq_tasks (correlation_id);
+
+-- key = business-stable pointer to the *current* task for that key.
+-- task_id = one concrete execution. Kept separate (not a unique constraint on
+-- tasks) so reuse / reject / replace are natural.
+create table if not exists cairnq_task_keys (
+    key text primary key,
+    task_id text not null references cairnq_tasks(id) on delete cascade,
+    created_at_ms bigint not null,
+    updated_at_ms bigint not null
+);
+
+create table if not exists cairnq_meta (
+    key text primary key,
+    value text not null
+);
+
+insert into cairnq_meta (key, value) values ('protocol_version', '1')
+    on conflict (key) do nothing;
+insert into cairnq_meta (key, value) values ('schema_version', '1')
+    on conflict (key) do nothing;

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

@@ -0,0 +1,74 @@
+-- CairnQ canonical schema (SQLite dialect) — protocol_version 1
+-- Single source of truth for the task table. Idempotent; safe to re-run.
+-- Time is stored as integer epoch milliseconds (`*_ms`). JSON columns are
+-- TEXT validated by json_valid(). There is no separate schema.sql: ordered
+-- migrations are canonical.
+
+create table if not exists cairnq_tasks (
+    id text primary key,
+
+    name text not null,
+    queue text not null default 'default',
+
+    status text not null check (
+        status in ('queued', 'running', 'succeeded', 'failed', 'canceled')
+    ),
+
+    payload text not null check (json_valid(payload)),
+    result text check (result is null or json_valid(result)),
+    error text check (error is null or json_valid(error)),
+    metadata text not null default '{}' check (json_valid(metadata)),
+
+    progress real,
+    message text,
+
+    attempt integer not null default 0,
+    max_attempts integer not null default 3,
+
+    priority integer not null default 0,
+
+    worker_id text,
+    lease_until_ms integer,
+
+    run_at_ms integer not null,
+
+    cancel_requested_at_ms integer,
+
+    parent_id text,
+    root_id text,
+    correlation_id text,
+
+    created_at_ms integer not null,
+    updated_at_ms integer not null,
+    completed_at_ms integer
+);
+
+-- 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.
+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);
+create index if not exists cairnq_tasks_name_idx on cairnq_tasks (name);
+create index if not exists cairnq_tasks_root_idx on cairnq_tasks (root_id);
+create index if not exists cairnq_tasks_correlation_idx on cairnq_tasks (correlation_id);
+
+-- key = business-stable pointer to the *current* task for that key.
+-- task_id = one concrete execution. Kept separate (not a unique constraint on
+-- tasks) so reuse / reject / replace are natural.
+create table if not exists cairnq_task_keys (
+    key text primary key,
+    task_id text not null references cairnq_tasks(id) on delete cascade,
+    created_at_ms integer not null,
+    updated_at_ms integer not null
+);
+
+create table if not exists cairnq_meta (
+    key text primary key,
+    value text not null
+);
+
+insert into cairnq_meta (key, value) values ('protocol_version', '1')
+    on conflict(key) do nothing;
+insert into cairnq_meta (key, value) values ('schema_version', '1')
+    on conflict(key) do nothing;

package/dist/_protocol/sql/postgres/cancel.sql

@@ -0,0 +1,16 @@
+-- Cancel (Postgres dialect). queued -> canceled immediately; running -> set
+-- cancel_requested_at_ms for cooperative exit (worker checks ctx.canceled()).
+-- Single statement covers both. No-op (0 rows) for terminal tasks. Time from the
+-- DB clock.
+-- params: id
+update cairnq_tasks
+set
+    status = case when status = 'queued' then 'canceled' else status end,
+    cancel_requested_at_ms = case when status = 'running'
+                                  then (extract(epoch from now()) * 1000)::bigint
+                                  else cancel_requested_at_ms end,
+    completed_at_ms = case when status = 'queued'
+                           then (extract(epoch from now()) * 1000)::bigint else completed_at_ms end,
+    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+where id = :id and status in ('queued', 'running')
+returning *;

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

@@ -0,0 +1,27 @@
+-- Atomic claim (Postgres dialect). Uses native FOR UPDATE SKIP LOCKED so
+-- concurrent workers never contend on the same task — the native equivalent of
+-- SQLite's single-writer BEGIN IMMEDIATE serialization. No claimable_probe is
+-- needed (PG readers don't block writers). :queues is a text[]; time and the new
+-- lease (now + :lease_ms) come from the DB clock.
+-- 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
+update cairnq_tasks t
+set
+    status = 'running',
+    worker_id = :worker_id,
+    lease_until_ms = (extract(epoch from now()) * 1000)::bigint + :lease_ms,
+    attempt = attempt + 1,
+    updated_at_ms = (extract(epoch from now()) * 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
+    limit :limit
+    for update skip locked
+) sel
+where t.id = sel.id
+returning t.*;

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

@@ -0,0 +1,17 @@
+-- Finalize a task the worker finished running (Postgres dialect). Ownership-checked
+-- like succeed. Atomic cancel-vs-success decision: if a cancel was requested while
+-- the task ran, it finalizes as 'canceled' (the result is discarded — cancel wins);
+-- otherwise 'succeeded' with the given result. Time comes from the DB clock.
+-- params: id, worker_id, result (jsonb or null)
+update cairnq_tasks
+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,
+    completed_at_ms = (extract(epoch from now()) * 1000)::bigint,
+    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > (extract(epoch from now()) * 1000)::bigint
+returning *;

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

@@ -0,0 +1,21 @@
+-- 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'.
+-- :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,
+    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
+                     then (extract(epoch from now()) * 1000)::bigint + :delay_ms else run_at_ms end,
+    completed_at_ms = case when :retryable and attempt < max_attempts
+                           then null else (extract(epoch from now()) * 1000)::bigint end,
+    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > (extract(epoch from now()) * 1000)::bigint
+returning *;

package/dist/_protocol/sql/postgres/get.sql

@@ -0,0 +1,2 @@
+-- params: id
+select * from cairnq_tasks where id = :id;

package/dist/_protocol/sql/postgres/get_by_key.sql

@@ -0,0 +1,4 @@
+-- params: key
+select t.* from cairnq_tasks t
+join cairnq_task_keys k on k.task_id = t.id
+where k.key = :key;

package/dist/_protocol/sql/postgres/get_key.sql

@@ -0,0 +1,3 @@
+-- Resolve the current task_id a key points at (for conflict handling).
+-- params: key
+select task_id from cairnq_task_keys where key = :key;

package/dist/_protocol/sql/postgres/heartbeat.sql

@@ -0,0 +1,12 @@
+-- Extend the lease (Postgres dialect). Ownership-checked: 0 rows -> caller raises
+-- LostLease. Returns the row (incl. cancel_requested_at_ms) so ctx.canceled() can
+-- ride on it. New lease (now + :lease_ms) and time come from the DB clock.
+-- params: id, worker_id, lease_ms
+update cairnq_tasks
+set lease_until_ms = (extract(epoch from now()) * 1000)::bigint + :lease_ms,
+    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > (extract(epoch from now()) * 1000)::bigint
+returning *;

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

@@ -0,0 +1,20 @@
+-- Insert a brand-new task (Postgres dialect). The SDK generates :id (ULID) and
+-- :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.
+-- params: id, name, queue, payload, metadata, max_attempts, priority,
+--         delay_ms, parent_id, root_id, correlation_id
+insert into cairnq_tasks (
+    id, name, queue, status, payload, metadata,
+    max_attempts, priority, run_at_ms,
+    parent_id, root_id, correlation_id,
+    created_at_ms, updated_at_ms
+) values (
+    :id, :name, :queue, 'queued', :payload::jsonb, :metadata::jsonb,
+    :max_attempts, :priority,
+    (extract(epoch from now()) * 1000)::bigint + :delay_ms,
+    :parent_id, :root_id, :correlation_id,
+    (extract(epoch from now()) * 1000)::bigint,
+    (extract(epoch from now()) * 1000)::bigint
+)
+returning *;

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

@@ -0,0 +1,13 @@
+-- List tasks with optional filters (Postgres dialect). Every filter param must be
+-- bound; pass NULL to skip it. The `::text` cast on each filter pins the param's
+-- type so PG can plan the `IS NULL` branch (an untyped param there is ambiguous).
+-- Supports chain queries via root_id / correlation_id.
+-- params: status, queue, name, root_id, correlation_id, limit, offset
+select * from cairnq_tasks
+where (:status::text is null or status = :status)
+  and (:queue::text is null or queue = :queue)
+  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
+limit :limit offset :offset;

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

@@ -0,0 +1,13 @@
+-- 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.
+-- params: id, worker_id, progress, message
+update cairnq_tasks
+set progress = :progress,
+    message = coalesce(:message, message),
+    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > (extract(epoch from now()) * 1000)::bigint
+returning *;

package/dist/_protocol/sql/postgres/recover_leases.sql

@@ -0,0 +1,20 @@
+-- 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.
+-- 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,
+    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
+returning *;

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

@@ -0,0 +1,17 @@
+-- Manually re-enqueue a failed/canceled task (Postgres dialect). :reset_attempt
+-- (native boolean) controls whether the attempt counter resets to 0. Time from
+-- the DB clock.
+-- params: id, reset_attempt (boolean)
+update cairnq_tasks
+set
+    status = 'queued',
+    error = null,
+    worker_id = null,
+    lease_until_ms = null,
+    run_at_ms = (extract(epoch from now()) * 1000)::bigint,
+    cancel_requested_at_ms = null,
+    completed_at_ms = 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')
+returning *;

package/dist/_protocol/sql/postgres/succeed.sql

@@ -0,0 +1,16 @@
+-- Mark succeeded (Postgres dialect). Ownership-checked. worker_id kept for audit.
+-- :result is bound as jsonb. Time comes from the DB clock.
+-- params: id, worker_id, result (jsonb), message
+update cairnq_tasks
+set
+    status = 'succeeded',
+    result = :result::jsonb,
+    progress = 1.0,
+    message = coalesce(:message, message),
+    completed_at_ms = (extract(epoch from now()) * 1000)::bigint,
+    updated_at_ms = (extract(epoch from now()) * 1000)::bigint
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > (extract(epoch from now()) * 1000)::bigint
+returning *;

package/dist/_protocol/sql/postgres/upsert_key.sql

@@ -0,0 +1,12 @@
+-- Point a key at a task (initial pointer, or repoint on replace). Postgres dialect.
+-- Time comes from the DB clock.
+-- params: key, task_id
+insert into cairnq_task_keys (key, task_id, created_at_ms, updated_at_ms)
+values (
+    :key, :task_id,
+    (extract(epoch from now()) * 1000)::bigint,
+    (extract(epoch from now()) * 1000)::bigint
+)
+on conflict (key) do update set
+    task_id = excluded.task_id,
+    updated_at_ms = excluded.updated_at_ms;

package/dist/_protocol/sql/sqlite/cancel.sql

@@ -0,0 +1,12 @@
+-- Cancel. queued -> canceled immediately; running -> set cancel_requested_at_ms
+-- for cooperative exit (worker checks ctx.canceled()). Single statement covers
+-- both. No-op (0 rows) for terminal tasks.
+-- params: id, now_ms
+update cairnq_tasks
+set
+    status = case when status = 'queued' then 'canceled' else status end,
+    cancel_requested_at_ms = case when status = 'running' then :now_ms else cancel_requested_at_ms end,
+    completed_at_ms = case when status = 'queued' then :now_ms else completed_at_ms end,
+    updated_at_ms = :now_ms
+where id = :id and status in ('queued', 'running')
+returning *;

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

@@ -0,0 +1,20 @@
+-- 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
+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 in (select value from json_each(:queues))
+      and run_at_ms <= :now_ms
+    order by priority desc, created_at_ms asc
+    limit :limit
+)
+returning *;

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

@@ -0,0 +1,14 @@
+-- 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
+select exists(
+    select 1 from cairnq_tasks
+    where (status = 'queued'
+           and queue in (select value from json_each(:queues))
+           and run_at_ms <= :now_ms)
+       or (status = 'running'
+           and lease_until_ms is not null
+           and lease_until_ms <= :now_ms)
+) as has_work;

package/dist/_protocol/sql/sqlite/complete.sql

@@ -0,0 +1,18 @@
+-- Finalize a task the worker finished running. Ownership-checked like succeed.
+-- Atomic cancel-vs-success decision: if a cancel was requested while the task
+-- ran, it finalizes as 'canceled' (the result is discarded — cancel wins);
+-- otherwise 'succeeded' with the given result. This is how a running task
+-- reaches the 'canceled' terminal state (cooperative cancel, §7).
+-- params: id, worker_id, now_ms, result (JSON text or null)
+update cairnq_tasks
+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,
+    completed_at_ms = :now_ms,
+    updated_at_ms = :now_ms
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > :now_ms
+returning *;

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

@@ -0,0 +1,19 @@
+-- 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'.
+-- :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,
+    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,
+    updated_at_ms = :now_ms
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > :now_ms
+returning *;

package/dist/_protocol/sql/sqlite/get.sql

@@ -0,0 +1,2 @@
+-- params: id
+select * from cairnq_tasks where id = :id;

package/dist/_protocol/sql/sqlite/get_by_key.sql

@@ -0,0 +1,4 @@
+-- params: key
+select t.* from cairnq_tasks t
+join cairnq_task_keys k on k.task_id = t.id
+where k.key = :key;

package/dist/_protocol/sql/sqlite/get_key.sql

@@ -0,0 +1,3 @@
+-- Resolve the current task_id a key points at (for conflict handling).
+-- params: key
+select task_id from cairnq_task_keys where key = :key;

package/dist/_protocol/sql/sqlite/heartbeat.sql

@@ -0,0 +1,10 @@
+-- Extend the lease. Ownership-checked: 0 rows -> caller raises LostLease.
+-- Returns the row (incl. cancel_requested_at_ms) so ctx.canceled() can ride on it.
+-- params: id, worker_id, now_ms, lease_until_ms
+update cairnq_tasks
+set lease_until_ms = :lease_until_ms, updated_at_ms = :now_ms
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > :now_ms
+returning *;

package/dist/_protocol/sql/sqlite/insert_task.sql

@@ -0,0 +1,16 @@
+-- Insert a brand-new task. Caller (SDK) generates :id (ULID) and :root_id
+-- (= :id for top-level tasks) and provides :now_ms.
+-- params: id, name, queue, payload, metadata, max_attempts, priority,
+--         run_at_ms, parent_id, root_id, correlation_id, now_ms
+insert into cairnq_tasks (
+    id, name, queue, status, payload, metadata,
+    max_attempts, priority, run_at_ms,
+    parent_id, root_id, correlation_id,
+    created_at_ms, updated_at_ms
+) values (
+    :id, :name, :queue, 'queued', :payload, :metadata,
+    :max_attempts, :priority, :run_at_ms,
+    :parent_id, :root_id, :correlation_id,
+    :now_ms, :now_ms
+)
+returning *;

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

@@ -0,0 +1,11 @@
+-- List tasks with optional filters. Every filter param must be bound; pass
+-- NULL to skip it. Supports chain queries via root_id / correlation_id (§22).
+-- params: status, queue, name, root_id, correlation_id, limit, offset
+select * from cairnq_tasks
+where (:status is null or status = :status)
+  and (:queue is null or queue = :queue)
+  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
+limit :limit offset :offset;

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

@@ -0,0 +1,10 @@
+-- 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.
+update cairnq_tasks
+set progress = :progress, message = coalesce(:message, message), updated_at_ms = :now_ms
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > :now_ms
+returning *;

package/dist/_protocol/sql/sqlite/recover_leases.sql

@@ -0,0 +1,17 @@
+-- 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.
+-- 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,
+    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,
+    updated_at_ms = :now_ms
+where status = 'running'
+  and lease_until_ms is not null
+  and lease_until_ms <= :now_ms
+returning *;