cairnq 0.6.0 → 0.7.0

package/README.md

@@ -34,7 +34,9 @@ try {
 } catch (err) {
   if (err instanceof TaskFailed) log(err.code, err.message, err.retryable); // envelope fields
   else if (err instanceof TaskTimeout) {
-    /* err.taskId keeps running */
+    // The task keeps running — resume the wait instead of submitting again.
+    const result = await tasks.wait(err.taskId, { timeoutMs: 60_000 });
+    // …or tasks.waitByKey(key), from a process that never held the id.
   }
 }
 ```
@@ -72,8 +74,11 @@ const worker = Worker.sqlite("tasks.db", {
   onError: (err, info) => log.warn({ err, ...info }), // claims/writes the loop survived
 });
 
-// Nothing else deletes rows. Sweep terminal tasks on a schedule.
-await tasks.purge({ olderThanMs: 7 * 24 * 3600_000 });
+// Nothing else deletes rows, so give the client a retention policy — it sweeps
+// terminal tasks in bounded batches for as long as the handle is open.
+const tasks = CairnQ.sqlite("tasks.db", {
+  retention: { olderThanMs: 7 * 24 * 3600_000 },
+});
 ```
 
 A handler that does real side effects should bail out when it loses its lease —

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import type { BackpressureOptions } from "./backpressure.js";
+import { type RetentionOptions } from "./retention.js";
 import { type Task, type TaskStatus } from "./models.js";
 import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
@@ -9,10 +10,17 @@ export interface CallOptions extends SubmitOptions {
 }
 /** Options this handle configures on the store it wraps, rather than the
  * store's own constructor arguments. */
