cairnq 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -1,24 +1,19 @@
 export { CairnQ } from "./client.js";
 export type { CallOptions, ClientOptions, SubmitOptions, WaitOptions } from "./client.js";
-export { QueueDepthGate } from "./backpressure.js";
-export type { BackpressureOptions, QueueDepthLimit } from "./backpressure.js";
-export { RetentionSweeper } from "./retention.js";
 export type { RetentionCutoffs, RetentionOptions, RetentionRule } from "./retention.js";
 export { Worker } from "./worker.js";
 export type { BatchHandler, Handler, TypedHandler, WorkerOptions } from "./worker.js";
 export { TaskContext } from "./context.js";
-export type { TaskContextOptions } from "./context.js";
 export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { TaskStore } from "./store/base.js";
+export type { Conflict, ListInput, PurgeInput, SubmitInput } from "./store/base.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, WatchOptions, WatchSignal, } from "./store/base.js";
-export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
+export { STATUSES, isTerminalStatus } from "./models.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, SchemaMismatch, UnsupportedBackend, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SchemaMismatch, UnsupportedBackend, SerializationError, StoreClosed, } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/dist/index.js

@@ -1,14 +1,11 @@
 export { CairnQ } from "./client.js";
-export { QueueDepthGate } from "./backpressure.js";
-export { RetentionSweeper } from "./retention.js";
 export { Worker } from "./worker.js";
 export { TaskContext } from "./context.js";
 export { defineTask } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { TaskStore } from "./store/base.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, SchemaMismatch, UnsupportedBackend, SerializationError, } from "./errors.js";
+export { STATUSES, isTerminalStatus } from "./models.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SchemaMismatch, UnsupportedBackend, SerializationError, StoreClosed, } from "./errors.js";

package/dist/models.d.ts

@@ -39,7 +39,20 @@ export declare function isTerminalStatus(status: TaskStatus): status is Terminal
 /** Map a probe row (see get_status.sql) to a TaskRef — the ref twin of
  * rowToTask, so the row shape stays models' knowledge alone. */
 export declare function rowToRef(row: Record<string, unknown>): TaskRef;
-export declare function rowToTask(row: Record<string, unknown>): Task;
+/**
+ * Map a row to a Task.
+ *
+ * `jsonIsText` says how this driver delivers a JSON column, and it has to be
+ * told rather than inferred. SQLite (TEXT) hands back the JSON text to parse; a
+ * jsonb-aware driver (`pg`) hands back an already-decoded value. Those two are
+ * distinguishable for an object or an array — but not for a JSON *string*, where
+ * the text form (`"hello"`, quotes included) and the decoded form (`hello`) are
+ * both, simply, strings. Guessing from the value used to double-parse the
+ * decoded one: `"s3://…"` threw a SyntaxError, and `"42"` came back as the
+ * NUMBER 42 — silent corruption for any payload or result that is a top-level
+ * string. The store knows which driver it has; models does not, so it asks.
+ */
+export declare function rowToTask(row: Record<string, unknown>, jsonIsText: boolean): Task;
 /** Accepts anything carrying a status — a Task or a TaskRef probe. */
 export declare function isTerminal(task: Pick<Task, "status">): boolean;
 export declare function cancelRequested(task: Task): boolean;

package/dist/models.js

