cairnq 0.8.0 → 0.10.0

package/README.md

@@ -1,8 +1,12 @@
 # cairnq (TypeScript / Node)
 
 SQLite-first, cross-language, storage-centered durable task runtime. The
-TypeScript SDK (Node ≥ 20, `better-sqlite3`). API and worker processes coordinate
-only through a shared SQLite file.
+TypeScript SDK (Node ≥ 20). API and worker processes coordinate only through a
+shared SQLite file.
+
+Both drivers are optional peers — install the one you use:
+`npm i better-sqlite3` for the SQLite backend, `npm i pg` for Postgres. Importing
+`cairnq` loads neither, so a Postgres-only deployment builds no native module.
 
 ```ts
 import { CairnQ, Worker } from "cairnq";
@@ -98,5 +102,72 @@ worker.task("long.job", async (ctx) => {
 Same code, Postgres instead of the file — `CairnQ.postgres(dsn)` /
 `Worker.postgres(dsn)`. Requires the optional `pg` peer dependency (`npm i pg`).
 
+### Sharing the application's connection
+
+Given a `PgExecutor` instead of a DSN, cairnq runs inside a session the
+application already has — no second driver, no second pool:
+
+```ts
+import { CairnQ, type PgExecutor } from "cairnq";
+
+const executor: PgExecutor = { /* ~30 lines over your driver */ };
+const tasks = CairnQ.postgres(executor);
+```
+
+`schema` puts cairnq's tables in a schema of their own:
+`CairnQ.postgres(dsn, { schema: "cairnq" })` creates it if absent and sets
+`search_path` per connection. The protocol's SQL names no schema, so nothing else
+changes. With your own executor the search_path is yours to set, and `schema`
+becomes an assertion about where it lands.
+
+**Every process in a deployment must agree on it.** A queue whose API and worker
+resolve to different schemas is two empty queues, and — because every migration is
+`create table if not exists` — both sides come up healthy, pass their protocol
+version check, and never see each other's tasks. cairnq refuses to connect where
+it can see that about to happen (`SchemaMismatch`); the Python SDK applies the
+same rule.
+
+Two things an adapter must get right: `int8` has to come back as a JS number
+(every cairnq `*_ms` is an epoch or a counter, all inside the safe range), and
+`jsonb` as an object rather than a string. An executor cairnq was handed is
+never closed by cairnq.
+
+That shared session is also what lets a task's settlement commit together with
+the rows the task produced:
+
+```ts
+worker.task("render.document", async (ctx, payload) => {
+  const rendered = await render(payload);
+  return ctx.succeedIn(async (session) => {
+    await db.withSession(session).insert(pages).values(rendered);
+    return { pages: rendered.length }; // becomes the task's result
+  });
+});
+```
+
+Without it the two are separate transactions, and a crash between them leaves
+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/sql/postgres/installations.sql

@@ -0,0 +1,33 @@
+-- Where cairnq already lives in this database, and where this connection is
+-- pointing. Read-only; runs once per connect, before migrations.
+--
+-- Exists because `search_path` is out-of-band configuration: two processes given
+-- the same DSN can still resolve to different schemas, and because every
+-- migration is `create table if not exists`, the second one to start does not
+-- fail — it quietly builds a parallel, empty installation. Nothing downstream can
+-- tell: protocol_version reads from whichever cairnq_meta the connection sees, so
+-- the version check passes on both sides while the API's tasks are invisible to
+-- the worker forever. The only way to catch that is to look OUTSIDE the
+-- connection's own search_path, which is what this does.
+--
+-- One row per installation, never zero: the LEFT JOIN keeps `current_schema`
+-- readable on a database that holds no cairnq yet, where `schema` is null.
+-- Deliberately NOT an array column — pg_namespace.nspname is `name`, and which
+-- drivers decode a `name[]` (or a text[]) into a list is exactly the kind of
+-- disagreement this protocol keeps out of the SDKs. Scalar columns behave the
+-- same everywhere.
+--
+-- `current_schema()` is null when the search_path names nothing that exists, in
+-- which case the caller cannot conclude anything.
+-- params: (none)
+select
+    current_schema()::text as current_schema,
+    found.schema
+from (select 1) one
+left join (
+    select n.nspname::text as schema
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where c.relname = 'cairnq_tasks' and c.relkind = 'r'
+) found on true
+order by found.schema;

package/dist/client.d.ts

@@ -1,7 +1,8 @@
 import type { BackpressureOptions } from "./backpressure.js";
 import { type RetentionOptions } from "./retention.js";
 import { type Task, type TaskRef, type TaskStatus } from "./models.js";
-import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
+import type { PgExecutor } from "./store/pg-executor.js";
+import type { ListInput, PurgeInput, SubmitInput, TaskStore, WatchOptions, WatchSignal } from "./store/base.js";
 import { type TaskDef } from "./task.js";
 import { type PollOptions } from "./wait.js";
 export type SubmitOptions = Omit<SubmitInput, "name" | "payload">;
@@ -28,10 +29,13 @@ export declare class CairnQ {
     static sqlite(path: string, opts?: {
         busyTimeoutMs?: number;
     } & ClientOptions): CairnQ;
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn: string, opts?: {
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs (an ORM's pool, say), which cairnq then shares instead of
+     * opening a second one. */
+    static postgres(source: string | PgExecutor, opts?: {
         max?: number;
+        schema?: string;
     } & ClientOptions): CairnQ;
     get store(): TaskStore;
     connect(): Promise<void>;
@@ -73,6 +77,17 @@ export declare class CairnQ {
     /** Task counts per queue, keyed by status and zero-filled across all statuses
      * — `(await stats()).default.queued` is the backlog of a queue. */
     stats(): 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. */

package/dist/client.js

@@ -29,11 +29,13 @@ export class CairnQ {
         const { busyTimeoutMs, ...client } = opts;
         return new CairnQ(new SQLiteStore(path, { busyTimeoutMs }), client);
     }
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn, opts = {}) {
-        const { max, ...client } = opts;
-        return new CairnQ(new PostgresStore(dsn, { max }), client);
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs (an ORM's pool, say), which cairnq then shares instead of
+     * opening a second one. */
+    static postgres(source, opts = {}) {
+        const { max, schema, ...client } = opts;
+        return new CairnQ(new PostgresStore(source, { max, schema }), client);
     }
     get store() {
         return this._store;
@@ -99,6 +101,19 @@ export class CairnQ {
     stats() {
         return this._store.stats();
     }
+    /**
+     * 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. */

package/dist/context.d.ts

@@ -2,6 +2,7 @@ import { type FailReason } from "./errors.js";
 import { type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
+import type { PgSession } from "./store/pg-executor.js";
 import { type TaskDef } from "./task.js";
 export interface TaskContextOptions {
     retryBackoffMs?: number;
@@ -18,7 +19,7 @@ export interface TaskContextOptions {
 export declare class TaskContext {
     private readonly store;
     private readonly task;
-    readonly workerId: string;
+    private readonly ownerId;
     private readonly leaseMs;
     private readonly abort;
     private leaseLost;
@@ -26,8 +27,10 @@ export declare class TaskContext {
     private isSettled;
     private readonly backoffMs;
     private readonly backoffMaxMs;
-    constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number, opts?: TaskContextOptions);
+    constructor(store: TaskStore, task: Task, ownerId: string, leaseMs: number, opts?: TaskContextOptions);
     get taskId(): string;
+    /** The worker running this task — what `worker_id` on the row points at. */
+    get workerId(): string;
     get name(): string;
     get queue(): string;
     get attempt(): number;
@@ -74,6 +77,30 @@ export declare class TaskContext {
      * this task was already settled.
      */
     succeed(result?: unknown): Promise<Task | null>;
+    /**
+     * Finalize this task as succeeded, committing the caller's own writes in the
+     * SAME transaction as the settlement. Whatever `write` returns becomes the
+     * task's result.
+     *
+     *     await ctx.succeedIn(async (session) => {
+     *       await db.withSession(session).insert(pages).values(rendered)
+     *       return { pages: rendered.length }
+     *     })
+     *
+     * The alternative — write the rows, then settle — has a window between the two
+     * commits where the work is durable but the task still reads as running. A
+     * crash there re-runs the whole task, which for a render or an ingest means
+     * recomputing it, and for non-idempotent work means doing it twice.
+     *
+     * `session` is the driver's, so this needs a Postgres store built on a
+     * PgExecutor the application shares with its own driver; anything else throws.
+     * If the settlement finds the lease gone, `write`'s work is rolled back with
+     * it and LostLease is raised. Returns null if this task was already settled.
+     *
+     * `write` may be replayed if the backend retries the transaction — derive
+     * nothing inside it that cannot be derived twice.
+     */
+    succeedIn<T>(write: (session: PgSession) => Promise<T>): Promise<Task | null>;
     /**
      * Finalize this task as failed, now. `error` may be a string reason, an Error,
      * a TaskError (which carries its own retryability), or a ready envelope.

package/dist/context.js

@@ -14,7 +14,7 @@ import { pollWait } from "./wait.js";
 export class TaskContext {
     store;
     task;
-    workerId;
+    ownerId;
     leaseMs;
     abort = new AbortController();
     leaseLost = false;
@@ -28,10 +28,10 @@ export class TaskContext {
     isSettled = false;
     backoffMs;
     backoffMaxMs;
-    constructor(store, task, workerId, leaseMs, opts = {}) {
+    constructor(store, task, ownerId, leaseMs, opts = {}) {
         this.store = store;
         this.task = task;
-        this.workerId = workerId;
+        this.ownerId = ownerId;
         this.leaseMs = leaseMs;
         this.backoffMs = opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
         this.backoffMaxMs = opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS;
@@ -39,6 +39,10 @@ export class TaskContext {
     get taskId() {
         return this.task.id;
     }
+    /** The worker running this task — what `worker_id` on the row points at. */
+    get workerId() {
+        return this.ownerId;
+    }
     get name() {
         return this.task.name;
     }
@@ -138,7 +142,7 @@ export class TaskContext {
     async progress(value, message = null) {
         return this.owned(() => this.store.progress({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             progress: value,
             message,
         }));
@@ -146,7 +150,7 @@ export class TaskContext {
     async heartbeat() {
         return this.owned(() => this.store.heartbeat({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             leaseMs: this.leaseMs,
         }));
     }
@@ -180,7 +184,40 @@ export class TaskContext {
     async succeed(result = null) {
         if (this.isSettled)
             return null;
-        const task = await this.owned(() => this.store.complete({ taskId: this.task.id, workerId: this.workerId, result }));
+        const task = await this.owned(() => this.store.complete({ taskId: this.task.id, workerId: this.ownerId, result }));
+        this.markSettled();
+        return task;
+    }
+    /**
+     * Finalize this task as succeeded, committing the caller's own writes in the
+     * SAME transaction as the settlement. Whatever `write` returns becomes the
+     * task's result.
+     *
+     *     await ctx.succeedIn(async (session) => {
+     *       await db.withSession(session).insert(pages).values(rendered)
+     *       return { pages: rendered.length }
+     *     })
+     *
+     * The alternative — write the rows, then settle — has a window between the two
+     * commits where the work is durable but the task still reads as running. A
+     * crash there re-runs the whole task, which for a render or an ingest means
+     * recomputing it, and for non-idempotent work means doing it twice.
+     *
+     * `session` is the driver's, so this needs a Postgres store built on a
+     * PgExecutor the application shares with its own driver; anything else throws.
+     * If the settlement finds the lease gone, `write`'s work is rolled back with
+     * it and LostLease is raised. Returns null if this task was already settled.
+     *
+     * `write` may be replayed if the backend retries the transaction — derive
+     * nothing inside it that cannot be derived twice.
+     */
+    async succeedIn(write) {
+        if (this.isSettled)
+            return null;
+        const task = await this.owned(async () => {
+            const { task } = await this.store.completeIn({ taskId: this.task.id, workerId: this.ownerId }, write);
+            return task;
+        });
         this.markSettled();
         return task;
     }
@@ -196,7 +233,7 @@ export class TaskContext {
         const [envelope, retryable] = asEnvelope(error, opts.retryable ?? true);
         const task = await this.owned(() => this.store.fail({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             error: envelope,
             retryable,
             delayMs: failDelayMs(this.task.attempt, retryable, this.backoffMs, this.backoffMaxMs),

package/dist/errors.d.ts

@@ -101,6 +101,23 @@ export declare class LostLease extends CairnQError {
 export declare class ProtocolVersionMismatch extends CairnQError {
     constructor(message: string);
 }
+/**
+ * This connection is not pointed at the cairnq installation the rest of the
+ * deployment is using — raised at connect, before any task is written.
+ *
+ * The schema a Postgres connection resolves to is out-of-band configuration
+ * (`search_path`, a `schema` option, an ORM's pool settings), so two processes
+ * given the same DSN can still land in different schemas. Every migration is
+ * `create table if not exists`, so the odd one out does not fail: it builds a
+ * second, empty installation and its protocol version check passes against the
+ * cairnq_meta it just created. Left undetected, an API and a worker then agree
+ * about everything except WHERE, and no task ever crosses.
+ *
+ * The Python SDK raises the same named error.
+ */
+export declare class SchemaMismatch 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

package/dist/errors.js

@@ -187,6 +187,26 @@ export class ProtocolVersionMismatch extends CairnQError {
         this.name = "ProtocolVersionMismatch";
     }
 }
+/**
+ * This connection is not pointed at the cairnq installation the rest of the
+ * deployment is using — raised at connect, before any task is written.
+ *
+ * The schema a Postgres connection resolves to is out-of-band configuration
+ * (`search_path`, a `schema` option, an ORM's pool settings), so two processes
+ * given the same DSN can still land in different schemas. Every migration is
+ * `create table if not exists`, so the odd one out does not fail: it builds a
+ * second, empty installation and its protocol version check passes against the
+ * cairnq_meta it just created. Left undetected, an API and a worker then agree
+ * about everything except WHERE, and no task ever crosses.
+ *
+ * The Python SDK raises the same named error.
+ */
+export class SchemaMismatch extends CairnQError {
+    constructor(message) {
+        super(message);
+        this.name = "SchemaMismatch";
+    }
+}
 /** 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

package/dist/index.d.ts

@@ -12,9 +12,13 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { ListenUnavailable } from "./store/pg-executor.js";
+export type { PgExecutor, PgSession, Row } from "./store/pg-executor.js";
+export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
-export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
+export type { ListInput, PurgeInput, SubmitInput, Conflict, WatchOptions, WatchSignal, } from "./store/base.js";
+export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
 export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, SerializationError, } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/dist/index.js

@@ -6,6 +6,9 @@ export { TaskContext } from "./context.js";
 export { defineTask } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { ListenUnavailable } from "./store/pg-executor.js";
+export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
+export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, SerializationError, } from "./errors.js";

package/dist/models.js

@@ -4,6 +4,19 @@
 // conformance suite pins this set against.
 export const STATUSES = ["queued", "running", "succeeded", "failed", "canceled"];
 const JSON_COLUMNS = ["payload", "result", "error", "metadata"];
+// The bigint columns. `attempt` / `max_attempts` / `priority` are int4 and
+// `progress` is double precision, so every driver already gives those as numbers;
+// only int8 has a wire form worth normalizing. Nullability differs per column
+// (completed_at_ms may be null, created_at_ms may not), so the coercion has to
+// preserve null rather than turn it into 0.
+const MS_COLUMNS = [
+    "lease_until_ms",
+    "run_at_ms",
+    "cancel_requested_at_ms",
+    "created_at_ms",
+    "updated_at_ms",
+    "completed_at_ms",
+];
 // As a const tuple so TerminalStatus derives from it — the same declare-once
 // pattern as STATUSES/TaskStatus above.
 export const TERMINAL = ["succeeded", "failed", "canceled"];
@@ -24,6 +37,20 @@ export function rowToTask(row) {
         // already-decoded object. Parse only a string — never assume one backend.
         t[col] = typeof v === "string" ? JSON.parse(v) : (v ?? null);
     }
+    for (const col of MS_COLUMNS) {
+        const v = row[col];
+        // Same argument, for the other column type the drivers disagree about.
+        // Postgres sends int8 down the wire as text to protect precision it cannot
+        // know is unneeded; `pg` surfaces that as a string, postgres.js does too,
+        // asyncpg decodes to int. Normalizing here rather than demanding it of every
+        // driver is what keeps an INJECTED executor honest: the alternative is
+        // asking an application to change its driver's global int8 handling to suit
+        // cairnq, which breaks that application's own bigint columns.
+        //
+        // Lossless: every one of these is an epoch-ms, and a millisecond timestamp
+        // does not reach Number.MAX_SAFE_INTEGER until the year 287396.
+        t[col] = v == null ? null : Number(v);
+    }
     return t;
 }
 /** Accepts anything carrying a status — a Task or a TaskRef probe. */

package/dist/store/base.d.ts

@@ -83,6 +83,32 @@ export declare function statementParams(sql: string): readonly string[];
  * them in one place is what stops SQLite and Postgres from drifting apart in
  * behavior; the shared SQL already stops them from drifting in wording.
  */
+/**
+ * Why `watch` is calling back.
+ *
+ * `queued` / `done` come from the store's push channel and name what moved;
+ * `poll` is the timer saying the watch cannot rule out a change. None of them
+ * carries state — the row is the truth.
+ */
+export interface WatchSignal {
+    reason: "queued" | "done" | "poll";
+    /** The queue a task was queued on. Only on `queued`. */
+    queue?: string;
+    /** The task that reached a terminal status. Only on `done`. */
+    taskId?: string;
+}
+export interface WatchOptions {
+    /** Restrict `queued` signals to these queues. Unset watches every queue. */
+    queues?: string[];
+    /**
+     * How often to signal in the absence of a push channel — and, where there is
+     * one, how long a dropped listener can go unnoticed. The default trades a
+     * dashboard's idle query rate against how stale it may look.
+     */
+    pollMs?: number;
+}
+/** See WatchOptions.pollMs. */
+export declare const DEFAULT_WATCH_POLL_MS = 2000;
 export declare abstract class TaskStore {
     /** Set by useBackpressure; null means submit is ungated. */
     private gate;
@@ -100,6 +126,34 @@ export declare abstract class TaskStore {
      * build ids and payloads before opening the transaction, not within it.
      */
     protected abstract tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
+    /**
+     * `tx`, but also handing `fn` the driver's own session so the CALLER can run
+     * their statements in the same transaction as the protocol's.
+     *
+     * This is what lets a task's settlement and the rows that task produced commit
+     * together. Without it the two are separate transactions and there is a window
+     * where the work is durable but the task still reads as unfinished — a crash
+     * there costs a full recomputation on retry, and for non-idempotent work costs
+     * more than that.
+     *
+     * Optional, because the session type is the driver's, not the protocol's: a
+     * store that has no session worth handing out simply does not implement it and
+     * `completeIn` reports that. Postgres implements it; SQLite does not.
+     */
+    protected txWithSession?<T>(fn: (fetch: Fetch, session: unknown) => Promise<T>): Promise<T>;
+    /**
+     * Register for this store's push channel, if it has one; returns an
+     * unsubscribe. A store without a push channel does not implement this, and
+     * `watch` degrades to its timer alone.
+     */
+    protected subscribePush?(onSignal: (signal: WatchSignal) => void): () => void;
+    /**
+     * Nudge the push channel back up if it has dropped. Called from `watch`'s
+     * timer, which is the only thing keeping a client-side subscriber alive: a
+     * process that never claims never calls claimWake, so without this a listener
+     * that died once would never come back there.
+     */
+    protected warmPush?(): void;
     /**
      * Whether it is worth opening the claim transaction at all. SQLite gates its
      * single write lock behind a read-only probe; Postgres readers don't block
@@ -169,6 +223,28 @@ export declare abstract class TaskStore {
      * them.
      */
     stats(): Promise<Record<string, Record<TaskStatus, number>>>;
+    /**
+     * Call `onSignal` when the tasks on `queues` may have changed — something was
+     * queued, or something finished.
+     *
+     * This is notify-ACCELERATED POLLING, not an event log, and the difference is
+     * the whole contract. Where a push channel is available (Postgres LISTEN) an
+     * idle watch costs nothing and a signal arrives within milliseconds of the
+     * event. Where it is not — a transaction-mode pooler refuses LISTEN, SQLite has
+     * no channel at all — the timer alone still delivers `poll` signals, so a
+     * consumer that re-reads on every signal is correct in both cases and merely
+     * less prompt in one.
+     *
+     * What it will NOT do is promise that a signal means something happened, or
+     * that every event produces its own signal. Treat a signal as "re-read now"
+     * and take the truth from `stats()` / `list()` / `get()`, which is where it
+     * lives. `reason` is a hint for reading less: a `done` signal names the task,
+     * so a dashboard can refresh that row instead of the list.
+     *
+     * Returns an unsubscribe. The timer is unref'd — watching does not hold a
+     * process open.
+     */
+    watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void;
     /**
      * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
      *
@@ -262,6 +338,29 @@ export declare abstract class TaskStore {
         workerId: string;
         result: unknown;
     }): Promise<Task>;
+    /**
+     * `complete`, with the caller's own writes committed in the same transaction.
+     *
+     * `fn` runs first and whatever it returns becomes the task's result; the
+     * settlement is the last statement in the transaction. So a lost lease — the
+     * settlement matching no row — rolls the caller's writes back with it, and
+     * there is no ordering in which the work is recorded but the task is not.
+     *
+     * The settlement runs LAST rather than checking ownership up front on purpose:
+     * the ownership predicate lives in the protocol's complete.sql, and a
+     * fail-fast pre-check here would be a second copy of it, free to drift. The
+     * cost of that choice is that a doomed attempt does its work before finding
+     * out, which is the rare path.
+     *
+     * `fn` must be replayable for the same reason `tx`'s callback must be.
+     */
+    completeIn<S, T>(input: {
+        taskId: string;
+        workerId: string;
+    }, fn: (session: S) => Promise<T>): Promise<{
+        task: Task;
+        value: T;
+    }>;
     fail(input: {
         taskId: string;
         workerId: string;