cairnq 0.12.0 → 0.14.0

package/README.md

@@ -34,7 +34,7 @@ Synchronous call (submit + wait):
 import { TaskFailed, TaskTimeout } from "cairnq";
 
 try {
-  const result = await tasks.call("summary.create", { text }, { waitTimeoutMs: 10_000 });
+  const result = await tasks.call("summary.create", { text }, { timeoutMs: 10_000 });
 } catch (err) {
   if (err instanceof TaskFailed) log(err.code, err.message, err.retryable); // envelope fields
   else if (err instanceof TaskTimeout) {
@@ -45,13 +45,11 @@ try {
 }
 ```
 
-Inspect a task by id/key without matching status strings:
+Inspect a task by id/key:
 
 ```ts
-import { isSucceeded } from "cairnq"; // also isFailed/isCanceled/isRunning/isQueued/isTerminal
-
 const task = await tasks.getByKey(key);
-if (task && isSucceeded(task)) use(task.result);
+if (task?.status === "succeeded") use(task.result);
 ```
 
 Optionally define a task once and share the symbol across both ends — no string
@@ -72,19 +70,17 @@ Opt-in: every API still accepts a plain name string (cross-language callers use
 
 ```ts
 const worker = Worker.sqlite("tasks.db", {
-  concurrency: 4,          // handler calls at once; use maxInFlightBytes to bound memory
+  concurrency: 4,          // handler calls at once (a batch call counts as one)
   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, so give the client a retention policy — it sweeps
-// terminal tasks in bounded batches for as long as the handle is open. A
-// per-status map keeps each status on its own clock (statuses left out are
-// never swept): spent results go in minutes, failures stay for diagnosis.
-const tasks = CairnQ.sqlite("tasks.db", {
-  retention: { olderThanMs: { succeeded: 300_000, failed: 7 * 24 * 3600_000 } },
-});
+// Nothing else deletes rows, so give the client a retention cutoff — it sweeps
+// terminal tasks in bounded batches for as long as the handle is open. Tiered
+// retention (per queue, per status) is purge() with filters, from your own
+// scheduler.
+const tasks = CairnQ.sqlite("tasks.db", { retentionMs: 7 * 24 * 3600_000 });
 ```
 
 A handler that does real side effects should bail out when it loses its lease —
@@ -150,24 +146,5 @@ work durable while the task still reads as running — on retry, recomputed. If
 the lease turns out to be gone, the settlement matches no row and the caller's
 writes roll back with it.
 
-## Watching
-
-`watch` calls back when the tasks on a queue may have changed — for a dashboard
-that would otherwise poll:
-
-```ts
-const stop = tasks.watch({ queues: ["render"] }, async (signal) => {
-  if (signal.reason === "done") return refreshOne(signal.taskId!);
-  setCounts(await tasks.stats());
-});
-```
-
-It is notify-accelerated polling, not an event log. On Postgres an idle watch
-costs nothing and a signal lands within milliseconds; where LISTEN is
-unavailable — a transaction-mode pooler, or SQLite, which has no channel — the
-timer alone still delivers `poll` signals. So the same consumer is correct either
-way, and only its promptness differs. Treat a signal as "re-read now"; the truth
-is in `stats()` / `list()` / `get()`.
-
 The protocol (schema + canonical SQL) lives in `../cairnq-protocol` and is shared
 verbatim with the Python SDK. See `../cairnq-protocol/PROTOCOL.md`.

package/dist/_protocol/migrations/postgres/0010_drop_status_index.sql

@@ -0,0 +1,29 @@
+-- Drop cairnq_tasks_status_idx, which nothing can use.
+--
+-- 0001 shipped it for list's status filter. 0007 later added
+-- (status, completed_at_ms) for purge, and a one-column index on the same
+-- leading column is strictly contained in that: any lookup the narrow one could
+-- serve, the wider one serves from its prefix. Confirmed on the statements as
+-- they run — with the status filter specialized to an equality, SQLite picks
+-- cairnq_tasks_status_completed_idx for list and for purge, and never the
+-- narrow index, on a 20k-row table with statistics.
+--
+-- Until specialization existed neither was reachable at all, so this was
+-- invisible: both indexes looked equally unused, and dropping either looked
+-- equally safe or unsafe. It is only once the filters reach an index that one
+-- of them is demonstrably the one reached.
+--
+-- The write cost is what makes it worth removing rather than leaving: every
+-- insert and every status transition — submit, claim, each settle, each retry —
+-- maintains it, which is the hottest write path there is, for a structure no
+-- read consults. The other three of 0001's filter indexes (name, root_id,
+-- correlation_id) stay: each is the only index that serves its filter, and each
+-- is demonstrably read now.
+--
+-- Dropping an index needs no CONCURRENTLY on either dialect and holds a lock
+-- only long enough to unlink it, so unlike 0008 this is not an upgrade window
+-- to plan around. An older SDK is unaffected: it never named the index, and the
+-- statement that used to want it could not reach it anyway.
+drop index if exists cairnq_tasks_status_idx;
+
+update cairnq_meta set value = '10' where key = 'schema_version';

package/dist/_protocol/migrations/sqlite/0010_drop_status_index.sql

@@ -0,0 +1,29 @@
+-- Drop cairnq_tasks_status_idx, which nothing can use.
+--
+-- 0001 shipped it for list's status filter. 0007 later added
+-- (status, completed_at_ms) for purge, and a one-column index on the same
+-- leading column is strictly contained in that: any lookup the narrow one could
+-- serve, the wider one serves from its prefix. Confirmed on the statements as
+-- they run — with the status filter specialized to an equality, SQLite picks
+-- cairnq_tasks_status_completed_idx for list and for purge, and never the
+-- narrow index, on a 20k-row table with statistics.
+--
+-- Until specialization existed neither was reachable at all, so this was
+-- invisible: both indexes looked equally unused, and dropping either looked
+-- equally safe or unsafe. It is only once the filters reach an index that one
+-- of them is demonstrably the one reached.
+--
+-- The write cost is what makes it worth removing rather than leaving: every
+-- insert and every status transition — submit, claim, each settle, each retry —
+-- maintains it, which is the hottest write path there is, for a structure no
+-- read consults. The other three of 0001's filter indexes (name, root_id,
+-- correlation_id) stay: each is the only index that serves its filter, and each
+-- is demonstrably read now.
+--
+-- Dropping an index needs no CONCURRENTLY on either dialect and holds a lock
+-- only long enough to unlink it, so unlike 0008 this is not an upgrade window
+-- to plan around. An older SDK is unaffected: it never named the index, and the
+-- statement that used to want it could not reach it anyway.
+drop index if exists cairnq_tasks_status_idx;
+
+update cairnq_meta set value = '10' where key = 'schema_version';

package/dist/_protocol/sql/postgres/purge.sql

@@ -21,6 +21,20 @@
 -- durable job's log kept for a week. Migration 0009 adds the index that makes
 -- the queue filter read only its own queue's rows rather than skipping past
 -- every other queue's.
+-- The optional form written here is not what runs when a filter IS supplied:
+-- `(:p is null or col = :p)` is planned before the parameter has a value, so
+-- SQLite must plan both branches, reaches no index at all, and walks every row
+-- past the cutoff in completion order. The SDK rewrites each supplied filter to
+-- a plain equality before preparing the statement (`specialize`), which is what
+-- lets the queue and status indexes be reached. That rewrite replaced the three
+-- hand-written variant files this comment used to name.
+--
+-- Postgres does not need the rewrite — it re-plans with the parameter values for
+-- a statement's first executions and folds the null branch away — but it costs
+-- nothing there, and one behaviour is easier to reason about than two.
+--
+-- :name has no specialization: no index covers it, so it is a residual predicate
+-- either way and an equality form would buy nothing.
 -- params: older_than_ms, queue, status, name, limit
 delete from cairnq_tasks
 where id in (

package/dist/_protocol/sql/sqlite/purge.sql

@@ -15,6 +15,20 @@
 -- result read once and a durable job's log kept for a week. Migration 0009 adds
 -- the index that makes the queue filter read only its own queue's rows rather
 -- than skipping past every other queue's.
+-- The optional form written here is not what runs when a filter IS supplied:
+-- `(:p is null or col = :p)` is planned before the parameter has a value, so
+-- SQLite must plan both branches, reaches no index at all, and walks every row
+-- past the cutoff in completion order. The SDK rewrites each supplied filter to
+-- a plain equality before preparing the statement (`specialize`), which is what
+-- lets the queue and status indexes be reached. That rewrite replaced the three
+-- hand-written variant files this comment used to name.
+--
+-- Postgres does not need the rewrite — it re-plans with the parameter values for
+-- a statement's first executions and folds the null branch away — but it costs
+-- nothing there, and one behaviour is easier to reason about than two.
+--
+-- :name has no specialization: no index covers it, so it is a residual predicate
+-- either way and an equality form would buy nothing.
 -- params: before_ms, queue, status, name, limit
 delete from cairnq_tasks
 where id in (

package/dist/backpressure.d.ts

@@ -7,8 +7,6 @@ export interface BackpressureOptions {
     maxQueueDepth: QueueDepthLimit;
     /** How long a blocked submit waits before raising QueueFull. Default 600_000. */
     maxQueueWaitMs?: number;
-    /** First backoff between depth probes; doubles to a 5s ceiling. Default 250. */
-    queuePollIntervalMs?: number;
 }
 /**
  * Blocks `submit` while a queue is at its depth limit.
@@ -37,7 +35,6 @@ export declare class QueueDepthGate {
     private readonly probing;
     private readonly limits;
     private readonly maxWaitMs;
-    private readonly initialProbeMs;
     constructor(store: TaskStore, opts: BackpressureOptions);
     private validate;
     /** The limit for `queue`, or null when it is not gated. */

package/dist/backpressure.js

@@ -44,12 +44,10 @@ export class QueueDepthGate {
     probing = new Map();
     limits;
     maxWaitMs;
-    initialProbeMs;
     constructor(store, opts) {
         this.store = store;
         this.limits = opts.maxQueueDepth;
         this.maxWaitMs = opts.maxQueueWaitMs ?? DEFAULT_MAX_WAIT_MS;
-        this.initialProbeMs = opts.queuePollIntervalMs ?? INITIAL_PROBE_INTERVAL_MS;
         if (typeof this.limits === "number")
             this.validate("*", this.limits);
         else
@@ -80,7 +78,7 @@ export class QueueDepthGate {
         if (limit == null)
             return;
         const startedAt = Date.now();
-        let waitMs = this.initialProbeMs;
+        let waitMs = INITIAL_PROBE_INTERVAL_MS;
         for (;;) {
             const left = this.headroom.get(queue) ?? 0;
             if (left > 0) {

package/dist/client.d.ts

@@ -1,29 +1,50 @@
-import type { BackpressureOptions } from "./backpressure.js";
-import { type RetentionOptions } from "./retention.js";
-import { type Task, type TaskRef, type TaskStatus } from "./models.js";
+import { type Task } from "./models.js";
 import type { PgExecutor } from "./store/pg-executor.js";
-import type { ListInput, PurgeInput, SubmitInput, TaskStore, WatchOptions, WatchSignal } from "./store/base.js";
+import type { Conflict, ListInput, PurgeInput, TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
 import { type PollOptions } from "./wait.js";
-export type SubmitOptions = Omit<SubmitInput, "name" | "payload">;
+/** Per-task options a submit may carry. Everything else about a task — how it
+ * is delivered, retried, batched — is declared once, on the worker. */
+export interface SubmitOptions {
+    queue?: string;
+    /** Business-stable idempotency key; see `conflict` for what a duplicate means. */
+    key?: string | null;
+    conflict?: Conflict;
+    maxAttempts?: number;
+    priority?: number;
+    metadata?: unknown;
+    /** Run no earlier than this many ms from now. */
+    delayMs?: number;
+}
 /** The wait loop's knobs with the timeout optional (default 30s) — the public
  * face of PollOptions, whose comments document each knob. */
 export type WaitOptions = Partial<PollOptions>;
-export interface CallOptions extends SubmitOptions, Omit<WaitOptions, "timeoutMs"> {
-    waitTimeoutMs?: number;
+/** submit + wait in one call: the submit's options and the wait's, together.
+ * `timeoutMs` bounds the wait, not the task. */
+export interface CallOptions extends SubmitOptions, WaitOptions {
 }
 /** Options this handle configures on the store it wraps, rather than the
  * store's own constructor arguments. */
-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;
-};
+export interface ClientOptions {
+    /** Queued tasks a queue may hold before `submit` blocks — a number for every
+     * queue, or a per-queue record that leaves unnamed queues unbounded. `submit`
+     * raises QueueFull if the queue stays full for `maxQueueWaitMs`. */
+    maxQueueDepth?: number | Record<string, number>;
+    /** How long a blocked submit waits before raising QueueFull. Default 600_000. */
+    maxQueueWaitMs?: number;
+    /**
+     * Delete terminal tasks this many ms after they finished, 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. Tiered
+     * retention (per queue, per status) is `purge()` with filters, from your own
+     * scheduler.
+     */
+    retentionMs?: number;
+}
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export declare class CairnQ {
     private readonly _store;
-    /** null unless `retention` was configured. */
+    /** null unless `retentionMs` was configured. */
     private readonly sweeper;
     constructor(_store: TaskStore, opts?: ClientOptions);
     static sqlite(path: string, opts?: {
@@ -44,22 +65,16 @@ export declare class CairnQ {
     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
-     * `maxQueueWaitMs` — see QueueDepthGate for why that bound is approximate
-     * across several producers. */
+     * `maxQueueWaitMs` — a soft limit across several producers. */
     submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;
     submit<P, R>(task: TaskDef<P, R>, payload?: P, opts?: SubmitOptions): Promise<Task>;
     /** How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
      * The non-blocking read behind `maxQueueDepth`, for a producer that would
-     * rather shed load or pick another queue than wait. Cheaper than `stats()`:
-     * bounded at `maxDepth` index entries instead of aggregating the table. */
+     * rather shed load or pick another queue than wait. Bounded at `maxDepth`
+     * index entries, so it stays cheap to ask on every enqueue. */
     queueDepth(queue: string, maxDepth: number): Promise<number>;
     get(taskId: string): Promise<Task | null>;
     getByKey(key: string): Promise<Task | null>;
-    /** The status-only probe wait polls on: id + status, no payload. Public for
-     * the same reason it exists — a dashboard or poller that only asks "is it
-     * finished yet" should not drag the payload back per ask. */
-    getStatus(taskId: string): Promise<TaskRef | null>;
-    getStatusByKey(key: string): Promise<TaskRef | null>;
     list(input?: ListInput): Promise<Task[]>;
     cancel(taskId: string): Promise<Task | null>;
     cancelByKey(key: string): Promise<Task | null>;
@@ -71,32 +86,13 @@ export declare class CairnQ {
     }): Promise<Task | null>;
     /** Delete terminal tasks that finished more than `olderThanMs` ago and return
      * their ids. Nothing else in CairnQ removes rows, so a long-lived database
-     * needs this on a schedule. Each call is bounded by `limit` to keep the write
-     * short; loop until it returns fewer than `limit`.
+     * needs this on a schedule — `retentionMs` is this call on a timer. Each call
+     * is bounded by `limit` to keep the write short; loop until it returns fewer
+     * than `limit`.
      *
      * `queue` / `status` / `name` narrow the sweep — one installation carrying two
      * workloads needs a retention per workload, not one for the whole database. */
     purge(input?: PurgeInput): Promise<string[]>;
-    /** Task counts per queue, keyed by status and zero-filled across all statuses
-     * — `(await stats()).default.queued` is the backlog of a queue. `queue` narrows
-     * the aggregate to one queue, which is also what keeps a caller from paying for
-     * the other workloads sharing the installation; a named queue is always
-     * present, zero-filled if it has no rows.
-     *
-     * This counts rows, so it costs what it counts — use it for a dashboard, and
-     * poll `queueDepth()` instead, which is bounded. */
-    stats(queue?: string): Promise<Record<string, Record<TaskStatus, number>>>;
-    /**
-     * Call `onSignal` when the tasks on `queues` may have changed. Returns an
-     * unsubscribe.
-     *
-     * Notify-accelerated polling, not an event log: a signal means "re-read now",
-     * and `stats()` / `list()` / `get()` are where the truth is. On Postgres an
-     * idle watch costs nothing and signals land in milliseconds; everywhere else
-     * the timer alone still delivers, so the same consumer code is correct either
-     * way. See TaskStore.watch for the full contract.
-     */
-    watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void;
     /** 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. */
@@ -111,7 +107,7 @@ export declare class CairnQ {
      * TaskFailed / TaskCanceled / TaskTimeout otherwise. Pass a TaskDef and the
      * resolved value is typed as its Result.
      *
-     * `waitTimeoutMs` bounds the wait, not the task: on timeout the task runs on,
+     * `timeoutMs` 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>;

package/dist/client.js

@@ -8,21 +8,24 @@ import { DEFAULT_WAIT_TIMEOUT_MS, 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. */
+    /** null unless `retentionMs` was configured. */
     sweeper;
     constructor(_store, opts = {}) {
         this._store = _store;
         // Installed on the store, not held here: every submit path goes through the
         // store, including TaskContext.submit, which this handle never sees.
         if (opts.maxQueueDepth != null) {
-            _store.useBackpressure(opts);
+            _store.useBackpressure({
+                maxQueueDepth: opts.maxQueueDepth,
+                maxQueueWaitMs: opts.maxQueueWaitMs,
+            });
         }
         // 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 = opts.retentionMs != null ? new RetentionSweeper(_store, opts.retentionMs) : null;
         this.sweeper?.start();
     }
     static sqlite(path, opts = {}) {
@@ -50,12 +53,25 @@ export class CairnQ {
         await this._store.close();
     }
     submit(task, payload, opts = {}) {
-        return this._store.submit({ name: taskName(task), payload, ...opts });
+        // Fields picked explicitly rather than spread, so the type is the truth:
+        // store-level SubmitInput accepts more (parentId and friends, which
+        // TaskContext.submit wires), and a spread would silently keep honoring them.
+        return this._store.submit({
+            name: taskName(task),
+            payload,
+            queue: opts.queue,
+            key: opts.key,
+            conflict: opts.conflict,
+            maxAttempts: opts.maxAttempts,
+            priority: opts.priority,
+            metadata: opts.metadata,
+            delayMs: opts.delayMs,
+        });
     }
     /** How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
      * The non-blocking read behind `maxQueueDepth`, for a producer that would
-     * rather shed load or pick another queue than wait. Cheaper than `stats()`:
-     * bounded at `maxDepth` index entries instead of aggregating the table. */
+     * rather shed load or pick another queue than wait. Bounded at `maxDepth`
+     * index entries, so it stays cheap to ask on every enqueue. */
     queueDepth(queue, maxDepth) {
         return this._store.queueDepth(queue, maxDepth);
     }
@@ -65,15 +81,6 @@ export class CairnQ {
     getByKey(key) {
         return this._store.getByKey(key);
     }
-    /** The status-only probe wait polls on: id + status, no payload. Public for
-     * the same reason it exists — a dashboard or poller that only asks "is it
-     * finished yet" should not drag the payload back per ask. */
-    getStatus(taskId) {
-        return this._store.getStatus(taskId);
-    }
-    getStatusByKey(key) {
-        return this._store.getStatusByKey(key);
-    }
     list(input) {
         return this._store.list(input);
     }
@@ -91,38 +98,15 @@ export class CairnQ {
     }
     /** Delete terminal tasks that finished more than `olderThanMs` ago and return
      * their ids. Nothing else in CairnQ removes rows, so a long-lived database
-     * needs this on a schedule. Each call is bounded by `limit` to keep the write
-     * short; loop until it returns fewer than `limit`.
+     * needs this on a schedule — `retentionMs` is this call on a timer. Each call
+     * is bounded by `limit` to keep the write short; loop until it returns fewer
+     * than `limit`.
      *
      * `queue` / `status` / `name` narrow the sweep — one installation carrying two
      * workloads needs a retention per workload, not one for the whole database. */
     purge(input) {
         return this._store.purge(input);
     }
-    /** Task counts per queue, keyed by status and zero-filled across all statuses
-     * — `(await stats()).default.queued` is the backlog of a queue. `queue` narrows
-     * the aggregate to one queue, which is also what keeps a caller from paying for
-     * the other workloads sharing the installation; a named queue is always
-     * present, zero-filled if it has no rows.
-     *
-     * This counts rows, so it costs what it counts — use it for a dashboard, and
-     * poll `queueDepth()` instead, which is bounded. */
-    stats(queue) {
-        return this._store.stats(queue);
-    }
-    /**
-     * Call `onSignal` when the tasks on `queues` may have changed. Returns an
-     * unsubscribe.
-     *
-     * Notify-accelerated polling, not an event log: a signal means "re-read now",
-     * and `stats()` / `list()` / `get()` are where the truth is. On Postgres an
-     * idle watch costs nothing and signals land in milliseconds; everywhere else
-     * the timer alone still delivers, so the same consumer code is correct either
-     * way. See TaskStore.watch for the full contract.
-     */
-    watch(opts, onSignal) {
-        return this._store.watch(opts, onSignal);
-    }
     /** 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. */
@@ -146,9 +130,9 @@ export class CairnQ {
         });
     }
     async call(task, payload, opts = {}) {
-        const { waitTimeoutMs, pollMs, maxPollMs, ...submit } = opts;
+        const { timeoutMs, pollMs, maxPollMs, ...submit } = opts;
         const created = await this.submit(taskName(task), payload, submit);
-        const final = await this.wait(created.id, { timeoutMs: waitTimeoutMs, pollMs, maxPollMs });
+        const final = await this.wait(created.id, { timeoutMs, pollMs, maxPollMs });
         if (isSucceeded(final))
             return final.result;
         if (isFailed(final))

package/dist/context.d.ts

@@ -65,6 +65,19 @@ export declare class TaskContext {
      * every payload back on every beat.
      */
     observeCancel(cancelRequested: boolean): void;
+    /**
+     * The half of the gate that asks only "is this attempt still mine?".
+     *
+     * 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.
+     *
+     * `owned` layers the settled check on top for writes to this task; `submit`
+     * takes this half alone, because a handler may legitimately settle a task and
+     * then fan out from it.
+     */
+    private requireLease;
     private owned;
     progress(value: number | null, message?: string | null): Promise<Task>;
     heartbeat(): Promise<Task>;
@@ -110,7 +123,16 @@ export declare class TaskContext {
     fail(error?: FailReason, opts?: {
         retryable?: boolean;
     }): Promise<Task | null>;
-    /** Submit a child task; parent/root/correlation are wired automatically. */
+    /**
+     * Submit a child task; parent/root/correlation are wired automatically.
+     *
+     * Refused once the lease is gone. Not the full `owned` gate — a handler may
+     * legitimately settle a task and then fan out from it, so `settled` is no bar
+     * — but a context whose lease was lost is an attempt that has been abandoned:
+     * it is being retried elsewhere, and every child it creates now will be
+     * created again by that retry. Creating work is the one side effect cairnq can
+     * actually stop a zombie handler from repeating.
+     */
     submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;
     submit<P, R>(task: TaskDef<P, R>, payload?: P, opts?: SubmitOptions): Promise<Task>;
     wait(taskId: string, opts?: {

package/dist/context.js

@@ -112,17 +112,27 @@ export class TaskContext {
         if (cancelRequested)
             this.cancelSeen = true;
     }
+    /**
+     * The half of the gate that asks only "is this attempt still mine?".
+     *
+     * 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.
+     *
+     * `owned` layers the settled check on top for writes to this task; `submit`
+     * takes this half alone, because a handler may legitimately settle a task and
+     * then fan out from it.
+     */
+    requireLease() {
+        if (this.leaseLost)
+            throw new LostLease(this.task.id);
+    }
     async owned(write) {
         // 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);
+        this.requireLease();
         // 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.
@@ -242,6 +252,7 @@ export class TaskContext {
         return task;
     }
     async submit(task, payload, opts = {}) {
+        this.requireLease();
         return this.store.submit({
             name: taskName(task),
             payload,

package/dist/errors.d.ts

@@ -70,29 +70,6 @@ export declare class TaskCanceled extends CairnQError {
     taskId: string;
     constructor(taskId: string);
 }
-/**
- * A heartbeat beat came back later than its own interval allowed.
- *
- * The heartbeat shares the event loop with the handlers whose leases it renews,
- * so a handler that blocks the loop stops the renewal with it: the lease expires,
- * the task is recovered and redelivered, and a second worker starts computing
- * what the first is still computing — one task, billed twice, with no error
- * anywhere. Nothing inside the blocked handler can observe that, which is why it
- * is reported through `onError` alongside the other things the run loop survived.
- *
- * The usual cause is synchronous work in a handler: a tight loop, a large
- * JSON.parse, a `*Sync` filesystem or crypto call. Node has one loop and no way
- * to preempt it — move the work to a worker thread, a child process, or an async
- * API that yields. The other cause is a worker simply oversubscribed for its
- * `leaseMs` — nothing is blocking, there is just more work than turns — which the
- * same report covers, because the lease is at equal risk either way.
- */
-export declare class EventLoopBlocked extends CairnQError {
-    readonly lateMs: number;
-    readonly intervalMs: number;
-    readonly leaseMs: number;
-    constructor(lateMs: number, intervalMs: number, leaseMs: number);
-}
 /** A worker write affected 0 rows: the lease expired and was reclaimed. */
 export declare class LostLease extends CairnQError {
     taskId: string;
@@ -129,10 +106,27 @@ export declare class UnsupportedBackend extends CairnQError {
 export declare class SchemaMismatch extends CairnQError {
     constructor(message: string);
 }
+/**
+ * The store was closing when this operation asked for it.
+ *
+ * `close()` waits for the work already accepted — a group commit still holding
+ * writes, a transaction with a BEGIN IMMEDIATE open — and turns away everything
+ * that arrives after, so that wait cannot be extended indefinitely by a producer
+ * that keeps submitting. An operation that lands in that window gets this rather
+ * than a driver error about a connection that vanished underneath it.
+ *
+ * It does not mean the store is finished for good: connecting is lazy, so a
+ * store used again after `close()` has returned simply reopens. The Python SDK
+ * raises the same named error.
+ */
+export declare class StoreClosed extends CairnQError {
+    constructor(message?: string);
+}
 /** A value could not be encoded for a protocol JSON column (non-finite number,
- * BigInt, circular structure, …). Raised at the boundary — submit rejects with
- * it, and a worker records a handler result that triggers it as a permanent
- * `unserializable_result` failure. The Python SDK raises the same named error. */
+ * BigInt, circular structure, an opaque built-in like Map or Set, …). Raised at
+ * the boundary — submit rejects with it, and a worker records a handler result
+ * that triggers it as a permanent `unserializable_result` failure. The Python
+ * SDK raises the same named error. */
 export declare class SerializationError extends CairnQError {
     constructor(message: string);
 }