cairnq 0.5.0 → 0.7.0

package/README.md

@@ -34,7 +34,9 @@ try {
 } catch (err) {
   if (err instanceof TaskFailed) log(err.code, err.message, err.retryable); // envelope fields
   else if (err instanceof TaskTimeout) {
-    /* err.taskId keeps running */
+    // The task keeps running — resume the wait instead of submitting again.
+    const result = await tasks.wait(err.taskId, { timeoutMs: 60_000 });
+    // …or tasks.waitByKey(key), from a process that never held the id.
   }
 }
 ```
@@ -66,13 +68,17 @@ Opt-in: every API still accepts a plain name string (cross-language callers use
 
 ```ts
 const worker = Worker.sqlite("tasks.db", {
-  concurrency: 4,
-  retryBackoffMs: 1_000,   // doubles per attempt, capped by retryBackoffMaxMs (30s); 0 disables
+  concurrency: 4,          // handler calls at once; use maxInFlightBytes to bound memory
+  retryBackoffMs: 1_000,   // window doubles per attempt, capped at retryBackoffMaxMs (30s),
+                           // jittered over its upper half; 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 });
+// Nothing else deletes rows, so give the client a retention policy — it sweeps
+// terminal tasks in bounded batches for as long as the handle is open.
+const tasks = CairnQ.sqlite("tasks.db", {
+  retention: { olderThanMs: 7 * 24 * 3600_000 },
+});
 ```
 
 A handler that does real side effects should bail out when it loses its lease —

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

@@ -0,0 +1,25 @@
+-- Serves the per-name claim: claim_one_name.sql and claim_one_queue_one_name.sql,
+-- which a worker uses to draw a separate quota for each task name that sizes
+-- itself (a `batch`, or its own concurrency). See "Batch delivery" in PROTOCOL.md.
+--
+-- cairnq_tasks_claim_idx does not cover it: `name` is not in that index, so a
+-- name filter is a residual applied while walking the queue in claim order. The
+-- cost lands hardest on a name with *nothing* queued — the claim walks every
+-- claimable row in the queue looking for `limit` matches and finds none — and a
+-- worker makes one such draw per registered name, per poll, inside the claim's
+-- transaction, holding its FOR UPDATE row locks for the whole of it.
+--
+-- Both indexes are needed. `name` sits before the ORDER BY columns here, so this
+-- one can only be read in claim order when `name` is an equality — exactly the
+-- per-name draws. A claim with no name filter, or an array-valued one, still
+-- reads cairnq_tasks_claim_idx and is unaffected.
+--
+-- NOT built CONCURRENTLY: migrations run inside a transaction (see the runner's
+-- `lock table cairnq_migrations`), and CREATE INDEX CONCURRENTLY cannot. On an
+-- 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.
+create index if not exists cairnq_tasks_claim_name_idx
+    on cairnq_tasks (queue, status, name, priority desc, created_at_ms);
+
+update cairnq_meta set value = '6' where key = 'schema_version';

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

@@ -0,0 +1,26 @@
+-- Serves the per-name claim: claim_one_name.sql and claim_one_queue_one_name.sql,
+-- which a worker uses to draw a separate quota for each task name that sizes
+-- itself (a `batch`, or its own concurrency). See "Batch delivery" in PROTOCOL.md.
+--
+-- cairnq_tasks_claim_idx does not cover it: `name` is not in that index, so a
+-- name filter is a residual applied while walking the queue in claim order. The
+-- cost lands hardest on a name with *nothing* queued — the claim walks every
+-- claimable row in the queue looking for `limit` matches and finds none — and a
+-- worker makes one such draw per registered name, per poll, inside the claim's
+-- write transaction. Measured on a 20k backlog: 1116us for an empty name's draw
+-- against cairnq_tasks_claim_idx, 8.8us against this one.
+--
+-- Both indexes are needed. `name` sits before the ORDER BY columns here, so this
+-- one can only be read in claim order when `name` is an equality — exactly the
+-- per-name draws. A claim with no name filter, or a list-valued one, still reads
+-- cairnq_tasks_claim_idx and is unaffected (measured flat at ~13-16us either way).
+--
+-- The equality is what makes it usable: `name in (select value from json_each(?))`
+-- does NOT reach this index even for a single-element list — SQLite builds a
+-- 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.
+create index if not exists cairnq_tasks_claim_name_idx
+    on cairnq_tasks (queue, status, name, priority desc, created_at_ms);
+
+update cairnq_meta set value = '6' where key = 'schema_version';

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

@@ -0,0 +1,37 @@
+-- claim, for a caller drawing exactly ONE task name (Postgres dialect).
+-- Byte-for-byte claim.sql except that the name filter is an equality on :name
+-- instead of `= any(:names)` — a drift-guard test asserts precisely that, so
+-- treat claim.sql as the source and re-derive this file when it changes.
+--
+-- It exists so the draw can reach cairnq_tasks_claim_name_idx, whose leading
+-- columns are (queue, status, name): an array-valued name filter cannot be read
+-- in claim order against it, so the name falls back to a residual on
+-- cairnq_tasks_claim_idx and a draw for a name with nothing queued scans the
+-- whole claimable backlog — inside the transaction, holding its row locks. See
+-- migration 0006.
+--
+-- Used for the per-name quotas a worker draws for names that size themselves —
+-- a `batch`, or their own concurrency. See "Batch delivery" in PROTOCOL.md.
+-- params: queues (text[]), name, 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 = 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
+    -- 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/claim_one_queue_one_name.sql

@@ -0,0 +1,34 @@
+-- claim, for a caller watching ONE queue and drawing ONE task name (Postgres
+-- dialect) — the common shape for a batched worker. Byte-for-byte claim.sql
+-- except that both the queue and the name filters are equalities; a drift-guard
+-- test asserts precisely that, so treat claim.sql as the source and re-derive
+-- this file when it changes.
+--
+-- It is the combination of claim_one_queue.sql's queue equality and
+-- claim_one_name.sql's name equality, and each is there for the reason that file
+-- gives. Together they pin both leading columns of cairnq_tasks_claim_name_idx,
+-- so the draw is an index scan in claim order that stops at :limit rows however
+-- deep the backlog is.
+-- params: queue, name, 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 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
+    -- 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/heartbeat_batch.sql

@@ -0,0 +1,24 @@
+-- Extend the lease on several tasks at once (Postgres dialect) — the heartbeat
+-- for batch delivery. Ownership-checked per row, exactly as heartbeat.sql: a task
+-- whose lease this worker no longer holds simply does not come back, so the
+-- caller learns which ones it lost by which ids are absent from the result rather
+-- than by an error. One statement per beat replaces one round trip per leased
+-- task, which for a 256-task batch is the difference between one write and 256.
+--
+-- Returns only what the beat needs, unlike heartbeat.sql's `returning *`: the
+-- singular statement hands its row to the caller as `ctx.heartbeat()`'s public
+-- return value, while this one's rows never leave the worker — they answer "still
+-- mine?" (presence) and "cancelled?" (the one column). Whole rows here would pull
+-- every payload back on every beat: 256 tasks * 4KB is a megabyte re-read every
+-- lease/3 for the life of the call, and a JSON parse per row to discard it.
+--
+-- New lease (now + :lease_ms) and time come from the DB clock.
+-- params: ids (text[]), 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 = any(:ids::text[])
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > (extract(epoch from now()) * 1000)::bigint
+returning id, cancel_requested_at_ms;

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

@@ -0,0 +1,36 @@
+-- claim, for a caller drawing exactly ONE task name. Byte-for-byte claim.sql
+-- except that the name filter is an equality on :name instead of an IN over
+-- :names — 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 `name in (select value from json_each(:names))` cannot reach
+-- cairnq_tasks_claim_name_idx, even for a single-element list: SQLite builds a
+-- bloom filter over the subquery and falls back to cairnq_tasks_claim_idx, where
+-- the name is a residual and a draw for a name with nothing queued walks the
+-- whole claimable backlog. Measured on a 20k backlog: 1446us for the json_each
+-- form, 8.8us for this one. See migration 0006.
+--
+-- Used for the per-name quotas a worker draws for names that size themselves —
+-- a `batch`, or their own concurrency. See "Batch delivery" in PROTOCOL.md.
+-- params: queues (JSON array text), name, 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 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
+    -- 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_one_name.sql

@@ -0,0 +1,31 @@
+-- claim, for a caller watching ONE queue and drawing ONE task name — the common
+-- shape for a batched worker. Byte-for-byte claim.sql except that both the queue
+-- and the name filters are equalities; a drift-guard test asserts precisely that,
+-- so treat claim.sql as the source and re-derive this file when it changes.
+--
+-- It is the combination of claim_one_queue.sql's queue equality and
+-- 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.
+-- params: queue, name, 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 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
+    -- 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/heartbeat_batch.sql

@@ -0,0 +1,29 @@
+-- Extend the lease on several tasks at once — the heartbeat for batch delivery.
+-- Ownership-checked per row, exactly as heartbeat.sql: a task whose lease this
+-- worker no longer holds simply does not come back, so the caller learns which
+-- ones it lost by which ids are absent from the result rather than by an error.
+-- One statement per beat is the point: a batch handler holding 256 leases would
+-- otherwise write 256 rows every heartbeat interval, which on SQLite means 256
+-- turns of the single write lock for work nobody is waiting on.
+--
+-- Returns only what the beat needs, unlike heartbeat.sql's `returning *`: the
+-- singular statement hands its row to the caller as `ctx.heartbeat()`'s public
+-- return value, while this one's rows never leave the worker — they answer "still
+-- mine?" (presence) and "cancelled?" (the one column). Whole rows here would pull
+-- every payload back on every beat: 256 tasks * 4KB is a megabyte re-read every
+-- lease/3 for the life of the call, and a JSON parse per row to discard it.
+-- Unlike heartbeat.sql, this one's plan depends on statistics: json_each() hides
+-- the id list's length, so without sqlite_stat1 the planner drives the update off
+-- cairnq_tasks_status_idx and walks every 'running' row in the database per beat
+-- instead of doing primary-key lookups. Both SDKs ANALYZE on open and revisit
+-- once a minute per connection (see "Planner statistics" in PROTOCOL.md), so this
+-- is a warm-up window rather than a standing cost — but the statement it replaced
+-- had no such dependency, which is why it is called out here.
+-- params: ids (JSON array text), worker_id, now_ms, lease_until_ms
+update cairnq_tasks
+set lease_until_ms = :lease_until_ms, updated_at_ms = :now_ms
+where id in (select value from json_each(:ids))
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > :now_ms
+returning id, cancel_requested_at_ms;

package/dist/backoff.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Retry backoff, in its own module because two callers need it.
+ *
+ * The worker computes it when a handler's failure ends an attempt; TaskContext
+ * computes it when a handler fails one task of a batch itself. Keeping it in
+ * worker.ts would make context.ts import the module that imports it.
+ */
+export declare const DEFAULT_RETRY_BACKOFF_MS = 1000;
+export declare const DEFAULT_RETRY_BACKOFF_MAX_MS = 30000;
+/**
+ * Exponential backoff with equal jitter: the window doubles per attempt up to
+ * `maxMs`, and the delay lands uniformly in its upper half, `[w/2, w)`.
+ *
+ * The jitter is what keeps a fleet from retrying in lockstep. Failures align
+ * when the downstream fails fast enough that a whole concurrency batch raises
+ * at once (connection refused, DNS gone), and capped exponential backoff then
+ * *preserves* that alignment — once every task sits at `maxMs`, they all retry
+ * on the same beat forever. Spreading over half the window breaks it; keeping
+ * the lower half as a floor means jitter never shortens the wait to less than
+ * half of what plain exponential backoff would have asked for.
+ *
+ * `rand` is injected so tests can pin an exact delay.
+ */
+export declare function retryDelayMs(attempt: number, baseMs: number, maxMs: number, rand?: () => number): number;
+/**
+ * The delay a `fail` write should carry. Not just the backoff: a permanent
+ * failure is never re-run, so it always delays 0. Both settlement paths — the
+ * worker's and a handler's `ctx.fail` — go through this, so they cannot end up
+ * backing off differently.
+ */
+export declare function failDelayMs(attempt: number, retryable: boolean, baseMs: number, maxMs: number, rand?: () => number): number;

package/dist/backoff.js

@@ -0,0 +1,40 @@
+/**
+ * Retry backoff, in its own module because two callers need it.
+ *
+ * The worker computes it when a handler's failure ends an attempt; TaskContext
+ * computes it when a handler fails one task of a batch itself. Keeping it in
+ * worker.ts would make context.ts import the module that imports it.
+ */
+export const DEFAULT_RETRY_BACKOFF_MS = 1_000;
+export const DEFAULT_RETRY_BACKOFF_MAX_MS = 30_000;
+/**
+ * Exponential backoff with equal jitter: the window doubles per attempt up to
+ * `maxMs`, and the delay lands uniformly in its upper half, `[w/2, w)`.
+ *
+ * The jitter is what keeps a fleet from retrying in lockstep. Failures align
+ * when the downstream fails fast enough that a whole concurrency batch raises
+ * at once (connection refused, DNS gone), and capped exponential backoff then
+ * *preserves* that alignment — once every task sits at `maxMs`, they all retry
+ * on the same beat forever. Spreading over half the window breaks it; keeping
+ * the lower half as a floor means jitter never shortens the wait to less than
+ * half of what plain exponential backoff would have asked for.
+ *
+ * `rand` is injected so tests can pin an exact delay.
+ */
+export function retryDelayMs(attempt, baseMs, maxMs, rand = Math.random) {
+    if (baseMs <= 0)
+        return 0;
+    const exponent = Math.max(0, attempt - 1);
+    const window = Math.min(maxMs, baseMs * 2 ** exponent);
+    const floor = Math.floor(window / 2);
+    return floor + Math.floor(rand() * (window - floor));
+}
+/**
+ * The delay a `fail` write should carry. Not just the backoff: a permanent
+ * failure is never re-run, so it always delays 0. Both settlement paths — the
+ * worker's and a handler's `ctx.fail` — go through this, so they cannot end up
+ * backing off differently.
+ */
+export function failDelayMs(attempt, retryable, baseMs, maxMs, rand = Math.random) {
+    return retryable ? retryDelayMs(attempt, baseMs, maxMs, rand) : 0;
+}

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import type { BackpressureOptions } from "./backpressure.js";
+import { type RetentionOptions } from "./retention.js";
 import { type Task, type TaskStatus } from "./models.js";
 import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
@@ -9,10 +10,17 @@ export interface CallOptions extends SubmitOptions {
 }
 /** Options this handle configures on the store it wraps, rather than the
  * store's own constructor arguments. */
-export type ClientOptions = Partial<BackpressureOptions>;
+export type ClientOptions = Partial<BackpressureOptions> & {
+    /** Delete terminal tasks older than a cutoff, on a schedule, for as long as
+     * this handle is open. Off unless set — and off means rows accumulate forever,
+     * because nothing else in CairnQ removes them. */
+    retention?: RetentionOptions;
+};
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export declare class CairnQ {
     private readonly _store;
+    /** null unless `retention` was configured. */
+    private readonly sweeper;
     constructor(_store: TaskStore, opts?: ClientOptions);
     static sqlite(path: string, opts?: {
         busyTimeoutMs?: number;
@@ -24,6 +32,8 @@ export declare class CairnQ {
     } & ClientOptions): CairnQ;
     get store(): TaskStore;
     connect(): Promise<void>;
+    /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+     * store) and close the store. */
     close(): Promise<void>;
     /** Enqueue a task. With `maxQueueDepth` configured this blocks while the
      * target queue is at its limit, and raises QueueFull if it stays there for
@@ -55,13 +65,29 @@ export declare class CairnQ {
     /** Task counts per queue, keyed by status and zero-filled across all statuses
      * — `(await stats()).default.queued` is the backlog of a queue. */
     stats(): Promise<Record<string, Record<TaskStatus, number>>>;
+    /** Wait for a task to finish. Resolves with the terminal Task (any status);
+     * throws TaskTimeout without stopping the task, so `wait(err.taskId)` picks the
+     * same wait back up — from another process, or after a longer deadline. */
     wait(taskId: string, opts?: {
         timeoutMs?: number;
         pollMs?: number;
     }): Promise<Task>;
+    /** Wait for whatever task the `key` currently points at — the cross-process
+     * form of picking a wait back up, when the id was never in hand or the process
+     * that held it is gone. Re-resolves the key on each poll, so a `replace`
+     * landing mid-wait moves the wait onto the new task, and a key with no task
+     * yet is waited for rather than rejected. */
+    waitByKey(key: string, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Task>;
     /** submit + wait. Resolves with the result on success; rejects with
      * TaskFailed / TaskCanceled / TaskTimeout otherwise. Pass a TaskDef and the
-     * resolved value is typed as its Result. */
+     * resolved value is typed as its Result.
+     *
+     * `waitTimeoutMs` bounds the wait, not the task: on timeout the task runs on,
+     * and `wait(err.taskId)` — or `waitByKey`, from a process that only has the
+     * key — resumes the wait rather than starting the work over. */
     call(name: string, payload?: unknown, opts?: CallOptions): Promise<unknown>;
     call<P, R>(task: TaskDef<P, R>, payload?: P, opts?: CallOptions): Promise<R>;
 }

package/dist/client.js

@@ -1,12 +1,15 @@
+import { RetentionSweeper } from "./retention.js";
 import { TaskCanceled, TaskFailed } from "./errors.js";
 import { isFailed, isSucceeded } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
 import { taskName } from "./task.js";
-import { pollWait } from "./wait.js";
+import { pollWait, pollWaitByKey } from "./wait.js";
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export class CairnQ {
     _store;
+    /** null unless `retention` was configured. */
+    sweeper;
     constructor(_store, opts = {}) {
         this._store = _store;
         // Installed on the store, not held here: every submit path goes through the
@@ -14,6 +17,13 @@ export class CairnQ {
         if (opts.maxQueueDepth != null) {
             _store.useBackpressure(opts);
         }
+        // Retention is the opposite case: it belongs to the handle, because a worker
+        // sharing the store must not also be deleting rows behind the API's back.
+        // Started here rather than in connect(), which is optional — every other
+        // path connects lazily, and retention that silently depends on an optional
+        // call is retention that silently does not happen.
+        this.sweeper = opts.retention ? new RetentionSweeper(_store, opts.retention) : null;
+        this.sweeper?.start();
     }
     static sqlite(path, opts = {}) {
         const { busyTimeoutMs, ...client } = opts;
@@ -31,8 +41,11 @@ export class CairnQ {
     connect() {
         return this._store.connect();
     }
-    close() {
-        return this._store.close();
+    /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+     * store) and close the store. */
+    async close() {
+        await this.sweeper?.stop();
+        await this._store.close();
     }
     submit(task, payload, opts = {}) {
         return this._store.submit({ name: taskName(task), payload, ...opts });
@@ -77,12 +90,26 @@ export class CairnQ {
     stats() {
         return this._store.stats();
     }
+    /** Wait for a task to finish. Resolves with the terminal Task (any status);
+     * throws TaskTimeout without stopping the task, so `wait(err.taskId)` picks the
+     * same wait back up — from another process, or after a longer deadline. */
     wait(taskId, opts = {}) {
         return pollWait(this._store, taskId, {
             timeoutMs: opts.timeoutMs ?? 30_000,
             pollMs: opts.pollMs,
         });
     }
+    /** Wait for whatever task the `key` currently points at — the cross-process
+     * form of picking a wait back up, when the id was never in hand or the process
+     * that held it is gone. Re-resolves the key on each poll, so a `replace`
+     * landing mid-wait moves the wait onto the new task, and a key with no task
+     * yet is waited for rather than rejected. */
+    waitByKey(key, opts = {}) {
+        return pollWaitByKey(this._store, key, {
+            timeoutMs: opts.timeoutMs ?? 30_000,
+            pollMs: opts.pollMs,
+        });
+    }
     async call(task, payload, opts = {}) {
         const { waitTimeoutMs = 30_000, pollMs, ...submit } = opts;
         const created = await this.submit(taskName(task), payload, submit);

package/dist/context.d.ts

@@ -1,8 +1,20 @@
+import { type FailReason } from "./errors.js";
 import { type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
-/** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
+export interface TaskContextOptions {
+    retryBackoffMs?: number;
+    retryBackoffMaxMs?: number;
+}
+/**
+ * Handed to a task handler. Worker-side capabilities mirror the Python SDK.
+ *
+ * One of these per task, whether a handler is delivered one task or a batch: a
+ * batch handler receives a `TaskContext[]`, so a single-task handler's `ctx` is
+ * literally the batch-of-one element. Lease, cancellation and settlement are per
+ * task, which is why they live here rather than on anything batch-shaped.
+ */
 export declare class TaskContext {
     private readonly store;
     private readonly task;
@@ -11,7 +23,10 @@ export declare class TaskContext {
     private readonly abort;
     private leaseLost;
     private cancelSeen;
-    constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number);
+    private isSettled;
+    private readonly backoffMs;
+    private readonly backoffMaxMs;
+    constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number, opts?: TaskContextOptions);
     get taskId(): string;
     get name(): string;
     get queue(): string;
@@ -20,6 +35,14 @@ export declare class TaskContext {
     get rootId(): string | null;
     get correlationId(): string | null;
     get payload(): any;
+    /**
+     * True once this task reached a terminal state — whether the handler settled
+     * it with succeed()/fail() or the worker settled it on the handler's behalf.
+     * The heartbeat and the settlement paths both read it.
+     */
+    get settled(): boolean;
+    /** @internal Called by the worker when it finalizes this task itself. */
+    markSettled(): void;
     /**
      * True once this worker has lost the task's lease — it expired and another
      * worker reclaimed it. Nothing this handler writes will be recorded any more
@@ -32,11 +55,34 @@ export declare class TaskContext {
     /** @internal Called by the worker when an owned write reports a lost lease. */
     markLeaseLost(): void;
     private observe;
+    /**
+     * @internal The same observation from just the flag, for a caller that read it
+     * without materializing a Task — the shared heartbeat, whose statement returns
+     * only the id and the cancel column precisely so it does not have to drag
+     * every payload back on every beat.
+     */
+    observeCancel(cancelRequested: boolean): void;
     private owned;
     progress(value: number | null, message?: string | null): Promise<Task>;
     heartbeat(): Promise<Task>;
     /** Cooperative cancel check. Free once a heartbeat has already seen the flag. */
     canceled(): Promise<boolean>;
+    /**
+     * Finalize this task as succeeded, now, without waiting for the handler to
+     * return. `complete` semantics: a cancel requested while it ran wins and the
+     * task finalizes as canceled instead, its result discarded. Returns null if
+     * this task was already settled.
+     */
+    succeed(result?: unknown): Promise<Task | null>;
+    /**
+     * Finalize this task as failed, now. `error` may be a string reason, an Error,
+     * a TaskError (which carries its own retryability), or a ready envelope.
+     * Retryable failures get the worker's backoff and are re-queued while attempts
+     * remain, exactly as a thrown error would be. Returns null if already settled.
+     */
+    fail(error?: FailReason, opts?: {
+        retryable?: boolean;
+    }): Promise<Task | null>;
     /** Submit a child task; parent/root/correlation are wired automatically. */
     submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;
     submit<P, R>(task: TaskDef<P, R>, payload?: P, opts?: SubmitOptions): Promise<Task>;