cairnq 0.1.0 → 0.2.0

package/dist/context.d.ts

@@ -8,6 +8,9 @@ export declare class TaskContext {
     private readonly task;
     readonly workerId: string;
     private readonly leaseMs;
+    private readonly abort;
+    private leaseLost;
+    private cancelSeen;
     constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number);
     get taskId(): string;
     get name(): string;
@@ -17,9 +20,22 @@ export declare class TaskContext {
     get rootId(): string | null;
     get correlationId(): string | null;
     get payload(): any;
+    /**
+     * 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;
+    /** Aborts when the lease is lost. Pass it to fetch / any AbortSignal-aware API. */
+    get signal(): AbortSignal;
+    /** @internal Called by the worker when an owned write reports a lost lease. */
+    markLeaseLost(): void;
+    private observe;
+    private owned;
     progress(value: number | null, message?: string | null): Promise<Task>;
     heartbeat(): Promise<Task>;
-    /** Cooperative cancel check. */
+    /** Cooperative cancel check. Free once a heartbeat has already seen the flag. */
     canceled(): Promise<boolean>;
     /** Submit a child task; parent/root/correlation are wired automatically. */
     submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;

package/dist/context.js

@@ -1,3 +1,4 @@
+import { LostLease } from "./errors.js";
 import { cancelRequested } from "./models.js";
 import { taskName } from "./task.js";
 import { pollWait } from "./wait.js";
@@ -7,6 +8,11 @@ export class TaskContext {
     task;
     workerId;
     leaseMs;
+    abort = new AbortController();
+    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.
+    cancelSeen = false;
     constructor(store, task, workerId, leaseMs) {
         this.store = store;
         this.task = task;
@@ -37,27 +43,75 @@ export class TaskContext {
     get payload() {
         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() {
+        return this.leaseLost;
+    }
+    /** Aborts when the lease is lost. Pass it to fetch / any AbortSignal-aware API. */
+    get signal() {
+        return this.abort.signal;
+    }
+    /** @internal Called by the worker when an owned write reports a lost lease. */
+    markLeaseLost() {
+        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.
+    observe(task) {
+        if (cancelRequested(task))
+            this.cancelSeen = true;
+        return task;
+    }
+    async owned(write) {
+        // 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, message = null) {
-        return this.store.progress({
+        return this.owned(() => this.store.progress({
             taskId: this.task.id,
             workerId: this.workerId,
             progress: value,
             message,
-        });
+        }));
     }
     async heartbeat() {
-        return this.store.heartbeat({
+        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() {
+        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";
     }
     async submit(task, payload, opts = {}) {
         return this.store.submit({

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { 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. */
@@ -9,15 +10,23 @@ export declare function errorEnvelope(e: {
     details?: Record<string, unknown>;
 }): Record<string, unknown>;
 export declare class CairnQError extends Error {
+    constructor(message?: string);
 }
 export declare class AlreadyExists extends CairnQError {
     key: string;
     constructor(key: string);
 }
-/** wait/call did not reach a terminal status in time. The task keeps running. */
+/** 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 declare class TaskTimeout extends CairnQError {
     taskId: string;
-    constructor(taskId: string);
+    readonly task: Task | null;
+    constructor(taskId: string, opts?: {
+        timeoutMs?: number;
+        task?: Task | null;
+    });
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
  * error — read `e.code` / `e.message` / `e.retryable` / `e.details` instead of
@@ -42,6 +51,13 @@ export declare class LostLease extends CairnQError {
 export declare class ProtocolVersionMismatch 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
+ * `unserializable_result` failure. The Python SDK raises the same named error. */
+export declare class SerializationError extends CairnQError {
+    constructor(message: string);
+}
 /** 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/dist/errors.js

@@ -1,3 +1,5 @@
+import { nowMs } from "./ids.js";
+import { cancelRequested, isQueued } 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. */
@@ -11,6 +13,13 @@ export function errorEnvelope(e) {
     };
 }
 export class CairnQError extends Error {
+    constructor(message) {
+        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 {
     key;
@@ -20,13 +29,40 @@ export class AlreadyExists extends CairnQError {
         this.name = "AlreadyExists";
     }
 }
-/** 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) {
+    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 {
     taskId;
-    constructor(taskId) {
-        super(`task ${taskId} did not finish in time`);
+    task;
+    constructor(taskId, opts = {}) {
+        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.taskId = taskId;
         this.name = "TaskTimeout";
+        this.task = opts.task ?? null;
     }
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
@@ -72,6 +108,16 @@ export class ProtocolVersionMismatch extends CairnQError {
         this.name = "ProtocolVersionMismatch";
     }
 }
+/** 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) {
+        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/dist/index.d.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, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, } from "./errors.js";
+export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/index.js

@@ -4,5 +4,6 @@ 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 { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, } from "./errors.js";
+export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/sql.js

@@ -1,19 +1,23 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-// Locate the shared cairnq-protocol dir. Resolution: $CAIRNQ_PROTOCOL_DIR ->
-// vendored `_protocol/` next to this module -> walk up to `cairnq-protocol/`
-// (monorepo dev). Both SDKs load the SAME .sql strings (zero-drift guarantee).
-// The dir is laid out per-dialect (sql/<dialect>/*.sql, migrations/<dialect>/*.sql)
-// so a second backend (Postgres) slots in beside sqlite; `dialect` picks the subtree.
+// Locate the shared cairnq-protocol dir. Resolution: $CAIRNQ_PROTOCOL_DIR -> walk
+// up to `cairnq-protocol/` (monorepo dev) -> vendored `_protocol/` next to this
+// module (written at publish time). Both SDKs load the SAME .sql strings
+// (zero-drift guarantee). The dir is laid out per-dialect (sql/<dialect>/*.sql,
+// migrations/<dialect>/*.sql) so a second backend (Postgres) slots in beside
+// sqlite; `dialect` picks the subtree.
+//
+// The source tree wins over the vendored copy on purpose: vendoring is a publish
+// step that also runs locally, and a stale `_protocol/` shadowing the canonical
+// SQL means edits to cairnq-protocol/ are silently not under test. An installed
+// package has no repo above it, so it falls through to the vendored copy.
 export function findProtocolRoot() {
     const env = process.env.CAIRNQ_PROTOCOL_DIR;
     if (env)
         return env;
-    let dir = dirname(fileURLToPath(import.meta.url));
-    const vendored = join(dir, "_protocol");
-    if (existsSync(join(vendored, "sql")))
-        return vendored;
+    const start = dirname(fileURLToPath(import.meta.url));
+    let dir = start;
     for (let i = 0; i < 10; i++) {
         const candidate = join(dir, "cairnq-protocol");
         if (existsSync(join(candidate, "sql")))
@@ -23,6 +27,9 @@ export function findProtocolRoot() {
             break;
         dir = parent;
     }
+    const vendored = join(start, "_protocol");
+    if (existsSync(join(vendored, "sql")))
+        return vendored;
     throw new Error("cannot locate cairnq-protocol; set CAIRNQ_PROTOCOL_DIR");
 }
 export function loadStatements(dialect = "sqlite", root = findProtocolRoot()) {

package/dist/store/base.d.ts

@@ -1,5 +1,17 @@
-import type { Task } from "../models.js";
-export type Conflict = "reuse" | "reject" | "replace";
+import { type Task, type TaskStatus } from "../models.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). */
+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
+ * checks it here so the constant can't fork per store. */
+export declare function checkProtocolVersion(version: number): void;
+declare const CONFLICTS: readonly ["reuse", "reject", "replace"];
+export type Conflict = (typeof CONFLICTS)[number];
 export interface SubmitInput {
     name: string;
     payload: unknown;
@@ -15,7 +27,7 @@ export interface SubmitInput {
     runAtDelayMs?: number;
 }
 export interface ListInput {
-    status?: string | null;
+    status?: TaskStatus | null;
     queue?: string | null;
     name?: string | null;
     rootId?: string | null;
@@ -23,28 +35,113 @@ export interface ListInput {
     limit?: number;
     offset?: number;
 }
-/** The storage seam. SQLiteStore is the only MVP implementation. */
-export interface TaskStore {
-    connect(): Promise<void>;
-    close(): Promise<void>;
-    protocolVersion(): Promise<number>;
+export interface PurgeInput {
+    olderThanMs?: number;
+    limit?: number;
+}
+export type Params = Record<string, unknown>;
+/** Runs one named protocol statement and returns its rows. */
+export type Fetch = (name: string, params: Params) => Promise<any[]>;
+export declare const LEASE_EXPIRED_ERROR_JSON: string;
+/** Strips SQL line comments, so a `:name` in a header comment isn't a parameter. */
+export declare const COMMENT: RegExp;
+/** A `:name` placeholder. The lookbehind spares Postgres `::type` casts. */
+export declare const NAMED: RegExp;
+/**
+ * The parameter names a statement binds, in first-appearance order.
+ *
+ * Callers pass a superset of parameters and each dialect takes what its own SQL
+ * asks for — that is what lets one call site serve both dialects even though e.g.
+ * SQLite binds `:lease_until_ms` where Postgres binds `:lease_ms`. This is the one
+ * place that decides what counts as a parameter; both dialects' binding goes
+ * through it.
+ */
+export declare function statementParams(sql: string): readonly string[];
+/**
+ * The storage seam.
+ *
+ * A backend supplies three things: how to run one protocol statement, how to run
+ * several inside a transaction, and how its dialect binds parameters. Everything
+ * above that — the submit conflict branches, the *_by_key lookups, the
+ * recover-then-claim sequence, the ownership-checked writes — lives here once,
+ * because those are protocol decisions rather than storage decisions. Keeping
+ * 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.
+ */
+export declare abstract class TaskStore {
+    abstract connect(): Promise<void>;
+    abstract close(): Promise<void>;
+    abstract protocolVersion(): Promise<number>;
+    /** Run one protocol statement outside a transaction, connecting if needed. */
+    protected abstract fetch(name: string, params: Params): Promise<any[]>;
+    /** Run several statements atomically; `fn` receives a Fetch bound to the txn. */
+    protected abstract tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
+    /**
+     * 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
+     * writers, so it just says yes.
+     */
+    protected hasClaimableWork(_params: Params): Promise<boolean>;
+    /** Resolves when a task may have become claimable on one of `queues`. The
+     * timer is unref'd: the worker races this against its own stop-aware, ref'd
+     * sleep, so it must neither hold the process open nor need clearing. */
+    claimWake(_queues: string[], timeoutMs: number): Promise<void>;
+    /** 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>;
+    /**
+     * 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;
     submit(input: SubmitInput): Promise<Task>;
     get(taskId: string): Promise<Task | null>;
     getByKey(key: string): Promise<Task | null>;
     list(input?: ListInput): Promise<Task[]>;
     cancel(taskId: string): Promise<Task | null>;
-    cancelByKey(key: string): Promise<Task | null>;
     retry(taskId: string, opts?: {
         resetAttempt?: boolean;
     }): Promise<Task | null>;
+    cancelByKey(key: string): Promise<Task | null>;
     retryByKey(key: string, opts?: {
         resetAttempt?: boolean;
     }): Promise<Task | null>;
+    /**
+     * Resolve a key to the task it currently points at, then act on that task —
+     * under the key's lock, so a concurrent `replace` can't repoint the key
+     * between the lookup and the write (the transaction alone is not enough on
+     * Postgres; see lock_key.sql).
+     */
+    private byKey;
+    /**
+     * Delete terminal tasks that completed more than `olderThanMs` ago and return
+     * their ids. Nothing else removes rows, so a long-lived database needs this
+     * called periodically. Bounded by `limit` to keep each sweep a short write;
+     * call it in a loop until it returns fewer than `limit`.
+     */
+    purge(input?: PurgeInput): Promise<string[]>;
+    /**
+     * Task counts per queue, keyed by status and zero-filled across all statuses —
+     * `(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.
+     */
+    stats(): Promise<Record<string, Record<TaskStatus, 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.
+     * Queues alone do not partition work, so without it a worker claims a task it
+     * cannot run and fails it permanently. Undefined means no filter; an empty
+     * array claims nothing.
+     */
     claim(input: {
         queues: string[];
         workerId: string;
         leaseMs?: number;
         limit?: number;
+        names?: string[];
     }): Promise<Task[]>;
     heartbeat(input: {
         taskId: string;
@@ -75,3 +172,4 @@ export interface TaskStore {
         delayMs?: number;
     }): Promise<Task>;
 }
+export {};