cairnq 0.1.0 → 0.2.0

package/dist/store/sqlite.js

@@ -1,38 +1,105 @@
 import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, resolve } from "node:path";
 import Database from "better-sqlite3";
-import { newId, nowMs } from "../ids.js";
-import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch } from "../errors.js";
-import { rowToTask } from "../models.js";
+import { nowMs } from "../ids.js";
 import { loadMigrations, loadStatements } from "../sql.js";
-const SUPPORTED_PROTOCOL_MAJOR = 1;
-const LEASE_EXPIRED_ERROR = errorEnvelope({
-    type: "LeaseExpired",
-    code: "lease_expired",
-    message: "task lease expired and max attempts reached",
-    retryable: false,
-});
-// Serialized once: it's an immutable constant bound on every claim that finds work.
-const LEASE_EXPIRED_ERROR_JSON = JSON.stringify(LEASE_EXPIRED_ERROR);
+import { checkProtocolVersion, statementParams, TaskStore, } from "./base.js";
+const WAL_RETRY_DELAY_MS = 50;
+const WAL_RETRY_BUDGET_MS = 5_000;
+/** Sleep without yielding — the whole open path is synchronous already. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Whether this path names an in-memory database rather than a file. */
+function isMemory(path) {
+    return path === ":memory:" || path.includes("mode=memory");
+}
+/**
+ * Serializes every SQLiteStore on one database file, process-wide.
+ *
+ * better-sqlite3 is synchronous, and a transaction holds SQLite's write lock
+ * across `await`s (the callback seam is shared with Postgres, so it is async). A
+ * second connection in this process then blocks the only thread waiting for that
+ * lock, and the holder can never reach COMMIT — reaching it needs the thread the
+ * waiter is sitting on. busy_timeout cannot break that inversion, being one
+ * thread; the wait just burns the timeout and throws "database is locked". So the
+ * two must not overlap at all.
+ *
+ * Keyed by database, not by store: what the lock protects is the file. Across
+ * processes there is no inversion (the holder keeps its own thread) and
+ * busy_timeout still applies. An in-memory database is private to one connection
+ * and gets a key of its own.
+ */
+const fileLocks = new Map();
+let memoryDbSeq = 0;
+/**
+ * Put the database in WAL mode, waiting out a concurrent cold start.
+ *
+ * journal_mode is a persistent property of the file, so only the first connection
+ * to a new database actually switches it — and that switch needs an exclusive
+ * lock. `busy_timeout` does not cover it: SQLite returns SQLITE_BUSY for a
+ * journal_mode change rather than invoking the busy handler, so several processes
+ * opening the same new database at once would otherwise get an instant "database
+ * is locked". Retry briefly instead; the window is only as long as one other
+ * opener's switch.
+ *
+ * Callers must skip in-memory databases: those report journal_mode = "memory" and
+ * can never be WAL, so waiting for one is waiting for something that will not
+ * happen.
+ */
+function enableWal(db) {
+    const deadline = Date.now() + WAL_RETRY_BUDGET_MS;
+    for (;;) {
+        try {
+            const rows = db.pragma("journal_mode = WAL");
+            if (rows[0]?.journal_mode?.toLowerCase() === "wal")
+                return;
+        }
+        catch (err) {
+            const message = String(err.message ?? err);
+            if (!/locked|busy/i.test(message))
+                throw err;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error("could not switch the database to WAL mode: it stayed locked by another connection");
+        }
+        sleepSync(WAL_RETRY_DELAY_MS);
+    }
+}
 /**
- * SQLiteStore — better-sqlite3 backend executing the shared cairnq-protocol SQL.
+ * SQLiteStore — the SQLite dialect of the shared cairnq-protocol SQL.
+ *
+ * Everything protocol-shaped lives in TaskStore; this file is only what SQLite
+ * does differently: better-sqlite3's synchronous driver, BEGIN IMMEDIATE
+ * transactions, a read-only probe in front of the write lock, and time supplied
+ * by the SDK (`:now_ms`) rather than by the database.
  *
- * The driver is synchronous, which suits SQLite's single writer: claim is one
- * short transaction, the handler runs outside any transaction, and
- * progress/heartbeat/succeed/fail are each their own short write. JS being
- * single-threaded means sync DB calls never interleave. Cross-process contention
- * (deployment mode B) is absorbed by busy_timeout.
+ * The driver being synchronous suits SQLite's single writer: claim is one short
+ * transaction, the handler runs outside any transaction, and
+ * progress/heartbeat/succeed/fail are each their own short write. Cross-process
+ * contention is absorbed by busy_timeout.
  */
