cairnq 0.13.0 → 0.14.0

package/dist/store/postgres.d.ts

@@ -1,4 +1,4 @@
-import { type Fetch, type Params, TaskStore, type WatchSignal } from "./base.js";
+import { type Fetch, type Params, TaskStore } from "./base.js";
 import { type PgExecutor, type PgSession } from "./pg-executor.js";
 /**
  * The rewritten SQL and the order its `$n` slots must be filled in.
@@ -98,9 +98,6 @@ export declare class PostgresStore extends TaskStore {
     private readonly wakeableQueues;
     /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
     private readonly waiters;
-    /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
-     * consumes the notification, a subscriber is standing and only observes. */
-    private readonly subscribers;
     /**
      * `source` is either a libpq connection string — this store then owns a `pg`
      * pool and requires the optional `pg` package — or a PgExecutor the caller
@@ -119,8 +116,8 @@ export declare class PostgresStore extends TaskStore {
      * Every path here connects lazily, so a store used again after close simply
      * reconnects — and without this it would reconnect permanently degraded to
      * polling, having decided "no push channel" about a connection that no longer
-     * exists. Called from the constructor for the initial state and from doConnect
-     * for every later one, so the three fields cannot be re-armed by halves. Only
+     * exists. The fields' initializers give the first state and doConnect calls
+     * this for every later one, so the three cannot be re-armed by halves. Only
      * ever safe under doConnect's generation check.
      */
     private resetListenerState;
