cairnq 0.1.0 → 0.2.0

package/dist/worker.js

@@ -1,9 +1,20 @@
 import { TaskContext } from "./context.js";
-import { errorEnvelope, LostLease, TaskError } from "./errors.js";
+import { errorEnvelope, LostLease, SerializationError, TaskError } from "./errors.js";
 import { newId } from "./ids.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
 import { taskName } from "./task.js";
+const DEFAULT_RETRY_BACKOFF_MS = 1_000;
+const DEFAULT_RETRY_BACKOFF_MAX_MS = 30_000;
+/** Wait after a failed claim, so a broken database is not polled in a tight loop. */
+const CLAIM_ERROR_BACKOFF_MS = 250;
+/** Exponential backoff for the next attempt of a task that just failed. */
+export function retryDelayMs(attempt, baseMs, maxMs) {
+    if (baseMs <= 0)
+        return 0;
+    const exponent = Math.max(0, attempt - 1);
+    return Math.min(maxMs, baseMs * 2 ** exponent);
+}
 function exceptionEnvelope(err) {
     const e = err;
     return errorEnvelope({
@@ -13,6 +24,23 @@ function exceptionEnvelope(err) {
         retryable: true,
     });
 }
+/** Internal: an attempt outran maxRunMs and was abandoned. */
+class AttemptTimeout extends Error {
+    maxRunMs;
+    constructor(maxRunMs) {
+        super(`attempt exceeded ${maxRunMs}ms`);
+        this.maxRunMs = maxRunMs;
+    }
+}
+function timeoutEnvelope(name, maxRunMs) {
+    return errorEnvelope({
+        type: "HandlerTimeout",
+        code: "handler_timeout",
+        message: `handler for ${name} exceeded maxRunMs=${maxRunMs}ms; the attempt was abandoned`,
+        retryable: true,
+    });
+}
+const TIMED_OUT = Symbol("cairnq.timedOut");
 export class Worker {
     store;
     queues;
@@ -20,7 +48,10 @@ export class Worker {
     handlers = new Map();
     workerId = newId("worker");
     stopped = false;
-    stopResolvers = [];
+    stopWake;
+    // Resolved once by stop(); every sleep races against it. A stopped worker
+    // never restarts, so one promise serves the instance's lifetime.
+    stopped$ = new Promise((r) => (this.stopWake = r));
     // True only when this worker created its own store (via Worker.sqlite); an
     // injected store may be shared, so serve()/background() must not close it.
     ownsStore = false;
@@ -28,6 +59,9 @@ export class Worker {
         this.store = store;
         this.queues = queues;
         this.opts = opts;
+        if (opts.maxRunMs != null && opts.maxRunMs <= 0) {
+            throw new Error(`maxRunMs must be > 0, got ${opts.maxRunMs}`);
+        }
     }
     static sqlite(path, opts = {}) {
         const { queues = ["default"], busyTimeoutMs, ...rest } = opts;
@@ -51,8 +85,10 @@ export class Worker {
         let fn;
         if (typeof arg === "function") {
             // Bare form: worker.task(fn) — registered under the function's name.
+            // Strip the "bound " prefix .bind() stamps on it: otherwise a bound
+            // method registers under "bound process", a name no submit ever uses.
             fn = arg;
-            name = fn.name;
+            name = fn.name.replace(/^(bound )+/, "");
             if (!name) {
                 throw new Error("worker.task(fn): the handler is anonymous; pass a name explicitly, " +
                     "e.g. worker.task('summary.create', fn)");
@@ -68,10 +104,7 @@ export class Worker {
     }
     stop() {
         this.stopped = true;
-        const resolvers = this.stopResolvers;
-        this.stopResolvers = [];
-        for (const r of resolvers)
-            r();
+        this.stopWake();
     }
     /** Close the underlying store connection. Call after run() returns. */
     async close() {
@@ -84,28 +117,66 @@ export class Worker {
         if (this.ownsStore)
             await this.close();
     }
+    report(err, info) {
+        try {
+            this.opts.onError?.(err, info);
+        }
+        catch {
+            // A reporting hook must never take the worker down with it.
+        }
+    }
     async run(opts = {}) {
-        const concurrency = opts.concurrency ?? this.opts.concurrency ?? 1;
+        // Clamped: at 0 the loop would await Promise.race([]) — pending forever,
+        // beyond even stop()'s reach.
+        const concurrency = Math.max(1, opts.concurrency ?? this.opts.concurrency ?? 1);
         const leaseMs = this.opts.leaseMs ?? 30_000;
-        const pollMs = this.opts.pollIntervalMs ?? 500;
         const batch = this.opts.claimBatch ?? concurrency;
         await this.store.connect();
-        this.installSignals();
         const running = new Set();
+        try {
+            await this.loop(concurrency, batch, leaseMs, running);
+        }
+        finally {
+            // Whatever ends the loop — stop(), or something unexpected out of the body
+            // — nothing this worker started may outlive run(). serve() closes the store
+            // as soon as run() settles, and a handler still holding the connection
+            // would fault on it.
+            await Promise.all([...running]);
+        }
+    }
+    async loop(concurrency, batch, leaseMs, running) {
+        const pollMs = this.opts.pollIntervalMs ?? 500;
         while (!this.stopped) {
             const free = concurrency - running.size;
             if (free <= 0) {
-                await this.sleepOrStop(5);
+                // Wait for a slot rather than spinning. execute() never rejects, so
+                // racing these is safe.
+                await Promise.race([...running]);
+                continue;
+            }
+            let claimed;
+            try {
+                claimed = await this.store.claim({
+                    queues: this.queues,
+                    // Only what this worker can run. Queues do not partition work by task
+                    // name, so another worker's tasks would otherwise be claimed here and
+                    // failed for want of a handler. Read each poll: handlers may be
+                    // registered after run() started.
+                    names: [...this.handlers.keys()],
+                    workerId: this.workerId,
+                    leaseMs,
+                    limit: Math.min(batch, free),
+                });
+            }
+            catch (err) {
+                // A claim can fail transiently (lock contention, a dropped connection).
+                // Report it and keep polling — one bad poll must not end the worker.
+                this.report(err, { phase: "claim" });
+                await this.sleepOrStop(CLAIM_ERROR_BACKOFF_MS);
                 continue;
             }
-            const claimed = await this.store.claim({
-                queues: this.queues,
-                workerId: this.workerId,
-                leaseMs,
-                limit: Math.min(batch, free),
-            });
             if (claimed.length === 0) {
-                await this.sleepOrStop(pollMs);
+                await this.idle(pollMs);
                 continue;
             }
             for (const task of claimed) {
@@ -113,16 +184,21 @@ export class Worker {
                 running.add(p);
             }
         }
-        await Promise.all([...running]);
     }
     /** 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. */
     async serve(opts = {}) {
+        // Signals are installed here rather than in run(): serve() is the entry point
+        // that owns the process. run()/background() embed the worker in someone
+        // else's process, where a leftover listener suppresses Node's default Ctrl-C
+        // handling for the host long after the worker is done.
+        const removeSignalHandlers = this.installSignals();
         try {
             await this.run(opts);
         }
         finally {
+            removeSignalHandlers();
             await this.closeIfOwned();
         }
     }
@@ -138,13 +214,18 @@ export class Worker {
             await this.closeIfOwned();
         }
     }
+    /**
+     * 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.)
+     */
     async execute(task, leaseMs) {
         const ctx = new TaskContext(this.store, task, this.workerId, leaseMs);
         const hb = this.startHeartbeat(ctx, leaseMs);
         try {
             const handler = this.handlers.get(task.name);
             if (!handler) {
-                await this.safeFail(task.id, errorEnvelope({
+                await this.safeFail(task, errorEnvelope({
                     type: "NoHandler",
                     code: "no_handler",
                     message: `no handler registered for ${task.name}`,
@@ -154,16 +235,22 @@ export class Worker {
             }
             let result;
             try {
-                result = await handler(ctx, task.payload);
+                result = await this.attempt(handler, ctx, task);
             }
             catch (err) {
                 if (err instanceof LostLease)
                     return;
+                if (err instanceof AttemptTimeout) {
+                    // Recorded as a retryable failure, so backoff / maxAttempts /
+                    // cancel-wins all apply exactly as for a thrown error.
+                    await this.safeFail(task, timeoutEnvelope(task.name, err.maxRunMs), true);
+                    return;
+                }
                 if (err instanceof TaskError) {
-                    await this.safeFail(task.id, err.envelope(), err.retryable);
+                    await this.safeFail(task, err.envelope(), err.retryable);
                 }
                 else {
-                    await this.safeFail(task.id, exceptionEnvelope(err), true);
+                    await this.safeFail(task, exceptionEnvelope(err), true);
                 }
                 return;
             }
@@ -173,20 +260,68 @@ export class Worker {
                 await this.store.complete({ taskId: task.id, workerId: this.workerId, result });
             }
             catch (err) {
-                if (err instanceof LostLease)
+                if (err instanceof LostLease) {
+                    ctx.markLeaseLost();
                     return;
+                }
+                if (err instanceof SerializationError) {
+                    // The handler succeeded but its return value can't cross the JSON
+                    // protocol (BigInt, non-finite number, circular). Deterministic, so
+                    // fail fast and permanently — the alternative is sitting `running`
+                    // until lease expiry redelivers a task that fails the same way every
+                    // attempt.
+                    await this.safeFail(task, errorEnvelope({
+                        type: "SerializationError",
+                        code: "unserializable_result",
+                        message: `handler result is not JSON-serializable: ${err.message}`,
+                        retryable: false,
+                    }), false);
+                    return;
+                }
                 throw err;
             }
         }
+        catch (err) {
+            this.report(err, { phase: "execute", taskId: task.id });
+        }
         finally {
             hb.cancel();
             await hb.done;
         }
     }
+    /**
+     * 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.
+     */
+    async attempt(handler, ctx, task) {
+        const maxRunMs = this.opts.maxRunMs;
+        if (maxRunMs == null)
+            return handler(ctx, task.payload);
+        // As a real promise: the race needs one (a handler may return a plain
+        // value), and the timeout path .catch()es it.
+        const run = (async () => handler(ctx, task.payload))();
+        let timer;
+        const winner = await Promise.race([
+            run,
+            new Promise((r) => (timer = setTimeout(() => r(TIMED_OUT), maxRunMs))),
+        ]).finally(() => clearTimeout(timer));
+        if (winner !== TIMED_OUT)
+            return winner;
+        ctx.markLeaseLost();
+        // The zombie may still reject later; that must not become an unhandled
+        // rejection — its outcome was already decided to be handler_timeout.
+        run.catch(() => { });
+        throw new AttemptTimeout(maxRunMs);
+    }
     startHeartbeat(ctx, leaseMs) {
         let active = true;
         let wake = null;
-        const interval = this.opts.heartbeatIntervalMs ?? Math.max(1_000, Math.floor(leaseMs / 3));
+        // lease/3 gives two beats of slack; the floor only matters for sub-150ms leases.
+        const interval = this.opts.heartbeatIntervalMs ?? Math.max(50, Math.floor(leaseMs / 3));
         const done = (async () => {
             while (active) {
                 // Cancellable sleep: cancel() resolves this immediately and clears the
@@ -205,8 +340,10 @@ export class Worker {
                     await ctx.heartbeat();
                 }
                 catch (err) {
+                    // ctx.heartbeat() already flagged the lease as lost for the handler.
                     if (err instanceof LostLease)
                         break;
+                    this.report(err, { phase: "execute", taskId: ctx.taskId });
                 }
             }
         })();
@@ -219,34 +356,57 @@ export class Worker {
             done,
         };
     }
-    async safeFail(taskId, envelope, retryable) {
+    async safeFail(task, envelope, retryable) {
+        const delayMs = retryable
+            ? retryDelayMs(task.attempt, this.opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS, this.opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS)
+            : 0;
         try {
-            await this.store.fail({ taskId, workerId: this.workerId, error: envelope, retryable });
+            await this.store.fail({
+                taskId: task.id,
+                workerId: this.workerId,
+                error: envelope,
+                retryable,
+                delayMs,
+            });
         }
         catch (err) {
             if (!(err instanceof LostLease))
                 throw err;
         }
     }
+    /**
+     * 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.
+     */
+    idle(ms) {
+        return Promise.race([this.sleepOrStop(ms), this.store.claimWake(this.queues, ms)]);
+    }
     sleepOrStop(ms) {
         if (this.stopped)
             return Promise.resolve();
-        return new Promise((resolve) => {
-            let done = false;
-            const finish = () => {
-                if (done)
-                    return;
-                done = true;
-                clearTimeout(timer);
-                resolve();
-            };
-            const timer = setTimeout(finish, ms);
-            this.stopResolvers.push(finish);
-        });
+        let timer;
+        const nap = new Promise((r) => (timer = setTimeout(r, ms)));
+        // Clear the timer whichever side wins, so a stop is never followed by a
+        // leftover poll timer holding the process open.
+        return Promise.race([nap, this.stopped$]).finally(() => clearTimeout(timer));
     }
+    /** Take SIGINT/SIGTERM for the duration of serve(). Returns the undo. */
     installSignals() {
-        const handler = () => this.stop();
-        process.once("SIGINT", handler);
-        process.once("SIGTERM", handler);
+        const remove = () => {
+            process.off("SIGINT", handler);
+            process.off("SIGTERM", handler);
+        };
+        const handler = () => {
+            // Stand down after the first signal, so a second Ctrl-C reaches Node's
+            // default and kills a worker that will not drain. `once` would only drop
+            // whichever signal fired and leave the other suppressing the default.
+            remove();
+            this.stop();
+        };
+        process.on("SIGINT", handler);
+        process.on("SIGTERM", handler);
+        return remove;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",
@@ -33,6 +33,7 @@
   "files": ["dist", "src"],
   "engines": { "node": ">=20" },
   "scripts": {
+    "bench": "tsx bench/run.ts",
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
@@ -40,13 +41,19 @@
   "dependencies": {
     "better-sqlite3": "^11.3.0"
   },
-  "optionalDependencies": {
+  "peerDependencies": {
     "pg": "^8.13.0"
   },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
     "@types/node": "^22.7.0",
     "@types/pg": "^8.11.10",
+    "pg": "^8.13.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/src/client.ts

@@ -1,8 +1,8 @@
 import { TaskCanceled, TaskFailed } from "./errors.js";
-import { isFailed, isSucceeded, type Task } from "./models.js";
+import { isFailed, isSucceeded, type Task, type TaskStatus } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
-import type { ListInput, SubmitInput, TaskStore } from "./store/base.js";
+import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
 import { pollWait } from "./wait.js";
 
@@ -72,6 +72,20 @@ export class CairnQ {
     return this._store.retryByKey(key, opts);
   }
 
+  /** 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`. */
+  purge(input?: PurgeInput): Promise<string[]> {
+    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. */
+  stats(): Promise<Record<string, Record<TaskStatus, number>>> {
+    return this._store.stats();
+  }
+
   wait(
     taskId: string,
     opts: { timeoutMs?: number; pollMs?: number } = {},

package/src/context.ts

@@ -1,3 +1,4 @@
+import { LostLease } from "./errors.js";
 import { cancelRequested, type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
@@ -6,6 +7,12 @@ import { pollWait } from "./wait.js";
 
 /** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
 export class TaskContext {
+  private readonly abort = new AbortController();
+  private leaseLost = false;
+  // Cancellation is monotonic: once the DB has told us a cancel was requested it
+  // can't be taken back, so canceled() can answer from this without a re-read.
+  private cancelSeen = false;
+
   constructor(
     private readonly store: TaskStore,
     private readonly task: Task,
@@ -38,28 +45,78 @@ export class TaskContext {
     return this.task.payload;
   }
 
+  /**
+   * True once this worker has lost the task's lease — it expired and another
+   * worker reclaimed it. Nothing this handler writes will be recorded any more
+   * and the task is already running elsewhere, so a long handler should check
+   * this (or `signal`) and bail out instead of continuing to do side effects.
+   */
+  get lostLease(): boolean {
+    return this.leaseLost;
+  }
+
+  /** Aborts when the lease is lost. Pass it to fetch / any AbortSignal-aware API. */
+  get signal(): AbortSignal {
+    return this.abort.signal;
+  }
+
+  /** @internal Called by the worker when an owned write reports a lost lease. */
+  markLeaseLost(): void {
+    if (this.leaseLost) return;
+    this.leaseLost = true;
+    this.abort.abort(new LostLease(this.task.id));
+  }
+
+  // Every owned write returns the current row, so cancellation and lease loss
+  // ride along on writes the handler was making anyway.
+  private observe(task: Task): Task {
+    if (cancelRequested(task)) this.cancelSeen = true;
+    return task;
+  }
+
+  private async owned(write: () => Promise<Task>): Promise<Task> {
+    // Short-circuit once the lease is known lost: nothing this context writes
+    // may be recorded any more. 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);
+    try {
+      return this.observe(await write());
+    } catch (err) {
+      if (err instanceof LostLease) this.markLeaseLost();
+      throw err;
+    }
+  }
+
   async progress(value: number | null, message: string | null = null): Promise<Task> {
-    return this.store.progress({
-      taskId: this.task.id,
-      workerId: this.workerId,
-      progress: value,
-      message,
-    });
+    return this.owned(() =>
+      this.store.progress({
+        taskId: this.task.id,
+        workerId: this.workerId,
+        progress: value,
+        message,
+      }),
+    );
   }
 
   async heartbeat(): Promise<Task> {
-    return this.store.heartbeat({
-      taskId: this.task.id,
-      workerId: this.workerId,
-      leaseMs: this.leaseMs,
-    });
+    return this.owned(() =>
+      this.store.heartbeat({
+        taskId: this.task.id,
+        workerId: this.workerId,
+        leaseMs: this.leaseMs,
+      }),
+    );
   }
 
-  /** Cooperative cancel check. */
+  /** Cooperative cancel check. Free once a heartbeat has already seen the flag. */
   async canceled(): Promise<boolean> {
+    if (this.cancelSeen) return true;
     const t = await this.store.get(this.task.id);
     if (!t) return true;
-    return cancelRequested(t) || t.status === "canceled";
+    if (cancelRequested(t)) this.cancelSeen = true;
+    return this.cancelSeen || t.status === "canceled";
   }
 
   /** Submit a child task; parent/root/correlation are wired automatically. */

package/src/errors.ts

@@ -1,3 +1,6 @@
+import { nowMs } from "./ids.js";
+import { cancelRequested, isQueued, type Task } from "./models.js";
+
 /** The single shape of the JSON error envelope (see PROTOCOL.md). Everything that
  * records an error — a handler exception, a missing handler, lease expiry, a thrown
  * TaskError — builds it here, so the contract's fields live in one place. */
@@ -17,7 +20,15 @@ export function errorEnvelope(e: {
   };
 }
 
-export class CairnQError extends Error {}
+export class CairnQError extends Error {
+  constructor(message?: string) {
+    super(message);
+    // Subclasses each set their own; without this a bare CairnQError reports
+    // "Error", and `err.name` is how callers (and the conformance runner) tell
+    // one apart from another.
+    this.name = "CairnQError";
+  }
+}
 
 export class AlreadyExists extends CairnQError {
   constructor(public key: string) {
@@ -26,11 +37,44 @@ export class AlreadyExists extends CairnQError {
   }
 }
 
-/** wait/call did not reach a terminal status in time. The task keeps running. */
+/** One line of "why hasn't this finished" from the last snapshot wait()
+ * observed. No worker running, no handler for the name, wrong queue, and two
+ * processes on different database files all look identical from the API side —
+ * queued, never claimed — so that case names the likely causes. */
+function timeoutDetail(task: Task | null): string {
+  if (!task) return "task not found — wrong database file, or already purged?";
+  if (isQueued(task)) {
+    const delayMs = task.run_at_ms - nowMs();
+    if (task.attempt === 0 && delayMs <= 0) {
+      return (
+        `never claimed by a worker — is a worker running with a handler for ` +
+        `'${task.name}' on queue '${task.queue}', against this same database?`
+      );
+    }
+    const next = delayMs > 0 ? `, next run in ~${delayMs}ms` : "";
+    return `still queued (attempt ${task.attempt}/${task.max_attempts})${next}`;
+  }
+  if (cancelRequested(task)) return "cancel requested, waiting for the handler to observe it";
+  return `still running (attempt ${task.attempt}/${task.max_attempts})`;
+}
+
+/** wait/call did not reach a terminal status in time. The task keeps running.
+ * `task` is the last snapshot wait() observed (null if get() found nothing), and
+ * the message says what state it was stuck in — a queued-never-claimed task is
+ * the classic first-run failure (no worker, no handler, wrong queue or file). */
 export class TaskTimeout extends CairnQError {
-  constructor(public taskId: string) {
-    super(`task ${taskId} did not finish in time`);
+  readonly task: Task | null;
+  constructor(
+    public taskId: string,
+    opts: { timeoutMs?: number; task?: Task | null } = {},
+  ) {
+    super(
+      opts.timeoutMs == null
+        ? `task ${taskId} did not finish in time`
+        : `task ${taskId} did not finish within ${opts.timeoutMs}ms: ${timeoutDetail(opts.task ?? null)}`,
+    );
     this.name = "TaskTimeout";
+    this.task = opts.task ?? null;
   }
 }
 
@@ -81,6 +125,17 @@ export class ProtocolVersionMismatch extends CairnQError {
   }
 }
 
+/** 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. */
+export class SerializationError extends CairnQError {
+  constructor(message: string) {
+    super(message);
+    this.name = "SerializationError";
+  }
+}
+
 /** Throw inside a handler to control how the failure is recorded. Defaults to
  * non-retryable so deterministic errors fail fast instead of burning retries.
  * Any other thrown value is treated as retryable. */

package/src/index.ts

@@ -7,7 +7,8 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
-export type { ListInput, SubmitInput, TaskStore, Conflict } from "./store/base.js";
+export { TaskStore } from "./store/base.js";
+export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
 export type { Task, TaskStatus } from "./models.js";
 export {
   STATUSES,
@@ -28,4 +29,5 @@ export {
   TaskError,
   LostLease,
   ProtocolVersionMismatch,
+  SerializationError,
 } from "./errors.js";