cairnq 0.5.0 → 0.6.0

package/README.md

@@ -66,8 +66,9 @@ 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
 });
 

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

package/dist/context.js

@@ -1,8 +1,16 @@
-import { LostLease } from "./errors.js";
+import { DEFAULT_RETRY_BACKOFF_MAX_MS, DEFAULT_RETRY_BACKOFF_MS, failDelayMs } from "./backoff.js";
+import { asEnvelope, LostLease } from "./errors.js";
 import { cancelRequested } from "./models.js";
 import { taskName } from "./task.js";
 import { pollWait } from "./wait.js";
-/** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
+/**
+ * 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 class TaskContext {
     store;
     task;
@@ -13,11 +21,20 @@ export class TaskContext {
     // Cancellation is monotonic: once the DB has told us a cancel was requested it
     // can't be taken back, so canceled() can answer from this without a re-read.
     cancelSeen = false;
-    constructor(store, task, workerId, leaseMs) {
+    // Set once this task reached a terminal state through succeed()/fail(). The
+    // worker reads it to know which tasks a batch handler already decided, so it
+    // neither settles them twice nor keeps renewing their leases — the bookkeeping
+    // every ack/nack-style handler otherwise has to carry itself.
+    isSettled = false;
+    backoffMs;
+    backoffMaxMs;
+    constructor(store, task, workerId, leaseMs, opts = {}) {
         this.store = store;
         this.task = task;
         this.workerId = workerId;
         this.leaseMs = leaseMs;
+        this.backoffMs = opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+        this.backoffMaxMs = opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS;
     }
     get taskId() {
         return this.task.id;
@@ -43,6 +60,18 @@ export class TaskContext {
     get payload() {
         return this.task.payload;
     }
+    /**
+     * 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() {
+        return this.isSettled;
+    }
+    /** @internal Called by the worker when it finalizes this task itself. */
+    markSettled() {
+        this.isSettled = true;
+    }
     /**
      * 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
@@ -66,18 +95,37 @@ export class TaskContext {
     // Every owned write returns the current row, so cancellation and lease loss
     // ride along on writes the handler was making anyway.
     observe(task) {
-        if (cancelRequested(task))
-            this.cancelSeen = true;
+        this.observeCancel(cancelRequested(task));
         return task;
     }
+    /**
+     * @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) {
+        if (cancelRequested)
+            this.cancelSeen = true;
+    }
     async owned(write) {
-        // Short-circuit once the lease is known lost: nothing this context writes
-        // may be recorded any more. Locally, not just via the store's ownership
-        // check — after an abandoned (timed-out) attempt the same worker may
-        // re-claim this task under the same workerId, and a zombie handler's write
-        // would then pass ownership against the NEW attempt.
+        // One gate for every write through this context, so "may I still write?" is
+        // answered in one place rather than at each call site.
+        //
+        // Lease lost: nothing this context writes may be recorded any more. Checked
+        // locally, not just via the store's ownership check — after an abandoned
+        // (timed-out) attempt the same worker may re-claim this task under the same
+        // workerId, and a zombie handler's write would then pass ownership against
+        // the NEW attempt.
         if (this.leaseLost)
             throw new LostLease(this.task.id);
+        // Settled: the task is terminal, so the statement would match no row and come
+        // back as a lost lease — telling the handler "another worker took this" when
+        // the truth is "you already finished it", and flipping lostLease on the way.
+        // Refuse here instead, without the round trip and without corrupting the
+        // lease state.
+        if (this.isSettled)
+            throw new LostLease(this.task.id);
         try {
             return this.observe(await write());
         }
@@ -113,6 +161,49 @@ export class TaskContext {
             this.cancelSeen = true;
         return this.cancelSeen || t.status === "canceled";
     }
+    // ------------------------------------------------------------- settlement
+    // Finalizing a task is normally the worker's job, decided by whether the
+    // handler returned or threw. These two let a handler decide one task itself,
+    // which is what a batch needs: four of 256 tasks failing for four different
+    // reasons is the ordinary case, not the edge one, and it cannot be expressed
+    // by a single return value or a single throw.
+    //
+    // Settling twice is a no-op rather than an error. Handlers built on ack/nack
+    // queues all end up carrying a `finalizedIds` set to guarantee exactly that;
+    // holding it here instead is the point.
+    /**
+     * 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.
+     */
+    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 }));
+        this.markSettled();
+        return task;
+    }
+    /**
+     * 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.
+     */
+    async fail(error = "task failed", opts = {}) {
+        if (this.isSettled)
+            return null;
+        const [envelope, retryable] = asEnvelope(error, opts.retryable ?? true);
+        const task = await this.owned(() => this.store.fail({
+            taskId: this.task.id,
+            workerId: this.workerId,
+            error: envelope,
+            retryable,
+            delayMs: failDelayMs(this.task.attempt, retryable, this.backoffMs, this.backoffMaxMs),
+        }));
+        this.markSettled();
+        return task;
+    }
     async submit(task, payload, opts = {}) {
         return this.store.submit({
             name: taskName(task),

package/dist/errors.d.ts

@@ -9,6 +9,15 @@ export declare function errorEnvelope(e: {
     retryable: boolean;
     details?: Record<string, unknown>;
 }): Record<string, unknown>;
+/**
+ * How an arbitrary thrown value becomes an envelope. Split out from `asEnvelope`
+ * below because the worker also reaches it directly, for a thrown plain object —
+ * which `asEnvelope` reads as a ready envelope, the right call for `ctx.fail` and
+ * the wrong one for something that was thrown. Both must agree on `code` and on
+ * deriving `type` from the error's name, or the same error reads differently
+ * depending on which way it was recorded.
+ */
+export declare function exceptionEnvelope(err: unknown, retryable?: boolean): Record<string, unknown>;
 export declare class CairnQError extends Error {
     constructor(message?: string);
 }
@@ -84,3 +93,21 @@ export declare class TaskError extends CairnQError {
     });
     envelope(): Record<string, unknown>;
 }
+/** What a handler may pass to `ctx.fail`. */
+export type FailReason = string | Error | TaskError | Record<string, unknown>;
+/**
+ * Normalize anything that can end a task into [envelope, retryable].
+ *
+ * Shared by both ways a failure is recorded — a handler passing a reason to
+ * `ctx.fail`, and the worker classifying an error that ended an attempt — so the
+ * two cannot disagree about what a given error means. It lives here, beside the
+ * envelope constructors it dispatches to, rather than in the module that happens
+ * to expose it to handlers.
+ *
+ * A handler failing one task of a batch has a reason, not an exception object:
+ * `item.fail("no source records", { retryable: false })` is the shape the real
+ * code wants. A TaskError carries its own retryability and wins over the option;
+ * everything else takes the caller's. A ready envelope passes through, which is
+ * how the worker hands in the ones it composes itself.
+ */
+export declare function asEnvelope(error: FailReason, retryable: boolean): [Record<string, unknown>, boolean];