@@ -149,12 +146,25 @@ export declare class PostgresStore extends TaskStore {
      */
     private checkSchema;
     private applyMigrations;
+    /**
+     * Whether this driver hands json/jsonb back as text, measured rather than
+     * assumed.
+     *
+     * `pg` decodes jsonb by default; asyncpg hands back the text; an application's
+     * own driver — or a `pg` with a type parser the application installed — may do
+     * either, and an injected executor is exactly that case. The two are
+     * indistinguishable from a value once it arrives (see rowToTask), so the
+     * answer has to come from the driver itself.
+     *
+     * A JSON string is the probe because it is the only value whose two forms
+     * differ: as text it arrives with its quotes (`"cairnq"`, 8 characters), as a
+     * decoded value without them (`cairnq`, 6). One statement, once per connect.
+     */
+    private detectJsonWireForm;
     private readProtocolVersion;
     protocolVersion(): Promise<number>;
     protected registerWakeable(queues: string[]): void;
     claimWake(queues: string[], timeoutMs: number): Promise<void>;
-    protected subscribePush(onSignal: (signal: WatchSignal) => void): () => void;
-    protected warmPush(): void;
     taskDoneWake(taskId: string, timeoutMs: number): Promise<void>;
     /** A promise resolving on notification-or-timeout, deregistering either way.
      * The timer is unref'd: while a listener exists its socket keeps the process
@@ -167,10 +177,6 @@ export declare class PostgresStore extends TaskStore {
     private listenerReady;
     private startListener;
     private onNotification;
-    /** Hand a notification to every watch() subscriber. A throwing subscriber is
-     * its own problem: it must not cost the others their signal, nor take down the
-     * listener connection that delivered it. */
-    private publish;
     private dropListener;
     protected fetch(name: string, params: Params): Promise<any[]>;
     protected tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;

package/dist/store/postgres.js

@@ -125,9 +125,6 @@ export class PostgresStore extends TaskStore {
     wakeableQueues = new Set();
     /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
     waiters = new Map();
-    /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
-     * consumes the notification, a subscriber is standing and only observes. */
-    subscribers = new Set();
     /**
      * `source` is either a libpq connection string — this store then owns a `pg`
      * pool and requires the optional `pg` package — or a PgExecutor the caller
@@ -175,8 +172,8 @@ export class PostgresStore extends TaskStore {
      * Every path here connects lazily, so a store used again after close simply
      * reconnects — and without this it would reconnect permanently degraded to
      * polling, having decided "no push channel" about a connection that no longer
-     * exists. Called from the constructor for the initial state and from doConnect
-     * for every later one, so the three fields cannot be re-armed by halves. Only
+     * exists. The fields' initializers give the first state and doConnect calls
+     * this for every later one, so the three cannot be re-armed by halves. Only
      * ever safe under doConnect's generation check.
      */
     resetListenerState() {
@@ -194,6 +191,9 @@ export class PostgresStore extends TaskStore {
             await this.checkSchema(executor);
             await this.applyMigrations(executor);
             checkProtocolVersion(await this.readProtocolVersion(executor));
+            // Before publishing the executor, so no row is ever mapped against an
+            // unmeasured wire form.
+            this.jsonIsText = await this.detectJsonWireForm(executor);
         }
         catch (e) {
             // Never leak an executor we created; never close one we were handed.
@@ -286,6 +286,24 @@ export class PostgresStore extends TaskStore {
             });
         }
     }
+    /**
+     * Whether this driver hands json/jsonb back as text, measured rather than
+     * assumed.
+     *
+     * `pg` decodes jsonb by default; asyncpg hands back the text; an application's
+     * own driver — or a `pg` with a type parser the application installed — may do
+     * either, and an injected executor is exactly that case. The two are
+     * indistinguishable from a value once it arrives (see rowToTask), so the
+     * answer has to come from the driver itself.
+     *
+     * A JSON string is the probe because it is the only value whose two forms
+     * differ: as text it arrives with its quotes (`"cairnq"`, 8 characters), as a
+     * decoded value without them (`cairnq`, 6). One statement, once per connect.
+     */
+    async detectJsonWireForm(s) {
+        const rows = await s.query(`select '"cairnq"'::jsonb as probe`, []);
+        return rows[0]?.probe === '"cairnq"';
+    }
     // Takes an explicit session: during doConnect the executor is not published
     // yet, so this cannot go through fetch(). The statement binds nothing.
     async readProtocolVersion(s) {
@@ -322,15 +340,6 @@ export class PostgresStore extends TaskStore {
             await this.wakeOn("queued", remaining);
         }
     }
-    subscribePush(onSignal) {
-        this.subscribers.add(onSignal);
-        this.listenerReady(); // an API-side watcher is often the only thing asking
-        return () => void this.subscribers.delete(onSignal);
-    }
-    warmPush() {
-        if (this.subscribers.size > 0)
-            this.listenerReady();
-    }
     taskDoneWake(taskId, timeoutMs) {
         if (!this.listenerReady())
             return super.taskDoneWake(taskId, timeoutMs);
@@ -421,11 +430,9 @@ export class PostgresStore extends TaskStore {
             if (this.wakeableQueues.has(payload))
                 this.pendingQueues.add(payload);
             key = "queued";
-            this.publish({ reason: "queued", queue: payload });
         }
         else if (channel === DONE_CHANNEL && payload) {
             key = `done:${payload}`;
-            this.publish({ reason: "done", taskId: payload });
         }
         else {
             return;
@@ -436,19 +443,6 @@ export class PostgresStore extends TaskStore {
             for (const w of set)
                 w();
     }
-    /** Hand a notification to every watch() subscriber. A throwing subscriber is
-     * its own problem: it must not cost the others their signal, nor take down the
-     * listener connection that delivered it. */
-    publish(signal) {
-        for (const s of [...this.subscribers]) {
-            try {
-                s(signal);
-            }
-            catch {
-                // Deliberately swallowed — see above.
-            }
-        }
-    }
     dropListener() {
         const stop = this.listener;
         this.listener = null;

package/dist/store/sqlite.d.ts

@@ -46,13 +46,48 @@ export declare class SQLiteStore extends TaskStore {
     private readonly writes;
     /** Writes waiting to be group-committed — see flush(). */
     private pending;
-    /** Whether a flusher is already queued to drain `pending`. */
-    private flushing;
+    /**
+     * The flusher draining `pending`, or null when none is running — both the
+     * "is one already going" guard and the handle `close()` waits on, which are
+     * the same question. The Python twin keeps two fields only because its
+     * _do_close hands the flusher off before awaiting it.
+     */
+    private flusher;
+    /** Set for the duration of close(), so the drain it waits on is finite. */
+    private closing;
+    /** The close in progress, so a second caller waits for it rather than
+     * returning while the connection is still open. */
+    private closed;
+    /** Whether a connection was ever opened — see ensure() on in-memory reopen. */
+    private everOpened;
     constructor(path: string, opts?: {
         busyTimeoutMs?: number;
     });
     connect(): Promise<void>;
+    /**
+     * Close the connection, once everything already accepted has landed.
+     *
+     * Two things can be in flight, and cutting off either loses a write that a
+     * caller is still awaiting: a group commit holding a batch (`flush`), and a
+     * transaction with a BEGIN IMMEDIATE open on this same connection (a keyed
+     * submit, a claim). The first is awaited directly. The second is waited out by
+     * queuing an empty operation behind it on the file lock — the lock is what
+     * serializes them in the first place, so anything already queued there runs
+     * before this does.
+     *
+     * Neither wait can be stretched indefinitely: `closing` turns away everything
+     * that arrives from now on, so the queue this drains is the one that existed
+     * when close() was called. Without that barrier a write landing between the
+     * flusher finishing and the connection closing would start a fresh flusher
+     * against a `db` already null — the TypeError that used to surface here.
+     *
+     * Closing does not retire the store. Connecting is lazy, so a store used again
+     * afterwards reopens; `closing` is cleared for exactly that reason. The one
+     * case where reopening cannot mean what the caller wants is an in-memory
+     * database, whose contents live in the connection — see ensure().
+     */
     close(): Promise<void>;
+    private doClose;
     private ensure;
     private applyMigrations;
     private readProtocolVersion;
@@ -136,6 +171,8 @@ export declare class SQLiteStore extends TaskStore {
      * and one that arrives after sees the flag down and starts a new flusher.
      */
     private scheduleFlush;
+    /** The flusher's body; see scheduleFlush for why it is a separate method. */
+    private drain;
     protected fetch(name: string, params: Params): Promise<any[]>;
     protected tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
 }

package/dist/store/sqlite.js

@@ -3,6 +3,7 @@ import { dirname, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { nowMs } from "../ids.js";
 import { loadMigrations, loadStatements } from "../sql.js";
+import { StoreClosed } from "../errors.js";
 import { checkProtocolVersion, COMMENT, specialize, statementParams, TaskStore, } from "./base.js";
 // `better-sqlite3` is an optional dependency, matching `pg` on the Postgres side:
 // a Postgres-only deployment should not have to build a native module it never
@@ -213,8 +214,20 @@ export class SQLiteStore extends TaskStore {
     writes;
     /** Writes waiting to be group-committed — see flush(). */
     pending = [];
-    /** Whether a flusher is already queued to drain `pending`. */
-    flushing = false;
+    /**
+     * The flusher draining `pending`, or null when none is running — both the
+     * "is one already going" guard and the handle `close()` waits on, which are
+     * the same question. The Python twin keeps two fields only because its
+     * _do_close hands the flusher off before awaiting it.
+     */
+    flusher = null;
+    /** Set for the duration of close(), so the drain it waits on is finite. */
+    closing = false;
+    /** The close in progress, so a second caller waits for it rather than
+     * returning while the connection is still open. */
+    closed = null;
+    /** Whether a connection was ever opened — see ensure() on in-memory reopen. */
+    everOpened = false;
     constructor(path, opts = {}) {
         super();
         this.path = path;
@@ -233,17 +246,81 @@ export class SQLiteStore extends TaskStore {
     async connect() {
         this.ensure();
     }
+    /**
+     * Close the connection, once everything already accepted has landed.
+     *
+     * Two things can be in flight, and cutting off either loses a write that a
+     * caller is still awaiting: a group commit holding a batch (`flush`), and a
+     * transaction with a BEGIN IMMEDIATE open on this same connection (a keyed
+     * submit, a claim). The first is awaited directly. The second is waited out by
+     * queuing an empty operation behind it on the file lock — the lock is what
+     * serializes them in the first place, so anything already queued there runs
+     * before this does.
+     *
+     * Neither wait can be stretched indefinitely: `closing` turns away everything
+     * that arrives from now on, so the queue this drains is the one that existed
+     * when close() was called. Without that barrier a write landing between the
+     * flusher finishing and the connection closing would start a fresh flusher
+     * against a `db` already null — the TypeError that used to surface here.
+     *
+     * Closing does not retire the store. Connecting is lazy, so a store used again
+     * afterwards reopens; `closing` is cleared for exactly that reason. The one
+     * case where reopening cannot mean what the caller wants is an in-memory
+     * database, whose contents live in the connection — see ensure().
+     */
     async close() {
-        if (this.db) {
-            this.db.close();
-            this.db = null;
-            this.stmts.clear();
+        return (this.closed ??= this.doClose().finally(() => {
+            this.closed = null;
+        }));
+    }
+    async doClose() {
+        this.closing = true;
+        try {
+            // Errors belong to the writes that carry them, and the flusher has already
+            // delivered each one to its own waiter; close() only needs it finished.
+            await this.flusher?.catch(() => { });
+            // Runs behind every operation currently on the lock, including a
+            // transaction mid-await. Reads are queued there too, so this also waits
+            // out a statement that would otherwise land on a closed connection.
+            await this.enqueue(() => { }).catch(() => { });
+            if (this.db) {
+                this.db.close();
+                this.db = null;
+                this.stmts.clear();
+            }
+            // An in-memory database's lock guards nothing once its connection is gone:
+            // the key is minted per store (see lockKey), so no other store can be
+            // queued behind it. Left in place, a process that opens many short-lived
+            // in-memory stores — a test suite, a per-request scratch queue — grows
+            // fileLocks by one settled promise per store, forever. A file's key is NOT
+            // dropped: other stores may still be serializing on it.
+            if (this.lockKey.startsWith("memory#"))
+                fileLocks.delete(this.lockKey);
+        }
+        finally {
+            this.closing = false;
         }
     }
     ensure() {
+        // A store mid-close is about to drop the connection this would hand back.
+        // Refusing keeps close()'s drain finite, and gives the caller a typed error
+        // instead of whatever the driver says about a connection pulled out from
+        // under it.
+        if (this.closing)
+            throw new StoreClosed();
         if (this.db)
             return this.db;
         const memory = isMemory(this.path);
+        // Reopening is how a store used again after close() carries on, and for a
+        // file that is exactly right — the tasks are in the file. An in-memory
+        // database lives in the connection, so the same path would hand back an
+        // EMPTY store: every task the caller submitted gone, no error, and a `get`
+        // that answers null as if the id had never existed. Say so instead.
+        if (memory && this.everOpened) {
+            throw new StoreClosed(`in-memory database ${JSON.stringify(this.path)} was closed — its contents ` +
+                `went with the connection, so reopening would silently start from empty. ` +
+                `Use a file path if the store needs to outlive a close.`);
+        }
         if (!memory)
             mkdirSync(dirname(this.path), { recursive: true });
         const db = new (loadSqlite())(this.path);
@@ -277,6 +354,7 @@ export class SQLiteStore extends TaskStore {
             this.stmts.set(sql, db.prepare(sql));
         }
         this.db = db;
+        this.everOpened = true;
         checkProtocolVersion(this.readProtocolVersion());
         return db;
     }
@@ -547,33 +625,34 @@ export class SQLiteStore extends TaskStore {
      * and one that arrives after sees the flag down and starts a new flusher.
      */
     scheduleFlush(db) {
-        if (this.flushing)
+        if (this.flusher)
             return;
-        this.flushing = true;
-        void (async () => {
+        // Assigned before the `.finally` can possibly run — a finally callback is a
+        // microtask at the earliest — so the field is never cleared before it is
+        // set, however little `drain` does before returning.
+        this.flusher = this.drain(db).finally(() => {
+            this.flusher = null;
+        });
+    }
+    /** The flusher's body; see scheduleFlush for why it is a separate method. */
+    async drain(db) {
+        while (this.pending.length) {
             try {
-                while (this.pending.length) {
-                    try {
-                        await this.withLock(() => this.flush(db));
-                    }
-                    catch (err) {
-                        // flush only throws on a lost write lock, and only after putting its
-                        // batch back — so reaching here means withLock spent the whole budget
-                        // and those writes are still queued with nobody else coming for them.
-                        // Anything that arrived behind them is failed with the same error
-                        // rather than left hanging: this store cannot write at all right now,
-                        // which is what a lone write would have been told too.
-                        const stranded = this.pending;
-                        this.pending = [];
-                        for (const w of stranded)
-                            w.reject(err);
-                    }
-                }
+                await this.withLock(() => this.flush(db));
             }
-            finally {
-                this.flushing = false;
+            catch (err) {
+                // flush only throws on a lost write lock, and only after putting its
+                // batch back — so reaching here means withLock spent the whole budget
+                // and those writes are still queued with nobody else coming for them.
+                // Anything that arrived behind them is failed with the same error
+                // rather than left hanging: this store cannot write at all right now,
+                // which is what a lone write would have been told too.
+                const stranded = this.pending;
+                this.pending = [];
+                for (const w of stranded)
+                    w.reject(err);
             }
-        })();
+        }
     }
     async fetch(name, params) {
         const db = this.ensure();

package/dist/worker.d.ts

@@ -1,4 +1,3 @@
-import type { BackpressureOptions } from "./backpressure.js";
 import { TaskContext } from "./context.js";
 import type { PgExecutor } from "./store/pg-executor.js";
 import type { TaskStore } from "./store/base.js";
@@ -24,18 +23,15 @@ export type ErrorPhase = "claim" | "execute";
  * children through TaskContext.submit is a producer, and in a worker process
  * there is usually no CairnQ handle to have configured the store.
  */
-export interface WorkerOptions extends Partial<BackpressureOptions> {
+export interface WorkerOptions {
     /**
      * 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.
+     * for how many tasks that comes to.
      */
     concurrency?: number;
     leaseMs?: number;
-    heartbeatIntervalMs?: number;
     pollIntervalMs?: number;
-    claimBatch?: number;
     /** Base delay before re-running a failed attempt; doubles per attempt. 0 disables. */
     retryBackoffMs?: number;
     /** Ceiling for the doubling. */
@@ -49,39 +45,21 @@ export interface WorkerOptions extends Partial<BackpressureOptions> {
      * a retryable `handler_timeout` failure. Unset disables the ceiling.
      */
     maxRunMs?: number;
-    /**
-     * Resident payload bytes allowed across running handlers, independent of
-     * their count.
-     *
-     * `concurrency` bounds tasks, not memory, so a worker sized for small payloads
-     * holds concurrency * largest-payload bytes the moment a batch of big ones
-     * arrives — for payloads that carry media inline, that is the difference
-     * 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: 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.
+     * The limit belongs to the scarce thing rather than to any one name — a GPU,
+     * an index that tolerates a single writer — so it is declared here, once, and
+     * at capacity 1 it is mutual exclusion across the names that join it. A name
+     * that only needs to cap itself declares a resource of its own.
      */
     resources?: Record<string, number>;
+    /** Queued tasks a queue may hold before `submit` blocks — a number for every
+     * queue, or a per-queue record that leaves unnamed queues unbounded. */
+    maxQueueDepth?: number | Record<string, number>;
+    /** How long a blocked submit waits before raising QueueFull. Default 600_000. */
+    maxQueueWaitMs?: 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
@@ -99,22 +77,7 @@ export declare class Worker {
     private readonly opts;
     private readonly handlers;
     private readonly ownId;
-    /** 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;
+    private readonly planner;
     /**
      * Retry backoff, resolved once. Both settlement paths read these — the
      * worker's own `safeFail` and the TaskContext it hands a handler — so
@@ -151,22 +114,16 @@ export declare class Worker {
      * 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;
+        batch?: number;
         resource?: string;
     }, handler: BatchHandler): this;
-    /** Per-name concurrency or a shared resource, without batching: the handler
-     * still takes `(ctx, payload)`. */
+    /** 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;
@@ -192,37 +149,6 @@ export declare class Worker {
      */
     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;
@@ -230,7 +156,23 @@ export declare class Worker {
     serve(opts?: {
         concurrency?: number;
     }): Promise<void>;
-    /** Run the worker in the same process for the duration of fn (deployment mode A). */
+    /**
+     * Run the worker in the same process for the duration of fn (deployment mode A).
+     *
+     * `run()` can fail before `fn` has even started — a database that will not
+     * open, a migration that will not apply, a protocol version this SDK does not
+     * speak — so its rejection is captured from the first tick rather than only at
+     * the `await` in the teardown. Left uncaught until then it is an unhandled
+     * rejection, which Node terminates the process for by default: the caller
+     * never saw the error, and `fn` never finished. (The same mistake `runCall`
+     * documents having made.)
+     *
+     * If `fn` returned, the worker's failure is what the caller hears: a value
+     * produced with no worker running is not a success worth reporting quietly. If
+     * `fn` threw, its own error wins — it is the caller's code, and replacing it
+     * would hide what they were actually doing — with the worker's failure
+     * attached as `cause` so the root of it stays reachable.
+     */
     background<T>(fn: () => Promise<T>, opts?: {
         concurrency?: number;
     }): Promise<T>;
@@ -307,10 +249,13 @@ export declare class Worker {
      * 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-lost first (ctx.signal aborts; a handler that keeps running can never
+     * write to its task again, nor settle anything behind the worker's back — see
+     * TaskContext.owned — and cannot create child tasks either, which would
+     * otherwise be created a second time by the retry), then the still-pending
+     * promise is left to settle on its own, its outcome discarded. What a zombie
+     * does OUTSIDE cairnq is its own business: `ctx.signal` is how a handler is
+     * told to stop, and only the handler can act on it. The caller records the handler_timeout failure;
      * lease recovery is NOT involved, so redelivery is immediate.
      */
     private attempt;