@@ -28,14 +28,26 @@ export function isTerminalStatus(status) {
 export function rowToRef(row) {
     return { id: row.id, status: row.status };
 }
-export function rowToTask(row) {
+/**
+ * Map a row to a Task.
+ *
+ * `jsonIsText` says how this driver delivers a JSON column, and it has to be
+ * told rather than inferred. SQLite (TEXT) hands back the JSON text to parse; a
+ * jsonb-aware driver (`pg`) hands back an already-decoded value. Those two are
+ * distinguishable for an object or an array — but not for a JSON *string*, where
+ * the text form (`"hello"`, quotes included) and the decoded form (`hello`) are
+ * both, simply, strings. Guessing from the value used to double-parse the
+ * decoded one: `"s3://…"` threw a SyntaxError, and `"42"` came back as the
+ * NUMBER 42 — silent corruption for any payload or result that is a top-level
+ * string. The store knows which driver it has; models does not, so it asks.
+ */
+export function rowToTask(row, jsonIsText) {
     const t = { ...row };
     for (const col of JSON_COLUMNS) {
         const v = row[col];
-        // The driver decides a JSON column's wire form: SQLite (TEXT) hands back a
-        // string to parse; a jsonb-aware driver (Postgres `pg`) hands back an
-        // already-decoded object. Parse only a string — never assume one backend.
-        t[col] = typeof v === "string" ? JSON.parse(v) : (v ?? null);
+        // A SQL NULL and a decoded JSON `null` both arrive as null and both mean
+        // "no value"; only a real text form is parsed.
+        t[col] = v == null ? null : jsonIsText ? JSON.parse(v) : v;
     }
     for (const col of MS_COLUMNS) {
         const v = row[col];

package/dist/retention.d.ts

@@ -108,7 +108,18 @@ export declare class RetentionSweeper {
      * demand — after a backfill, or from a maintenance command.
      */
     sweep(): Promise<number>;
-    /** Sleep, interruptible by stop(). Unref'd: retention is housekeeping, and a
-     * pending sweep must never be the reason a process refuses to exit. */
+    /**
+     * Sleep, interruptible by stop().
+     *
+     * `holdProcess` is the same distinction the store draws between `claimWake`
+     * and `taskDoneWake`: a wait nobody is awaiting must not hold the process
+     * open, and a wait somebody IS awaiting must. The scheduled loop's interval is
+     * the first — retention is housekeeping, and a pending sweep must never be the
+     * reason a process refuses to exit. `sweep()`'s between-batches yield is the
+     * second: its caller is awaiting the drain, and an unref'd timer there let
+     * Node decide the loop was idle and exit mid-drain, leaving that promise
+     * unsettled forever (a maintenance command that swept two rows of seven and
+     * exited 13). Python's twin never had this, `asyncio.sleep` having no unref.
+     */
     private sleep;
 }

package/dist/retention.js

@@ -86,9 +86,10 @@ export class RetentionSweeper {
         if (this.active)
             return;
         this.active = true;
-        this.stopping = false;
-        // A stopped sweeper can be started again, and the old signal is spent.
-        this.arm();
+        // No reset here: stop() clears `stopping` and re-arms the signal before it
+        // returns, and the constructor arms the first one — so a sweeper reaching
+        // this line always already has a fresh signal and a clear flag. (The Python
+        // twin has never had a reset here, for the same reason.)
         this.loop = this.run();
     }
     /** Mint a fresh stop signal. */
@@ -102,6 +103,15 @@ export class RetentionSweeper {
         this.wake();
         await this.loop;
         this.loop = null;
+        // Cleared, and the signal re-armed, now that the loop is provably gone.
+        // `stopping` is how a sweep in flight cuts itself short, so leaving it set
+        // would silently truncate a later on-demand sweep() — a supported call — to
+        // its first batch. Leaving the signal spent would be the subtler half of the
+        // same bug: that sweep's between-batches yield would resolve on a microtask
+        // instead of handing the event loop back, so a long drain would starve the
+        // submits and claims sharing this process — exactly what the yield is for.
+        this.stopping = false;
+        this.arm();
     }
     async run() {
         // Sleep first: a process that restarts often would otherwise purge on every
@@ -140,19 +150,31 @@ export class RetentionSweeper {
                 if (ids.length < this.limit)
                     break;
                 // Hand the loop back between batches: a large drain must not starve the
-                // submits and claims sharing this process.
-                await this.sleep(0);
+                // submits and claims sharing this process. Ref'd — see sleep().
+                await this.sleep(0, true);
             }
         }
         return deleted;
     }
-    /** Sleep, interruptible by stop(). Unref'd: retention is housekeeping, and a
-     * pending sweep must never be the reason a process refuses to exit. */
-    sleep(ms) {
+    /**
+     * Sleep, interruptible by stop().
+     *
+     * `holdProcess` is the same distinction the store draws between `claimWake`
+     * and `taskDoneWake`: a wait nobody is awaiting must not hold the process
+     * open, and a wait somebody IS awaiting must. The scheduled loop's interval is
+     * the first — retention is housekeeping, and a pending sweep must never be the
+     * reason a process refuses to exit. `sweep()`'s between-batches yield is the
+     * second: its caller is awaiting the drain, and an unref'd timer there let
+     * Node decide the loop was idle and exit mid-drain, leaving that promise
+     * unsettled forever (a maintenance command that swept two rows of seven and
+     * exited 13). Python's twin never had this, `asyncio.sleep` having no unref.
+     */
+    sleep(ms, holdProcess = false) {
         let timer;
         const nap = new Promise((resolve) => {
             timer = setTimeout(resolve, ms);
-            timer.unref?.();
+            if (!holdProcess)
+                timer.unref?.();
         });
         // Clear the timer whichever side wins, so a stop is never followed by a
         // leftover sweep timer.

package/dist/store/base.d.ts

@@ -2,10 +2,11 @@ import { type Task, type TaskRef, type TaskStatus } from "../models.js";
 import { type BackpressureOptions } from "../backpressure.js";
 /** Encode a value for a protocol JSON column, raising SerializationError on
  * anything JSON cannot represent. Refuses what JSON.stringify would silently
- * mangle into `null`: NaN/Infinity anywhere, undefined/function/symbol inside an
- * array, and a top-level undefined that disappears entirely — either way the
- * twin SDK reads back something other than what the caller meant (the Python
- * SDK rejects the same values, via allow_nan=False). */
+ * mangle: NaN/Infinity anywhere, undefined/function/symbol inside an array, a
+ * top-level undefined that disappears entirely, and the objects that would be
+ * written as an empty one (see emptiesItselfOut) — either way the twin SDK
+ * reads back something other than what the caller meant. The Python SDK rejects
+ * the same classes of value; see its dump_json. */
 export declare function dumpJson(value: unknown): string;
 /** Refuse to run against a store whose protocol major this SDK does not speak.
  * The supported major is a protocol fact, not a dialect one — every backend
@@ -28,7 +29,8 @@ export interface SubmitInput {
     parentId?: string | null;
     rootId?: string | null;
     correlationId?: string | null;
-    runAtDelayMs?: number;
+    /** Run no earlier than this many ms from now. */
+    delayMs?: number;
 }
 export interface ListInput {
     status?: TaskStatus | null;
@@ -109,32 +111,6 @@ 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;
@@ -167,25 +143,12 @@ export declare abstract class TaskStore {
      * `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;
     /**
      * Tell a store with a push channel which queues this process will wait on, so
      * it can buffer their notifications and ignore everyone else's. Optional: a
      * store without a push channel has nothing to buffer.
      */
     protected registerWakeable?(queues: string[]): 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 — the read-only
      * `claimable_probe`, which every dialect ships.
@@ -207,13 +170,31 @@ export declare abstract class TaskStore {
     /** Resolves when `taskId` may have gone terminal. Plain ref'd sleep —
      * pollWait awaits it directly, so it is what keeps the process alive. */
     taskDoneWake(_taskId: string, timeoutMs: number): Promise<void>;
+    /**
+     * Whether this store's driver hands JSON columns back as text.
+     *
+     * Declared by the store rather than sniffed per value, because for a JSON
+     * *string* the two wire forms are indistinguishable: the text form of
+     * `"hello"` and the decoded form of `"hello"` are both strings, and treating
+     * the decoded one as text parses it twice — `"s3://…"` threw, `"42"` came back
+     * as the number 42. See rowToTask.
+     *
+     * True is the SQLite answer and the safe default: its JSON columns are TEXT,
+     * always. PostgresStore replaces it with what its driver actually does, which
+     * it measures rather than assumes — an injected executor's driver is the
+     * application's choice, not cairnq's.
+     */
+    protected jsonIsText: boolean;
+    /** rowToTask, told this store's wire form. Every row in this class goes
+     * through here so no call site has to remember to pass it. */
+    private toTask;
     /**
      * 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.
      */
     private ownedWrite;
-    private static one;
+    private one;
     private static oneRef;
     /**
      * Bound how deep a queue may get before `submit` blocks. Off unless set.
@@ -260,7 +241,15 @@ export declare abstract class TaskStore {
      */
     purge(input?: PurgeInput): Promise<string[]>;
     /**
-     * Task counts per queue, keyed by status and zero-filled across all statuses —
+     * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
+     *
+     * The cheap half of backpressure: bounded at `maxDepth` index entries, so it
+     * stays cheap to ask on every enqueue. Use it directly to shed load or shape
+     * a producer; `QueueDepthGate` builds the blocking form on top.
+     */
+    queueDepth(queue: string, maxDepth: number): Promise<number>;
+    /**
+     * Task counts grouped by queue, keyed by status and zero-filled —
      * `(await stats()).default.queued` is the backlog of a queue. A queue appears
      * only while it has rows; terminal tasks keep counting until `purge` removes
      * them.
@@ -278,37 +267,6 @@ export declare abstract class TaskStore {
      * the point.
      */
     stats(queue?: string): 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.
-     *
-     * The cheap half of backpressure: bounded at `maxDepth` index entries, unlike
-     * `stats()`, which aggregates the whole table (terminal rows included) and so
-     * costs more the longer a database has been running. Use it directly to shed
-     * load or shape a producer; `QueueDepthGate` builds the blocking form on top.
-     */
-    queueDepth(queue: string, maxDepth: number): Promise<number>;
     /**
      * Take up to `limit` claimable tasks. `names` restricts the claim to task names
      * this caller can actually run — a worker passes its registered handlers.