-export class SQLiteStore {
+export class SQLiteStore extends TaskStore {
     path;
     opts;
     db = null;
     stmts = {};
     statements;
+    /** This store's entry in `fileLocks` — see there for why it is per-database. */
+    lockKey;
     constructor(path, opts = {}) {
+        super();
         this.path = path;
         this.opts = opts;
         this.statements = loadStatements("sqlite");
+        // Only a bare ":memory:" is guaranteed private to its connection, so only
+        // it gets a lock of its own. A "mode=memory" URI stays path-keyed: with
+        // cache=shared it names ONE shared database, and on a build without URI
+        // filenames it is a literal file — in both cases two stores on that string
+        // must share a lock. Over-serializing a private URI-memory database is
+        // harmless; skipping the lock on a shared one is the deadlock this map
+        // exists to prevent.
+        this.lockKey = path === ":memory:" ? `memory#${memoryDbSeq++}` : resolve(path);
     }
     async connect() {
         this.ensure();
@@ -47,251 +114,152 @@ export class SQLiteStore {
     ensure() {
         if (this.db)
             return this.db;
-        if (this.path !== ":memory:")
+        const memory = isMemory(this.path);
+        if (!memory)
             mkdirSync(dirname(this.path), { recursive: true });
         const db = new Database(this.path);
-        db.pragma("journal_mode = WAL");
-        db.pragma("foreign_keys = ON");
+        // busy_timeout first, so every later statement waits out contention instead
+        // of failing instantly.
         db.pragma(`busy_timeout = ${this.opts.busyTimeoutMs ?? 5000}`);
+        // WAL exists so several processes can share one file. An in-memory database
+        // is private to this connection, so there is nothing to share or wait for.
+        if (!memory)
+            enableWal(db);
+        db.pragma("foreign_keys = ON");
         this.applyMigrations(db);
         for (const [name, sql] of Object.entries(this.statements)) {
             this.stmts[name] = db.prepare(sql);
         }
         this.db = db;
-        this.checkVersion();
+        checkProtocolVersion(this.readProtocolVersion());
         return db;
     }
     applyMigrations(db) {
         db.exec("create table if not exists cairnq_migrations " +
             "(name text primary key, applied_at_ms integer not null)");
-        const applied = new Set(db.prepare("select name from cairnq_migrations").all().map((r) => r.name));
-        // `or ignore`: another process may apply the same migration concurrently on a
-        // fresh shared db (mode B cold start). Migrations are idempotent.
-        const insert = db.prepare("insert or ignore into cairnq_migrations (name, applied_at_ms) values (?, ?)");
+        const isApplied = db.prepare("select 1 from cairnq_migrations where name = ?");
+        const insert = db.prepare("insert into cairnq_migrations (name, applied_at_ms) values (?, ?)");
         for (const { name, sql } of loadMigrations("sqlite")) {
-            if (applied.has(name))
-                continue;
+            // Check and apply under one write lock. Two processes cold-starting on a
+            // shared database would otherwise both see a migration as unapplied and
+            // both run it — harmless for the idempotent ones, not for a future ALTER.
+            // `immediate` takes the write lock up front; the loser sees it applied.
             db.transaction(() => {
+                if (isApplied.get(name))
+                    return;
                 db.exec(sql);
                 insert.run(name, nowMs());
-            })();
-        }
-    }
-    checkVersion() {
-        const version = this.readProtocolVersion();
-        if (version !== SUPPORTED_PROTOCOL_MAJOR) {
-            throw new ProtocolVersionMismatch(`storage protocol_version=${version}, SDK supports ${SUPPORTED_PROTOCOL_MAJOR}`);
+            }).immediate();
         }
     }
     readProtocolVersion() {
-        const row = this.db
-            .prepare("select value from cairnq_meta where key = 'protocol_version'")
-            .get();
-        return row ? Number(row.value) : 0;
+        const rows = this.runNow("protocol_version", {});
+        return rows.length ? Number(rows[0].value) : 0;
     }
     async protocolVersion() {
         this.ensure();
-        return this.readProtocolVersion();
+        // Under the store lock: this public read must not slip a statement into
+        // another operation's open transaction on the shared connection.
+        return this.withLock(() => this.readProtocolVersion());
     }
-    all(name, params) {
-        return this.stmts[name].all(params);
-    }
-    run(name, params) {
-        this.stmts[name].run(params);
-    }
-    // An ownership-checked worker write (heartbeat/progress/succeed/complete/fail).
-    // Each statement's WHERE pins worker_id + a live lease, so 0 rows back means the
-    // lease was lost — every such write reports it the same way.
-    ownedWrite(name, taskId, params) {
-        const rows = this.all(name, params);
-        if (!rows.length)
-            throw new LostLease(taskId);
-        return rowToTask(rows[0]);
-    }
-    // ------------------------------------------------------------- client side
-    async submit(input) {
-        this.ensure();
+    // ------------------------------------------------------------ dialect seam
+    /**
+     * Adapt the dialect-neutral parameters to what this statement binds.
+     *
+     * SQLite statements carry no DB clock, so every absolute `*_ms` is derived here
+     * from one `now`, and booleans cross as 0/1. The result is narrowed to the
+     * names the SQL actually uses, which is what makes it safe for a caller to pass
+     * one superset of parameters for both dialects.
+     *
+     * Each derivation writes a name Postgres does not use (`lease_until_ms` from
+     * `lease_ms`, and so on), so a statement binds one or the other, never both —
+     * which is why the derived values can be computed unconditionally and left for
+     * the narrowing step to discard.
+     */
+    bind(sql, params) {
         const now = nowMs();
-        const id = newId("task");
-        const ins = {
-            id,
-            name: input.name,
-            queue: input.queue ?? "default",
-            payload: JSON.stringify(input.payload ?? {}),
-            metadata: JSON.stringify(input.metadata ?? {}),
-            max_attempts: input.maxAttempts ?? 3,
-            priority: input.priority ?? 0,
-            run_at_ms: now + (input.runAtDelayMs ?? 0),
-            parent_id: input.parentId ?? null,
-            root_id: input.rootId ?? id,
-            correlation_id: input.correlationId ?? null,
-            now_ms: now,
-        };
-        const key = input.key ?? null;
-        const conflict = input.conflict ?? "reuse";
-        const txn = this.db.transaction(() => {
-            if (key === null)
-                return this.all("insert_task", ins)[0];
-            const existing = this.all("get_key", { key });
-            if (existing.length) {
-                const exId = existing[0].task_id;
-                if (conflict === "reuse")
-                    return this.all("get", { id: exId })[0];
-                if (conflict === "reject")
-                    throw new AlreadyExists(key);
-                if (conflict === "replace") {
-                    this.all("cancel", { id: exId, now_ms: now });
-                    const row = this.all("insert_task", ins)[0];
-                    this.run("upsert_key", { key, task_id: id, now_ms: now });
-                    return row;
-                }
-                throw new Error(`unknown conflict strategy: ${conflict}`);
+        const bound = {};
+        for (const name of statementParams(sql)) {
+            switch (name) {
+                case "now_ms":
+                    bound[name] = now;
+                    break;
+                case "lease_until_ms":
+                    bound[name] = now + params.lease_ms;
+                    break;
+                case "run_at_ms":
+                    bound[name] = now + params.delay_ms;
+                    break;
+                case "before_ms":
+                    bound[name] = now - params.older_than_ms;
+                    break;
+                case "queues":
+                    bound[name] = JSON.stringify(params.queues);
+                    break;
+                case "names":
+                    // json_each needs a JSON array; null stays null so the SQL's
+                    // `:names is null` arm means "no filter".
+                    bound[name] = params.names == null ? null : JSON.stringify(params.names);
+                    break;
+                case "retryable":
+                case "reset_attempt":
+                    bound[name] = params[name] ? 1 : 0;
+                    break;
+                default:
+                    bound[name] = params[name];
             }
-            const row = this.all("insert_task", ins)[0];
-            this.run("upsert_key", { key, task_id: id, now_ms: now });
-            return row;
-        });
-        return rowToTask(txn.immediate());
-    }
-    async get(taskId) {
-        this.ensure();
-        const rows = this.all("get", { id: taskId });
-        return rows.length ? rowToTask(rows[0]) : null;
-    }
-    async getByKey(key) {
-        this.ensure();
-        const rows = this.all("get_by_key", { key });
-        return rows.length ? rowToTask(rows[0]) : null;
-    }
-    async list(input = {}) {
-        this.ensure();
-        const rows = this.all("list", {
-            status: input.status ?? null,
-            queue: input.queue ?? null,
-            name: input.name ?? null,
-            root_id: input.rootId ?? null,
-            correlation_id: input.correlationId ?? null,
-            limit: input.limit ?? 100,
-            offset: input.offset ?? 0,
-        });
-        return rows.map(rowToTask);
-    }
-    async cancel(taskId) {
-        this.ensure();
-        const rows = this.all("cancel", { id: taskId, now_ms: nowMs() });
-        return rows.length ? rowToTask(rows[0]) : null;
-    }
-    async cancelByKey(key) {
-        this.ensure();
-        const txn = this.db.transaction(() => {
-            const existing = this.all("get_key", { key });
-            if (!existing.length)
-                return null;
-            const rows = this.all("cancel", { id: existing[0].task_id, now_ms: nowMs() });
-            return rows.length ? rows[0] : null;
-        });
-        const row = txn.immediate();
-        return row ? rowToTask(row) : null;
-    }
-    async retry(taskId, opts = {}) {
-        this.ensure();
-        const rows = this.all("retry", {
-            id: taskId,
-            now_ms: nowMs(),
-            reset_attempt: opts.resetAttempt ? 1 : 0,
-        });
-        return rows.length ? rowToTask(rows[0]) : null;
-    }
-    async retryByKey(key, opts = {}) {
-        this.ensure();
-        const txn = this.db.transaction(() => {
-            const existing = this.all("get_key", { key });
-            if (!existing.length)
-                return null;
-            const rows = this.all("retry", {
-                id: existing[0].task_id,
-                now_ms: nowMs(),
-                reset_attempt: opts.resetAttempt ? 1 : 0,
-            });
-            return rows.length ? rows[0] : null;
-        });
-        const row = txn.immediate();
-        return row ? rowToTask(row) : null;
+        }
+        return bound;
     }
-    // ------------------------------------------------------------- worker side
-    async claim(input) {
-        this.ensure();
-        const now = nowMs();
-        const queues = JSON.stringify(input.queues);
-        const leaseMs = input.leaseMs ?? 30_000;
-        const limit = input.limit ?? 1;
-        // Read-only probe first: skip the write lock entirely when idle.
-        const probe = this.all("claimable_probe", { queues, now_ms: now })[0];
-        if (!probe || !probe.has_work)
+    runNow(name, params) {
+        const stmt = this.stmts[name];
+        const bound = this.bind(this.statements[name], params);
+        // Nearly every protocol statement ends in RETURNING; upsert_key does not, and
+        // better-sqlite3 refuses .all() on a statement that yields no rows.
+        if (!stmt.reader) {
+            stmt.run(bound);
             return [];
-        const txn = this.db.transaction(() => {
-            this.all("recover_leases", {
-                now_ms: now,
-                lease_expired_error: LEASE_EXPIRED_ERROR_JSON,
-            });
-            return this.all("claim", {
-                queues,
-                now_ms: now,
-                worker_id: input.workerId,
-                lease_until_ms: now + leaseMs,
-                limit,
-            });
-        });
-        return txn.immediate().map(rowToTask);
-    }
-    async heartbeat(input) {
-        this.ensure();
-        const now = nowMs();
-        return this.ownedWrite("heartbeat", input.taskId, {
-            id: input.taskId,
-            worker_id: input.workerId,
-            now_ms: now,
-            lease_until_ms: now + (input.leaseMs ?? 30_000),
-        });
+        }
+        return stmt.all(bound);
     }
-    async progress(input) {
-        this.ensure();
-        return this.ownedWrite("progress", input.taskId, {
-            id: input.taskId,
-            worker_id: input.workerId,
-            now_ms: nowMs(),
-            progress: input.progress,
-            message: input.message,
-        });
+    /** Serialize an operation against every other operation on this database. */
+    withLock(fn) {
+        const previous = fileLocks.get(this.lockKey) ?? Promise.resolve();
+        const run = previous.then(fn, fn);
+        fileLocks.set(this.lockKey, run.then(() => undefined, () => undefined));
+        return run;
     }
-    async succeed(input) {
+    async fetch(name, params) {
         this.ensure();
-        return this.ownedWrite("succeed", input.taskId, {
-            id: input.taskId,
-            worker_id: input.workerId,
-            now_ms: nowMs(),
-            result: input.result == null ? null : JSON.stringify(input.result),
-            message: null,
-        });
+        return this.withLock(() => this.runNow(name, params));
     }
-    async complete(input) {
-        this.ensure();
-        return this.ownedWrite("complete", input.taskId, {
-            id: input.taskId,
-            worker_id: input.workerId,
-            now_ms: nowMs(),
-            result: input.result == null ? null : JSON.stringify(input.result),
+    async tx(fn) {
+        const db = this.ensure();
+        // BEGIN IMMEDIATE by hand rather than db.transaction(): the callback is async
+        // (the seam is shared with Postgres), and better-sqlite3's wrapper only takes
+        // a synchronous one. The lock above makes the manual version safe.
+        return this.withLock(async () => {
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                const out = await fn(async (name, params) => this.runNow(name, params));
+                db.exec("COMMIT");
+                return out;
+            }
+            catch (err) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    // Already rolled back by SQLite (e.g. a constraint abort).
+                }
+                throw err;
+            }
         });
     }
-    async fail(input) {
-        this.ensure();
-        return this.ownedWrite("fail", input.taskId, {
-            id: input.taskId,
-            worker_id: input.workerId,
-            now_ms: nowMs(),
-            error: JSON.stringify(input.error ?? {}),
-            retryable: input.retryable === false ? 0 : 1,
-            delay_ms: input.delayMs ?? 0,
-        });
+    async hasClaimableWork(params) {
+        // Read-only probe first: an idle worker never takes SQLite's single write
+        // lock, so idle workers don't serialize against each other.
+        const rows = await this.fetch("claimable_probe", params);
+        return Boolean(rows[0]?.has_work);
     }
 }

package/dist/wait.d.ts

@@ -1,8 +1,21 @@
 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;
+/**
+ * Grow the polling interval towards the ceiling.
+ *
+ * wait() has no idea whether the task takes 50ms or an hour. Starting tight keeps
+ * short tasks snappy; growing keeps a long wait from costing a read every 100ms
+ * for its whole duration. The +1 keeps truncation from pinning tiny intervals:
+ * Math.floor(1 * 1.5) === 1 would otherwise never grow past 1.
+ */
+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. */
-export declare function pollWait(store: TaskStore, taskId: string, { timeoutMs, pollMs }: {
+ * 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>;

package/dist/wait.js

@@ -1,18 +1,36 @@
 import { TaskTimeout } from "./errors.js";
 import { nowMs } from "./ids.js";
 import { isTerminal } from "./models.js";
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const DEFAULT_POLL_MS = 100;
+export const MAX_POLL_MS = 500;
+const GROWTH = 1.5;
+/**
+ * Grow the polling interval towards the ceiling.
+ *
+ * wait() has no idea whether the task takes 50ms or an hour. Starting tight keeps
+ * short tasks snappy; growing keeps a long wait from costing a read every 100ms
+ * for its whole duration. The +1 keeps truncation from pinning tiny intervals:
+ * Math.floor(1 * 1.5) === 1 would otherwise never grow past 1.
+ */
+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. */
-export async function pollWait(store, taskId, { timeoutMs, pollMs = 150 }) {
+ * 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, }) {
     const deadline = nowMs() + timeoutMs;
+    let interval = pollMs;
     for (;;) {
         const task = await store.get(taskId);
         if (task && isTerminal(task))
             return task;
         const remaining = deadline - nowMs();
         if (remaining <= 0)
-            throw new TaskTimeout(taskId);
-        await sleep(Math.min(pollMs, remaining));
+            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));
+        interval = nextPollMs(interval, maxPollMs);
     }
 }

package/dist/worker.d.ts

@@ -4,13 +4,40 @@ import { type TaskDef } from "./task.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>;
+/** Where an error the worker recovered from came from. */
+export type ErrorPhase = "claim" | "execute";
 export interface WorkerOptions {
     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. */
+    retryBackoffMaxMs?: number;
+    /**
+     * Wall-clock ceiling for one attempt. The heartbeat renews the lease for as
+     * long as a handler runs, so a hung handler would otherwise hold its task
+     * `running` (and its concurrency slot) forever — cancel can't help,
+     * cooperative checks need a live handler. On expiry the worker abandons the
+     * attempt (ctx.signal aborts, further ctx writes throw LostLease) and records
+     * a retryable `handler_timeout` failure. Unset disables the ceiling.
+     */
+    maxRunMs?: 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
+     * loop carries on either way, so this is the only place an operator learns a
+     * worker is limping. Must not throw.
+     */
+    onError?: (err: unknown, info: {
+        phase: ErrorPhase;
+        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;
@@ -18,7 +45,8 @@ export declare class Worker {
     private readonly handlers;
     private readonly workerId;
     private stopped;
-    private stopResolvers;
+    private stopWake;
+    private readonly stopped$;
     private ownsStore;
     constructor(store: TaskStore, queues: string[], opts?: WorkerOptions);
     static sqlite(path: string, opts?: WorkerOptions & {
@@ -39,9 +67,11 @@ export declare class Worker {
     /** Close the underlying store connection. Call after run() returns. */
     close(): Promise<void>;
     private closeIfOwned;
+    private report;
     run(opts?: {
         concurrency?: number;
     }): Promise<void>;
+    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;
      * use run() / background() when you manage the event loop yourself. */
@@ -52,9 +82,31 @@ export declare class Worker {
     background<T>(fn: () => Promise<T>, opts?: {
         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.)
+     */
     private execute;
+    /**
+     * 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.
+     */
+    private attempt;
     private startHeartbeat;
     private safeFail;
+    /**
+     * The empty-poll sleep. A store with a push channel (Postgres LISTEN/NOTIFY)
+     * cuts it short when a task on this worker's queues becomes claimable;
+     * stop() interrupts it either way, and sleepOrStop bounds it at `ms` so the
+     * poll fallback — which also drives lease recovery — never stretches.
+     */
+    private idle;
     private sleepOrStop;
+    /** Take SIGINT/SIGTERM for the duration of serve(). Returns the undo. */
     private installSignals;
 }