-export type ClientOptions = Partial<BackpressureOptions>;
+export type ClientOptions = Partial<BackpressureOptions> & {
+    /** Delete terminal tasks older than a cutoff, on a schedule, for as long as
+     * this handle is open. Off unless set — and off means rows accumulate forever,
+     * because nothing else in CairnQ removes them. */
+    retention?: RetentionOptions;
+};
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export declare class CairnQ {
     private readonly _store;
+    /** null unless `retention` was configured. */
+    private readonly sweeper;
     constructor(_store: TaskStore, opts?: ClientOptions);
     static sqlite(path: string, opts?: {
         busyTimeoutMs?: number;
@@ -24,6 +32,8 @@ export declare class CairnQ {
     } & ClientOptions): CairnQ;
     get store(): TaskStore;
     connect(): Promise<void>;
+    /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+     * store) and close the store. */
     close(): Promise<void>;
     /** Enqueue a task. With `maxQueueDepth` configured this blocks while the
      * target queue is at its limit, and raises QueueFull if it stays there for
@@ -55,13 +65,29 @@ 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>>>;
+    /** 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. */
     wait(taskId: string, opts?: {
         timeoutMs?: number;
         pollMs?: number;
     }): Promise<Task>;
+    /** Wait for whatever task the `key` currently points at — the cross-process
+     * form of picking a wait back up, when the id was never in hand or the process
+     * that held it is gone. Re-resolves the key on each poll, so a `replace`
+     * landing mid-wait moves the wait onto the new task, and a key with no task
+     * yet is waited for rather than rejected. */
+    waitByKey(key: string, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Task>;
     /** submit + wait. Resolves with the result on success; rejects with
      * TaskFailed / TaskCanceled / TaskTimeout otherwise. Pass a TaskDef and the
-     * resolved value is typed as its Result. */
+     * resolved value is typed as its Result.
+     *
+     * `waitTimeoutMs` bounds the wait, not the task: on timeout the task runs on,
+     * and `wait(err.taskId)` — or `waitByKey`, from a process that only has the
+     * key — resumes the wait rather than starting the work over. */
     call(name: string, payload?: unknown, opts?: CallOptions): Promise<unknown>;
     call<P, R>(task: TaskDef<P, R>, payload?: P, opts?: CallOptions): Promise<R>;
 }

package/dist/client.js

@@ -1,12 +1,15 @@
+import { RetentionSweeper } from "./retention.js";
 import { TaskCanceled, TaskFailed } from "./errors.js";
 import { isFailed, isSucceeded } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
 import { taskName } from "./task.js";
-import { pollWait } from "./wait.js";
+import { pollWait, pollWaitByKey } from "./wait.js";
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export class CairnQ {
     _store;
+    /** null unless `retention` was configured. */
+    sweeper;
     constructor(_store, opts = {}) {
         this._store = _store;
         // Installed on the store, not held here: every submit path goes through the
@@ -14,6 +17,13 @@ export class CairnQ {
         if (opts.maxQueueDepth != null) {
             _store.useBackpressure(opts);
         }
+        // Retention is the opposite case: it belongs to the handle, because a worker
+        // sharing the store must not also be deleting rows behind the API's back.
+        // Started here rather than in connect(), which is optional — every other
+        // path connects lazily, and retention that silently depends on an optional
+        // call is retention that silently does not happen.
+        this.sweeper = opts.retention ? new RetentionSweeper(_store, opts.retention) : null;
+        this.sweeper?.start();
     }
     static sqlite(path, opts = {}) {
         const { busyTimeoutMs, ...client } = opts;
@@ -31,8 +41,11 @@ export class CairnQ {
     connect() {
         return this._store.connect();
     }
-    close() {
-        return this._store.close();
+    /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+     * store) and close the store. */
+    async close() {
+        await this.sweeper?.stop();
+        await this._store.close();
     }
     submit(task, payload, opts = {}) {
         return this._store.submit({ name: taskName(task), payload, ...opts });
@@ -77,12 +90,26 @@ export class CairnQ {
     stats() {
         return this._store.stats();
     }
+    /** 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. */
     wait(taskId, opts = {}) {
         return pollWait(this._store, taskId, {
             timeoutMs: opts.timeoutMs ?? 30_000,
             pollMs: opts.pollMs,
         });
     }
+    /** Wait for whatever task the `key` currently points at — the cross-process
+     * form of picking a wait back up, when the id was never in hand or the process
+     * that held it is gone. Re-resolves the key on each poll, so a `replace`
+     * landing mid-wait moves the wait onto the new task, and a key with no task
+     * yet is waited for rather than rejected. */
+    waitByKey(key, opts = {}) {
+        return pollWaitByKey(this._store, key, {
+            timeoutMs: opts.timeoutMs ?? 30_000,
+            pollMs: opts.pollMs,
+        });
+    }
     async call(task, payload, opts = {}) {
         const { waitTimeoutMs = 30_000, pollMs, ...submit } = opts;
         const created = await this.submit(taskName(task), payload, submit);

package/dist/errors.d.ts

@@ -35,16 +35,24 @@ export declare class QueueFull extends CairnQError {
     waitedMs: number;
     constructor(queue: string, maxDepth: number, waitedMs: number);
 }
-/** 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). */
+/** wait/call did not reach a terminal status in time. The task keeps running, so
+ * `taskId` is the handle for picking the wait back up — `wait(err.taskId)`
+ * re-attaches to the same task from anywhere that can reach the store. `task` is
+ * the last snapshot wait() observed (null if the lookup 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).
+ *
+ * `key` is set when the wait watched a key rather than an id; `taskId` is then
+ * the task the key pointed at, or the key itself when it pointed at nothing —
+ * there was no id to report. */
 export declare class TaskTimeout extends CairnQError {
     taskId: string;
     readonly task: Task | null;
+    readonly key: string | null;
     constructor(taskId: string, opts?: {
         timeoutMs?: number;
         task?: Task | null;
+        key?: string | null;
     });
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
@@ -62,6 +70,27 @@ export declare class TaskCanceled extends CairnQError {
     taskId: string;
     constructor(taskId: string);
 }
+/**
+ * A heartbeat beat came back later than its own interval allowed.
+ *
+ * The heartbeat shares the event loop with the handlers whose leases it renews,
+ * so a handler that blocks the loop stops the renewal with it: the lease expires,
+ * the task is recovered and redelivered, and a second worker starts computing
+ * what the first is still computing — one task, billed twice, with no error
+ * anywhere. Nothing inside the blocked handler can observe that, which is why it
+ * is reported through `onError` alongside the other things the run loop survived.
+ *
+ * The cause is always synchronous work in a handler: a tight loop, a large
+ * JSON.parse, a `*Sync` filesystem or crypto call. Node has one loop and no way
+ * to preempt it — move the work to a worker thread, a child process, or an async
+ * API that yields.
+ */
+export declare class EventLoopBlocked extends CairnQError {
+    readonly lateMs: number;
+    readonly intervalMs: number;
+    readonly leaseMs: number;
+    constructor(lateMs: number, intervalMs: number, leaseMs: number);
+}
 /** A worker write affected 0 rows: the lease expired and was reclaimed. */
 export declare class LostLease extends CairnQError {
     taskId: string;

package/dist/errors.js

@@ -67,9 +67,12 @@ export class QueueFull extends CairnQError {
  * 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?";
+function timeoutDetail(task, key) {
+    if (!task) {
+        return key === null
+            ? "task not found — wrong database file, or already purged?"
+            : "no task under this key — never submitted, or already purged?";
+    }
     if (isQueued(task)) {
         const delayMs = task.run_at_ms - nowMs();
         if (task.attempt === 0 && delayMs <= 0) {
@@ -83,20 +86,30 @@ function timeoutDetail(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). */
+/** wait/call did not reach a terminal status in time. The task keeps running, so
+ * `taskId` is the handle for picking the wait back up — `wait(err.taskId)`
+ * re-attaches to the same task from anywhere that can reach the store. `task` is
+ * the last snapshot wait() observed (null if the lookup 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).
+ *
+ * `key` is set when the wait watched a key rather than an id; `taskId` is then
+ * the task the key pointed at, or the key itself when it pointed at nothing —
+ * there was no id to report. */
 export class TaskTimeout extends CairnQError {
     taskId;
     task;
+    key;
     constructor(taskId, opts = {}) {
+        const key = opts.key ?? null;
+        const subject = key === null ? `task ${taskId}` : `key ${key}`;
         super(opts.timeoutMs == null
-            ? `task ${taskId} did not finish in time`
-            : `task ${taskId} did not finish within ${opts.timeoutMs}ms: ${timeoutDetail(opts.task ?? null)}`);
+            ? `${subject} did not finish in time`
+            : `${subject} did not finish within ${opts.timeoutMs}ms: ${timeoutDetail(opts.task ?? null, key)}`);
         this.taskId = taskId;
         this.name = "TaskTimeout";
         this.task = opts.task ?? null;
+        this.key = key;
     }
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
@@ -127,6 +140,35 @@ export class TaskCanceled extends CairnQError {
         this.name = "TaskCanceled";
     }
 }
+/**
+ * A heartbeat beat came back later than its own interval allowed.
+ *
+ * The heartbeat shares the event loop with the handlers whose leases it renews,
+ * so a handler that blocks the loop stops the renewal with it: the lease expires,
+ * the task is recovered and redelivered, and a second worker starts computing
+ * what the first is still computing — one task, billed twice, with no error
+ * anywhere. Nothing inside the blocked handler can observe that, which is why it
+ * is reported through `onError` alongside the other things the run loop survived.
+ *
+ * The cause is always synchronous work in a handler: a tight loop, a large
+ * JSON.parse, a `*Sync` filesystem or crypto call. Node has one loop and no way
+ * to preempt it — move the work to a worker thread, a child process, or an async
+ * API that yields.
+ */
+export class EventLoopBlocked extends CairnQError {
+    lateMs;
+    intervalMs;
+    leaseMs;
+    constructor(lateMs, intervalMs, leaseMs) {
+        super(`heartbeat beat was ${lateMs}ms late (interval ${intervalMs}ms, lease ${leaseMs}ms): ` +
+            `the event loop was blocked long enough to miss a beat. Synchronous work in a ` +
+            `handler starves lease renewal — move it off the loop.`);
+        this.lateMs = lateMs;
+        this.intervalMs = intervalMs;
+        this.leaseMs = leaseMs;
+        this.name = "EventLoopBlocked";
+    }
+}
 /** A worker write affected 0 rows: the lease expired and was reclaimed. */
 export class LostLease extends CairnQError {
     taskId;

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { CairnQ } from "./client.js";
 export type { CallOptions, ClientOptions, SubmitOptions } from "./client.js";
 export { QueueDepthGate } from "./backpressure.js";
 export type { BackpressureOptions, QueueDepthLimit } from "./backpressure.js";
+export { RetentionSweeper } from "./retention.js";
+export type { RetentionOptions } from "./retention.js";
 export { Worker } from "./worker.js";
 export type { BatchHandler, Handler, TypedHandler, WorkerOptions } from "./worker.js";
 export { TaskContext } from "./context.js";
@@ -14,5 +16,5 @@ 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, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 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";
@@ -7,4 +8,4 @@ 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, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/retention.d.ts

@@ -0,0 +1,60 @@
+import type { TaskStore } from "./store/base.js";
+export interface RetentionOptions {
+    /**
+     * How long a terminal task is kept after it finished. Required: there is no
+     * safe default for how long someone else's results stay readable.
+     */
+    olderThanMs: number;
+    /** Time between sweeps. Default 3_600_000 (one hour). */
+    intervalMs?: number;
+    /** Rows deleted per statement while draining. Default 1_000. */
+    limit?: number;
+    /**
+     * Called for a sweep that threw. The next sweep runs on schedule regardless —
+     * a purge that failed because the database was busy is not a reason to stop
+     * retaining — so without this a store quietly stops being swept. Must not throw.
+     */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Deletes terminal tasks on a schedule, for as long as the handle is open.
+ *
+ * `purge` exists because nothing else in CairnQ removes rows, and a queue whose
+ * payloads carry real data — an image, a document, a batch of embeddings — turns
+ * that into a disk leak measured in gigabytes per backfill. Every deployment
+ * that runs longer than a demo needs the sweep; leaving it to an external
+ * scheduler means the leak is the default and remembering is the opt-in.
+ *
+ * It sweeps in bounded batches with a yield between them, so draining a backlog
+ * that accumulated while nothing was sweeping stays a sequence of short writes
+ * rather than one long one — on SQLite that matters, since a long write holds
+ * the single write lock against every producer and worker on the file.
+ */
+export declare class RetentionSweeper {
+    private readonly store;
+    private readonly opts;
+    /** Whether the scheduled loop is running. */
+    private active;
+    /** Set by stop(), so a drain in progress can cut itself short too. */
+    private stopping;
+    /** Resolves the current sleep early, so stop() need not wait out an interval. */
+    private wake;
+    /** The loop itself, awaited by stop() so no purge outlives the store. */
+    private loop;
+    private readonly intervalMs;
+    private readonly purgeInput;
+    constructor(store: TaskStore, opts: RetentionOptions);
+    start(): void;
+    /** Stop sweeping and wait for the sweep in flight, if any. */
+    stop(): Promise<void>;
+    private run;
+    /**
+     * Delete everything past the cutoff now, in bounded batches, and return how
+     * many rows went. The scheduled loop calls this; call it directly to drain on
+     * 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. */
+    private sleep;
+}

package/dist/retention.js

@@ -0,0 +1,115 @@
+/** Sweep every hour unless asked otherwise — often enough that a queue with a
+ * day of retention never carries more than an hour of extra rows, rare enough
+ * that the sweep is invisible next to the task traffic. */
+const DEFAULT_INTERVAL_MS = 3_600_000;
+/** Rows per purge statement. The same bound `purge` defaults to: big enough that
+ * a backlog drains in few statements, small enough that each is a short write. */
+const DEFAULT_LIMIT = 1_000;
+/**
+ * Deletes terminal tasks on a schedule, for as long as the handle is open.
+ *
+ * `purge` exists because nothing else in CairnQ removes rows, and a queue whose
+ * payloads carry real data — an image, a document, a batch of embeddings — turns
+ * that into a disk leak measured in gigabytes per backfill. Every deployment
+ * that runs longer than a demo needs the sweep; leaving it to an external
+ * scheduler means the leak is the default and remembering is the opt-in.
+ *
+ * It sweeps in bounded batches with a yield between them, so draining a backlog
+ * that accumulated while nothing was sweeping stays a sequence of short writes
+ * rather than one long one — on SQLite that matters, since a long write holds
+ * the single write lock against every producer and worker on the file.
+ */
+export class RetentionSweeper {
+    store;
+    opts;
+    /** Whether the scheduled loop is running. */
+    active = false;
+    /** Set by stop(), so a drain in progress can cut itself short too. */
+    stopping = false;
+    /** Resolves the current sleep early, so stop() need not wait out an interval. */
+    wake = null;
+    /** The loop itself, awaited by stop() so no purge outlives the store. */
+    loop = null;
+    intervalMs;
+    purgeInput;
+    constructor(store, opts) {
+        this.store = store;
+        this.opts = opts;
+        if (!Number.isFinite(opts.olderThanMs) || opts.olderThanMs < 0) {
+            throw new Error(`retention.olderThanMs must be >= 0, got ${opts.olderThanMs}`);
+        }
+        this.intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+        if (!Number.isFinite(this.intervalMs) || this.intervalMs < 1) {
+            throw new Error(`retention.intervalMs must be >= 1, got ${this.intervalMs}`);
+        }
+        this.purgeInput = { olderThanMs: opts.olderThanMs, limit: opts.limit ?? DEFAULT_LIMIT };
+    }
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.stopping = false;
+        this.loop = this.run();
+    }
+    /** Stop sweeping and wait for the sweep in flight, if any. */
+    async stop() {
+        this.stopping = true;
+        this.active = false;
+        this.wake?.();
+        await this.loop;
+        this.loop = null;
+    }
+    async run() {
+        // Sleep first: a process that restarts often would otherwise purge on every
+        // boot, which is a write burst exactly when the store is busiest.
+        while (!this.stopping) {
+            await this.sleep(this.intervalMs);
+            if (this.stopping)
+                return;
+            try {
+                await this.sweep();
+            }
+            catch (err) {
+                try {
+                    this.opts.onError?.(err);
+                }
+                catch {
+                    // A reporting hook must never take the sweep down with it — the same
+                    // rule the worker's onError follows.
+                }
+            }
+        }
+    }
+    /**
+     * Delete everything past the cutoff now, in bounded batches, and return how
+     * many rows went. The scheduled loop calls this; call it directly to drain on
+     * demand — after a backfill, or from a maintenance command.
+     */
+    async sweep() {
+        const limit = this.purgeInput.limit;
+        let deleted = 0;
+        for (;;) {
+            const ids = await this.store.purge(this.purgeInput);
+            deleted += ids.length;
+            if (ids.length < limit || this.stopping)
+                return deleted;
+            // Hand the loop back between batches: a large drain must not starve the
+            // submits and claims sharing this process.
+            await this.sleep(0);
+        }
+    }
+    /** 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) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+            this.wake = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        }).finally(() => {
+            this.wake = null;
+        });
+    }
+}

package/dist/store/base.d.ts

@@ -11,7 +11,7 @@ export declare function dumpJson(value: unknown): string;
  * 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"];
+declare const CONFLICTS: readonly ["reuse", "reuse-succeeded", "reject", "replace"];
 export type Conflict = (typeof CONFLICTS)[number];
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */

package/dist/store/base.js

@@ -1,6 +1,6 @@
 import { newId } from "../ids.js";
 import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, } from "../errors.js";
-import { rowToTask, STATUSES } from "../models.js";
+import { rowToTask, STATUSES, TERMINAL } from "../models.js";
 import { QueueDepthGate } from "../backpressure.js";
 const rejectMangled = function (_key, v) {
     if (typeof v === "number" && !Number.isFinite(v)) {
@@ -51,7 +51,24 @@ export function checkProtocolVersion(version) {
 // CONFLICTS is the canonical declaration; the type derives from it so the
 // runtime guard in submit() and the type can't drift apart (same pattern as
 // STATUSES/TaskStatus in models.ts).
-const CONFLICTS = ["reuse", "reject", "replace"];
+const CONFLICTS = ["reuse", "reuse-succeeded", "reject", "replace"];
+/**
+ * Whether a keyed submit's strategy accepts the task the key already points at.
+ *
+ * Both reuse strategies deduplicate work that is still in play — that is what a
+ * key is for, and the answer cannot depend on the outcome of a task that has no
+ * outcome yet. They differ only on what a *finished* task means: `reuse` treats
+ * the key as free again, while `reuse-succeeded` reads a succeeded task as a
+ * cached result. Neither ever hands back a failed or canceled one, which would
+ * poison the key for every later submit (see PROTOCOL.md "Key conflict").
+ */
+function reusable(conflict, status) {
+    if (conflict === "replace")
+        return false;
+    if (!TERMINAL.includes(status))
+        return true;
+    return conflict === "reuse-succeeded" && status === "succeeded";
+}
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */
 export const DEFAULT_QUEUE = "default";
@@ -207,12 +224,17 @@ export class TaskStore {
                 // free after all, whatever the strategy.
                 const current = (await fetch("get", { id: existing[0].task_id }))[0];
                 if (current) {
-                    if (conflict === "reuse")
-                        return rowToTask(current);
                     if (conflict === "reject")
                         throw new AlreadyExists(key);
-                    // "replace": cancel the recorded task, then repoint the key below.
-                    await fetch("cancel", { id: existing[0].task_id });
+                    if (reusable(conflict, current.status))
+                        return rowToTask(current);
+                    // The strategy declined the recorded task, so the key repoints to the
+                    // fresh one inserted below. Cancel only what is still live: a terminal
+                    // task has nothing to stop, and cancelling it would rewrite a settled
+                    // row (and hand a `canceled` back to whoever is waiting on it).
+                    if (!TERMINAL.includes(current.status)) {
+                        await fetch("cancel", { id: existing[0].task_id });
+                    }
                 }
             }
             const row = (await fetch("insert_task", ins))[0];

package/dist/wait.d.ts

@@ -2,6 +2,11 @@ import { type Task } from "./models.js";
 import type { TaskStore } from "./store/base.js";
 export declare const DEFAULT_POLL_MS = 100;
 export declare const MAX_POLL_MS = 500;
+export interface PollOptions {
+    timeoutMs: number;
+    pollMs?: number;
+    maxPollMs?: number;
+}
 /**
  * Grow the polling interval towards the ceiling.
  *
@@ -14,8 +19,18 @@ export declare function nextPollMs(current: number, maxMs: number): number;
 /** Poll get() until terminal or timeout. Returns the terminal Task (any status).
  * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
  * it backs off towards `maxPollMs`. */
-export declare function pollWait(store: TaskStore, taskId: string, { timeoutMs, pollMs, maxPollMs, }: {
-    timeoutMs: number;
-    pollMs?: number;
-    maxPollMs?: number;
-}): Promise<Task>;
+export declare function pollWait(store: TaskStore, taskId: string, opts: PollOptions): Promise<Task>;
+/**
+ * The same wait, following a key instead of an id.
+ *
+ * The key is re-resolved on every read, because that is what a key means: a
+ * pointer to the task that is *current* under it. A `replace` landing mid-wait
+ * moves the wait onto the new task rather than reporting the cancellation of the
+ * old one, and a key that points at nothing yet is simply not finished — it
+ * polls until something appears, the same way waiting on an id that does not
+ * exist yet does.
+ *
+ * There is nothing to subscribe to before the key resolves, so those naps are
+ * plain sleeps; once it resolves, the store's push channel applies as usual.
+ */
+export declare function pollWaitByKey(store: TaskStore, key: string, opts: PollOptions): Promise<Task>;