cairnq 0.5.0 → 0.7.0

package/dist/store/base.d.ts

@@ -11,7 +11,7 @@ export declare function dumpJson(value: unknown): string;
  * The supported major is a protocol fact, not a dialect one — every backend
  * checks it here so the constant can't fork per store. */
 export declare function checkProtocolVersion(version: number): void;
-declare const CONFLICTS: readonly ["reuse", "reject", "replace"];
+declare const CONFLICTS: readonly ["reuse", "reuse-succeeded", "reject", "replace"];
 export type Conflict = (typeof CONFLICTS)[number];
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */
@@ -174,11 +174,60 @@ export declare abstract class TaskStore {
         limit?: number;
         names?: string[];
     }): Promise<Task[]>;
+    /**
+     * Open one claim transaction and let the caller draw from it repeatedly.
+     *
+     * The transaction is what has to live here: the read-only probe that keeps an
+     * idle worker off SQLite's single write lock, the `recover_leases` whose
+     * reclaimed leases must be visible to the claims that follow and to nobody in
+     * between, and the write lock itself. *What* gets claimed under it is the
+     * caller's business — a worker drawing a separate quota per task name is
+     * scheduling policy, and this layer has no vocabulary for the "handler call"
+     * that policy is denominated in. It knows queues, names, limits and rows.
+     *
+     * `plan` is handed a `claim(names, limit)` it may call any number of times,
+     * each a separate statement under the same lock and the same recovery, and
+     * each free to size itself from what the previous one returned. That feedback
+     * is the reason this is a callback rather than a list of quotas: a caller
+     * dividing a budget up front has to guess, and every share handed to a name
+     * with nothing queued is a slot left idle until the next poll.
+     *
+     * `plan` runs with the write lock held, so it must await nothing but that
+     * callback.
+     *
+     * `names` is the union `plan` might ask for — the probe and the recovery are
+     * filtered by it. Returns undefined when the probe finds nothing claimable, in
+     * which case `plan` never runs and no transaction is opened.
+     */
+    claimSession<T>(input: {
+        queues: string[];
+        workerId: string;
+        leaseMs?: number;
+        names: string[] | null;
+    }, plan: (claim: (names: string[] | null, limit: number) => Promise<Task[]>) => Promise<T>): Promise<T | undefined>;
     heartbeat(input: {
         taskId: string;
         workerId: string;
         leaseMs?: number;
     }): Promise<Task>;
+    /**
+     * Renew several leases in one statement. Returns `taskId -> cancel requested`
+     * for the tasks this worker still holds.
+     *
+     * Deliberately not an ownedWrite: ownership is per task here, so there is no
+     * single answer to "did it work". A task **absent** from the result lost its
+     * lease, and the caller decides what that means for that one task rather than
+     * failing the whole beat.
+     *
+     * It returns flags rather than Tasks because nothing downstream needs a task:
+     * the caller renews leases and observes cancellation, and whole rows would drag
+     * every payload back on every beat for the life of the call.
+     */
+    heartbeatBatch(input: {
+        taskIds: string[];
+        workerId: string;
+        leaseMs?: number;
+    }): Promise<Map<string, boolean>>;
     progress(input: {
         taskId: string;
         workerId: string;

package/dist/store/base.js

@@ -1,6 +1,6 @@
 import { newId } from "../ids.js";
 import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, } from "../errors.js";
-import { rowToTask, STATUSES } from "../models.js";
+import { rowToTask, STATUSES, TERMINAL } from "../models.js";
 import { QueueDepthGate } from "../backpressure.js";
 const rejectMangled = function (_key, v) {
     if (typeof v === "number" && !Number.isFinite(v)) {
@@ -51,7 +51,24 @@ export function checkProtocolVersion(version) {
 // CONFLICTS is the canonical declaration; the type derives from it so the
 // runtime guard in submit() and the type can't drift apart (same pattern as
 // STATUSES/TaskStatus in models.ts).
-const CONFLICTS = ["reuse", "reject", "replace"];
+const CONFLICTS = ["reuse", "reuse-succeeded", "reject", "replace"];
+/**
+ * Whether a keyed submit's strategy accepts the task the key already points at.
+ *
+ * Both reuse strategies deduplicate work that is still in play — that is what a
+ * key is for, and the answer cannot depend on the outcome of a task that has no
+ * outcome yet. They differ only on what a *finished* task means: `reuse` treats
+ * the key as free again, while `reuse-succeeded` reads a succeeded task as a
+ * cached result. Neither ever hands back a failed or canceled one, which would
+ * poison the key for every later submit (see PROTOCOL.md "Key conflict").
+ */
+function reusable(conflict, status) {
+    if (conflict === "replace")
+        return false;
+    if (!TERMINAL.includes(status))
+        return true;
+    return conflict === "reuse-succeeded" && status === "succeeded";
+}
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */
 export const DEFAULT_QUEUE = "default";
@@ -207,12 +224,17 @@ export class TaskStore {
                 // free after all, whatever the strategy.
                 const current = (await fetch("get", { id: existing[0].task_id }))[0];
                 if (current) {
-                    if (conflict === "reuse")
-                        return rowToTask(current);
                     if (conflict === "reject")
                         throw new AlreadyExists(key);
-                    // "replace": cancel the recorded task, then repoint the key below.
-                    await fetch("cancel", { id: existing[0].task_id });
+                    if (reusable(conflict, current.status))
+                        return rowToTask(current);
+                    // The strategy declined the recorded task, so the key repoints to the
+                    // fresh one inserted below. Cancel only what is still live: a terminal
+                    // task has nothing to stop, and cancelling it would rewrite a settled
+                    // row (and hand a `canceled` back to whoever is waiting on it).
+                    if (!TERMINAL.includes(current.status)) {
+                        await fetch("cancel", { id: existing[0].task_id });
+                    }
                 }
             }
             const row = (await fetch("insert_task", ins))[0];
@@ -330,27 +352,77 @@ export class TaskStore {
      * array claims nothing.
      */
     async claim(input) {
-        // One queue is the common case and gets its own statement: a list-valued queue
-        // filter cannot be read in claim order, so the planner sorts every claimable
-        // row to take LIMIT of them, and claim's cost grows with the queued backlog
-        // while it holds the claim transaction. See claim_one_queue.sql.
+        const names = input.names ?? null;
+        const claimed = await this.claimSession({ queues: input.queues, workerId: input.workerId, leaseMs: input.leaseMs, names }, (claim) => claim(names, input.limit ?? 1));
+        return claimed ?? [];
+    }
+    /**
+     * Open one claim transaction and let the caller draw from it repeatedly.
+     *
+     * The transaction is what has to live here: the read-only probe that keeps an
+     * idle worker off SQLite's single write lock, the `recover_leases` whose
+     * reclaimed leases must be visible to the claims that follow and to nobody in
+     * between, and the write lock itself. *What* gets claimed under it is the
+     * caller's business — a worker drawing a separate quota per task name is
+     * scheduling policy, and this layer has no vocabulary for the "handler call"
+     * that policy is denominated in. It knows queues, names, limits and rows.
+     *
+     * `plan` is handed a `claim(names, limit)` it may call any number of times,
+     * each a separate statement under the same lock and the same recovery, and
+     * each free to size itself from what the previous one returned. That feedback
+     * is the reason this is a callback rather than a list of quotas: a caller
+     * dividing a budget up front has to guess, and every share handed to a name
+     * with nothing queued is a slot left idle until the next poll.
+     *
+     * `plan` runs with the write lock held, so it must await nothing but that
+     * callback.
+     *
+     * `names` is the union `plan` might ask for — the probe and the recovery are
+     * filtered by it. Returns undefined when the probe finds nothing claimable, in
+     * which case `plan` never runs and no transaction is opened.
+     */
+    async claimSession(input, plan) {
+        // A list-valued filter cannot be read in claim order, so the planner sorts
+        // every claimable row to take LIMIT of them and the claim's cost grows with
+        // the backlog while it holds the transaction. Both filters therefore have an
+        // equality form, picked per draw: one queue is the common deployment, and one
+        // name is every per-name quota. See claim_one_queue.sql and claim_one_name.sql.
         const oneQueue = input.queues.length === 1;
-        const params = {
+        const base = {
             queues: input.queues,
             queue: oneQueue ? input.queues[0] : null,
-            names: input.names ?? null,
+            names: input.names,
+            name: null,
             worker_id: input.workerId,
             lease_ms: input.leaseMs ?? 30_000,
-            limit: input.limit ?? 1,
+            limit: 1,
             lease_expired_error: LEASE_EXPIRED_ERROR_JSON,
         };
-        if (!(await this.hasClaimableWork(params)))
-            return [];
-        // Recovery must share the claim's transaction: a lease reclaimed here has to
-        // be visible to the claim that follows, and to nobody in between.
+        if (!(await this.hasClaimableWork(base)))
+            return undefined;
         return this.tx(async (fetch) => {
-            await fetch("recover_leases", params);
-            return (await fetch(oneQueue ? "claim_one_queue" : "claim", params)).map(rowToTask);
+            await fetch("recover_leases", base);
+            return plan(async (names, limit) => {
+                // A draw asking for nothing, or filtered to no names, claims nothing —
+                // answer it here rather than spending a statement to learn that.
+                if (limit <= 0 || names?.length === 0)
+                    return [];
+                const oneName = names?.length === 1;
+                const statement = oneName
+                    ? oneQueue
+                        ? "claim_one_queue_one_name"
+                        : "claim_one_name"
+                    : oneQueue
+                        ? "claim_one_queue"
+                        : "claim";
+                const rows = await fetch(statement, {
+                    ...base,
+                    names,
+                    name: oneName ? names[0] : null,
+                    limit,
+                });
+                return rows.map(rowToTask);
+            });
         });
     }
     async heartbeat(input) {
@@ -360,6 +432,29 @@ export class TaskStore {
             lease_ms: input.leaseMs ?? 30_000,
         });
     }
+    /**
+     * Renew several leases in one statement. Returns `taskId -> cancel requested`
+     * for the tasks this worker still holds.
+     *
+     * Deliberately not an ownedWrite: ownership is per task here, so there is no
+     * single answer to "did it work". A task **absent** from the result lost its
+     * lease, and the caller decides what that means for that one task rather than
+     * failing the whole beat.
+     *
+     * It returns flags rather than Tasks because nothing downstream needs a task:
+     * the caller renews leases and observes cancellation, and whole rows would drag
+     * every payload back on every beat for the life of the call.
+     */
+    async heartbeatBatch(input) {
+        if (!input.taskIds.length)
+            return new Map();
+        const rows = await this.fetch("heartbeat_batch", {
+            ids: input.taskIds,
+            worker_id: input.workerId,
+            lease_ms: input.leaseMs ?? 30_000,
+        });
+        return new Map(rows.map((r) => [r.id, r.cancel_requested_at_ms != null]));
+    }
     async progress(input) {
         return this.ownedWrite("progress", input.taskId, {
             id: input.taskId,

package/dist/store/sqlite.js

@@ -313,7 +313,10 @@ export class SQLiteStore extends TaskStore {
                     bound[name] = now - params.older_than_ms;
                     break;
                 case "queues":
-                    bound[name] = JSON.stringify(params.queues);
+                case "ids":
+                    // json_each needs a JSON array. Postgres binds the array itself as
+                    // text[], so only this dialect encodes.
+                    bound[name] = JSON.stringify(params[name]);
                     break;
                 case "names":
                     // json_each needs a JSON array; null stays null so the SQL's

package/dist/wait.d.ts

@@ -2,6 +2,11 @@ import { type Task } from "./models.js";
 import type { TaskStore } from "./store/base.js";
 export declare const DEFAULT_POLL_MS = 100;
 export declare const MAX_POLL_MS = 500;
+export interface PollOptions {
+    timeoutMs: number;
+    pollMs?: number;
+    maxPollMs?: number;
+}
 /**
  * Grow the polling interval towards the ceiling.
  *
@@ -14,8 +19,18 @@ export declare function nextPollMs(current: number, maxMs: number): number;
 /** Poll get() until terminal or timeout. Returns the terminal Task (any status).
  * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
  * it backs off towards `maxPollMs`. */
-export declare function pollWait(store: TaskStore, taskId: string, { timeoutMs, pollMs, maxPollMs, }: {
-    timeoutMs: number;
-    pollMs?: number;
-    maxPollMs?: number;
-}): Promise<Task>;
+export declare function pollWait(store: TaskStore, taskId: string, opts: PollOptions): Promise<Task>;
+/**
+ * The same wait, following a key instead of an id.
+ *
+ * The key is re-resolved on every read, because that is what a key means: a
+ * pointer to the task that is *current* under it. A `replace` landing mid-wait
+ * moves the wait onto the new task rather than reporting the cancellation of the
+ * old one, and a key that points at nothing yet is simply not finished — it
+ * polls until something appears, the same way waiting on an id that does not
+ * exist yet does.
+ *
+ * There is nothing to subscribe to before the key resolves, so those naps are
+ * plain sleeps; once it resolves, the store's push channel applies as usual.
+ */
+export declare function pollWaitByKey(store: TaskStore, key: string, opts: PollOptions): Promise<Task>;

package/dist/wait.js

@@ -4,6 +4,7 @@ import { isTerminal } from "./models.js";
 export const DEFAULT_POLL_MS = 100;
 export const MAX_POLL_MS = 500;
 const GROWTH = 1.5;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Grow the polling interval towards the ceiling.
  *
@@ -15,22 +16,46 @@ const GROWTH = 1.5;
 export function nextPollMs(current, maxMs) {
     return Math.min(maxMs, Math.max(current + 1, Math.floor(current * GROWTH)));
 }
-/** Poll get() until terminal or timeout. Returns the terminal Task (any status).
- * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
- * it backs off towards `maxPollMs`. */
-export async function pollWait(store, taskId, { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS, }) {
+/**
+ * Poll `read` until it yields a terminal task, or the timeout elapses.
+ *
+ * `wake` is what the loop sleeps on between reads: a store with a push channel
+ * (Postgres) cuts it short when the task goes terminal, but the re-read is the
+ * source of truth either way, so a plain sleep is always a correct answer.
+ */
+async function poll(read, wake, subject, key, { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS }) {
     const deadline = nowMs() + timeoutMs;
     let interval = pollMs;
     for (;;) {
-        const task = await store.get(taskId);
+        const task = await read();
         if (task && isTerminal(task))
             return task;
         const remaining = deadline - nowMs();
         if (remaining <= 0)
-            throw new TaskTimeout(taskId, { timeoutMs, task });
-        // A store with a push channel (Postgres) cuts the sleep short when the task
-        // goes terminal; the re-get above stays the source of truth either way.
-        await store.taskDoneWake(taskId, Math.min(interval, remaining));
+            throw new TaskTimeout(task?.id ?? subject, { timeoutMs, task, key });
+        await wake(task, Math.min(interval, remaining));
         interval = nextPollMs(interval, maxPollMs);
     }
 }
+/** Poll get() until terminal or timeout. Returns the terminal Task (any status).
+ * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
+ * it backs off towards `maxPollMs`. */
+export function pollWait(store, taskId, opts) {
+    return poll(() => store.get(taskId), (_task, ms) => store.taskDoneWake(taskId, ms), taskId, null, opts);
+}
+/**
+ * The same wait, following a key instead of an id.
+ *
+ * The key is re-resolved on every read, because that is what a key means: a
+ * pointer to the task that is *current* under it. A `replace` landing mid-wait
+ * moves the wait onto the new task rather than reporting the cancellation of the
+ * old one, and a key that points at nothing yet is simply not finished — it
+ * polls until something appears, the same way waiting on an id that does not
+ * exist yet does.
+ *
+ * There is nothing to subscribe to before the key resolves, so those naps are
+ * plain sleeps; once it resolves, the store's push channel applies as usual.
+ */
+export function pollWaitByKey(store, key, opts) {
+    return poll(() => store.getByKey(key), (task, ms) => (task ? store.taskDoneWake(task.id, ms) : sleep(ms)), key, key, opts);
+}

package/dist/worker.d.ts

@@ -2,9 +2,20 @@ import type { BackpressureOptions } from "./backpressure.js";
 import { TaskContext } from "./context.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
+export { retryDelayMs, DEFAULT_RETRY_BACKOFF_MS, DEFAULT_RETRY_BACKOFF_MAX_MS } from "./backoff.js";
 export type Handler = (ctx: TaskContext, payload: any) => unknown | Promise<unknown>;
 /** Handler typed against a TaskDef<P, R>: payload is P, the return is R. */
 export type TypedHandler<P, R> = (ctx: TaskContext, payload: P) => R | Promise<R>;
+/**
+ * A batch handler takes one argument: the list of contexts. There is no payload
+ * shortcut to pair with it — payloads are per task, so they are read off the
+ * items (`item.payload`), which is also what a handler must hold to settle one
+ * of them.
+ *
+ * Returning a map of task id -> result fills in results for the tasks the
+ * handler did not settle itself; anything else returned is ignored.
+ */
+export type BatchHandler = (items: TaskContext[]) => void | Record<string, unknown> | Promise<void | Record<string, unknown>>;
 /** Where an error the worker recovered from came from. */
 export type ErrorPhase = "claim" | "execute";
 /**
@@ -13,6 +24,12 @@ export type ErrorPhase = "claim" | "execute";
  * there is usually no CairnQ handle to have configured the store.
  */
 export interface WorkerOptions extends Partial<BackpressureOptions> {
+    /**
+     * Handler calls allowed to run at once. A batch call counts as one, however
+     * many tasks it carries — size it for how much work you want in flight, not
+     * for how many tasks that comes to. Per-name limits refine it; `maxInFlightBytes`
+     * bounds memory, which task counts never did.
+     */
     concurrency?: number;
     leaseMs?: number;
     heartbeatIntervalMs?: number;
@@ -41,15 +58,29 @@ export interface WorkerOptions extends Partial<BackpressureOptions> {
      * between megabytes and gigabytes resident. Once the budget is spent the
      * worker stops claiming until running handlers give it back.
      *
-     * The bound is on tasks already executing. A claim commits to a whole batch
-     * before any size is known, so one batch can overshoot by up to `claimBatch`
-     * payloads; lower `claimBatch` to tighten that. A single payload larger than
-     * the entire budget still runs — alone, rather than deadlocking the worker.
+     * The bound is on tasks already executing: it is read between claims, never
+     * during one, and a claim commits to its rows before any size is known. One
+     * poll can therefore overshoot by up to `claimBatch` rows per registered name
+     * (or one whole `batch`, whichever is larger). Lower `claimBatch`, or the batch
+     * sizes, to tighten that. A single payload larger than the entire budget still
+     * runs — alone, rather than deadlocking the worker.
      *
      * Costs one JSON serialization per task to measure, so it is only computed
      * when set. Unset disables the budget.
      */
     maxInFlightBytes?: number;
+    /**
+     * Call ceilings that several names can draw from, by name — `{ gpu: 1 }`.
+     * A handler joins one with `task(name, { resource: "gpu" }, fn)`.
+     *
+     * `concurrency` caps a name against itself, which cannot say what usually
+     * binds a worker doing heavy local work: several *different* handlers
+     * contending for one scarce thing — a GPU, an index that tolerates a single
+     * writer. The limit belongs to that thing rather than to any one name, so it
+     * is declared here, once, and at capacity 1 it is mutual exclusion across the
+     * names that join it.
+     */
+    resources?: Record<string, number>;
     /**
      * Called for errors the worker survived — a claim that threw, a store write
      * that failed while finalizing a task. Without it these are silent: the run
@@ -61,8 +92,6 @@ export interface WorkerOptions extends Partial<BackpressureOptions> {
         taskId?: string;
     }) => void;
 }
-/** Exponential backoff for the next attempt of a task that just failed. */
-export declare function retryDelayMs(attempt: number, baseMs: number, maxMs: number): number;
 export declare class Worker {
     private readonly store;
     private readonly queues;
@@ -71,6 +100,27 @@ export declare class Worker {
     private readonly workerId;
     /** Payload bytes charged to running handlers — see maxInFlightBytes. */
     private inFlightBytes;
+    /** Calls in flight, for the names that cap their own concurrency. */
+    private readonly callsInFlight;
+    /**
+     * Calls holding units of each declared resource. A resource is the same shape
+     * of budget as a name's own `concurrency` — a ceiling on calls — differing
+     * only in who draws from it: several names rather than one. That is what
+     * expresses "these handlers share one GPU" without inventing a queue per
+     * resource.
+     */
+    private readonly resourceCalls;
+    /** Rotates which source is offered the free budget first — see loop(). */
+    private claimCursor;
+    /** Invalidated by task(); see schedule(). */
+    private scheduleCache;
+    /**
+     * Retry backoff, resolved once. Both settlement paths read these — the
+     * worker's own `safeFail` and the TaskContext it hands a handler — so
+     * resolving the defaults per call site is how the two drift apart.
+     */
+    private readonly backoffMs;
+    private readonly backoffMaxMs;
     private stopped;
     private stopWake;
     private readonly stopped$;
@@ -90,6 +140,30 @@ export declare class Worker {
     task(handler: Handler): this;
     task(name: string, handler: Handler): this;
     task<P, R>(def: TaskDef<P, R>, handler: TypedHandler<P, R>): this;
+    /**
+     * Batch delivery: the handler takes one argument, a `TaskContext[]` of up to
+     * `batch` tasks, instead of `(ctx, payload)`. Use it when the work itself is
+     * batched — one embedding call over 256 texts rather than 256 calls — and size
+     * it by what the downstream API wants, not by the queue.
+     *
+     * `concurrency` caps the calls this name may run at once, under the worker's
+     * own. Use it to keep one expensive name from taking the whole worker.
+     *
+     * `resource` draws each call from a ceiling declared in
+     * `WorkerOptions.resources` and shared with every other name that names it —
+     * at capacity 1, mutual exclusion across those names.
+     */
+    task(name: string | TaskDef, opts: {
+        batch: number;
+        concurrency?: number;
+        resource?: string;
+    }, handler: BatchHandler): this;
+    /** Per-name concurrency or a shared resource, without batching: the handler
+     * still takes `(ctx, payload)`. */
+    task(name: string | TaskDef, opts: {
+        concurrency?: number;
+        resource?: string;
+    }, handler: Handler): this;
     stop(): void;
     /** Close the underlying store connection. Call after run() returns. */
     close(): Promise<void>;
@@ -98,6 +172,52 @@ export declare class Worker {
     run(opts?: {
         concurrency?: number;
     }): Promise<void>;
+    /**
+     * Split one claim into handler calls, each with the registration to run it.
+     *
+     * A claim is filtered by queue and by the names this worker handles, so it
+     * comes back mixed; batch size is per name (one embedding call wants 256
+     * texts, one Docling parse wants exactly 1). So group by name, then chunk each
+     * group by that name's size. Names registered without `batch` come back as
+     * one-task calls, as do names not registered at all — reachable only if a
+     * handler is unregistered mid-run, and dispatched to failNoHandler().
+     *
+     * The registration rides along because this is where it was resolved; looking
+     * it up again at the call site would put "is this name batched" in two places.
+     */
+    private deliveries;
+    private context;
+    /**
+     * How this poll's claim is split into per-name quotas, plus the union of names
+     * the probe spans.
+     *
+     * Cached and invalidated by `task()`, rather than rebuilt each poll: handlers
+     * may be registered after run() started, but only there, and this otherwise
+     * allocates a source per name on every tick for a worker's whole lifetime.
+     *
+     * A name that limits itself — by `batch`, by its own `concurrency`, or by a
+     * `resource` — needs a quota the shared draw cannot express, so it gets a
+     * source of its own; every other name shares one, where a task is a call.
+     *
+     * A resource is deliberately *not* one source spanning its names: `batch` is
+     * per name, and a single source carries one batch size, so two members that
+     * batch differently could not share a draw. Keeping a source per name and
+     * letting several of them draw down one shared ceiling composes with batching
+     * instead of excluding it.
+     */
+    private schedule;
+    /**
+     * A source's own call ceiling for one poll, or undefined when only the
+     * worker-wide budget applies.
+     *
+     * Three independent ceilings, whichever binds first: the name's own concurrency
+     * less what it is already running; its resource's capacity less what is running
+     * *and* what earlier draws in this same poll already took (`taken`); and
+     * `claimBatch`. The last is a ceiling on *rows* per poll, so it converts at this
+     * source's batch size — and never below one call, or a `claimBatch` under some
+     * name's batch would stall that name outright.
+     */
+    private sourceCalls;
     private loop;
     /** Blocking-style entry point for a standalone worker process: run until
      * SIGINT/SIGTERM, then close the store. Use this at a script's top level;
@@ -110,20 +230,98 @@ export declare class Worker {
         concurrency?: number;
     }): Promise<T>;
     /**
-     * Run one task to completion. Never rejects: a task-level failure is reported
-     * through onError and the loop moves on. (It used to reject into a promise
-     * nobody awaited — an unhandled rejection that took the process down.)
+     * Record a claimed task this worker cannot run. Reachable only if a name is
+     * unregistered mid-run — the claim filters on the registered names — so it does
+     * not start a handler or a heartbeat for a task it will not run.
+     */
+    private failNoHandler;
+    /**
+     * Run one handler call to completion — one task, or a whole batch. Never
+     * rejects: a task-level failure is reported through onError and the loop moves
+     * on. (It used to reject into a promise nobody awaited — an unhandled rejection
+     * that took the process down.)
+     *
+     * One lifecycle for both delivery modes, because a single-task handler *is* the
+     * one-element case: the same heartbeat covers the call, the same classifier
+     * reads its error, and the same rule settles what is left. Only two things vary
+     * — how the handler is invoked, and where a leftover task's result comes from —
+     * so those are the only two branches below.
+     *
+     * The contract is single: **when the handler returns, every task it did not
+     * settle itself is settled by how the call ended.** Returning succeeds them,
+     * throwing fails them (retryably, or as the thrown TaskError says). That is
+     * what keeps the ordinary cases free of bookkeeping — a handler that just
+     * returns has finished 256 tasks — while still letting it pick individual
+     * tasks off with `item.succeed()` / `item.fail()` as it goes.
+     *
+     * For a batch, a returned map of task id -> result fills in results for the
+     * tasks left over; anything else returned is ignored, and unmentioned tasks
+     * succeed with no result (the common shape, where the handler's output went to
+     * a database rather than into the task row). For a single task the return value
+     * simply is the result.
      */
-    private execute;
+    private runCall;
     /**
-     * Run one attempt, bounded by maxRunMs when set. On timeout the attempt is
-     * abandoned: the context is flagged lease-lost first (ctx.signal aborts, and
-     * a handler that keeps running can never write again — see
-     * TaskContext.owned), then the still-pending promise is left to settle on
-     * its own, its outcome discarded. The caller records the handler_timeout
-     * failure; lease recovery is NOT involved, so redelivery is immediate.
+     * How an attempt that ended badly is recorded: [envelope, retryable], or null
+     * when there is nothing to record.
+     *
+     * One classifier for both delivery modes, so a handler error cannot mean
+     * different things depending on how its task happened to be delivered. That
+     * includes LostLease, which is not an outcome at all: it means a write through
+     * this context was already rejected, so recording anything more would be
+     * rejected too. Both modes then leave the task alone — the single-task one has
+     * nothing else to do, and a batch lets its remaining tasks fall to lease expiry
+     * and redelivery rather than stamping them with a failure the handler never
+     * reported.
+     */
+    private outcomeOf;
+    /**
+     * Finalize one task the handler left for the worker to decide — the tail of
+     * both delivery modes.
+     *
+     * Includes the unserializable-result rule: the handler succeeded but its value
+     * cannot cross the JSON protocol (BigInt, non-finite number, circular), which
+     * is deterministic, so it fails permanently rather than being redelivered to
+     * fail the same way every attempt.
+     */
+    private succeedOne;
+    /**
+     * Settle every task the handler did not settle itself, concurrently, reporting
+     * rather than throwing. Each task keeps its own attempt count and backoff —
+     * they are separate tasks that happened to be delivered together.
+     *
+     * allSettled, because one task's write failing must not abandon the rest of the
+     * batch mid-settlement — the others still hold leases and would sit `running`
+     * until expiry. Each outcome is reported against the task it belongs to;
+     * without that, an operator learns a settlement failed somewhere in a batch of
+     * 256.
+     */
+    private settleEach;
+    /**
+     * Run one attempt — of one task or of a whole batch — bounded by maxRunMs when
+     * set.
+     *
+     * On timeout the attempt is abandoned: every context it covers is flagged
+     * lease-lost first (ctx.signal aborts, and a handler that keeps running can
+     * never write again, nor settle anything behind the worker's back — see
+     * TaskContext.owned), then the still-pending promise is left to settle on its
+     * own, its outcome discarded. The caller records the handler_timeout failure;
+     * lease recovery is NOT involved, so redelivery is immediate.
      */
     private attempt;
+    /**
+     * One statement per beat, however many tasks the call covers — a single-task
+     * handler is just the one-element case.
+     *
+     * Only tasks still in play are renewed. A task the handler already settled is
+     * terminal, and re-leasing it would be a write against a row nobody owns; that
+     * is also why an absence is only read as lease loss after re-checking
+     * `settled`, since the handler may have finalized the task while this beat was
+     * in flight, which takes the row out of `running` and out of the reply. A task
+     * genuinely missing lost its lease (another worker recovered it), so its
+     * context is flagged and the handler stops being able to write through it —
+     * only that one, never its neighbours.
+     */
     private startHeartbeat;
     private safeFail;
     /**