cairnq 0.5.0 → 0.7.0

package/dist/context.js

@@ -1,8 +1,16 @@
-import { LostLease } from "./errors.js";
+import { DEFAULT_RETRY_BACKOFF_MAX_MS, DEFAULT_RETRY_BACKOFF_MS, failDelayMs } from "./backoff.js";
+import { asEnvelope, LostLease } from "./errors.js";
 import { cancelRequested } from "./models.js";
 import { taskName } from "./task.js";
 import { pollWait } from "./wait.js";
-/** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
+/**
+ * Handed to a task handler. Worker-side capabilities mirror the Python SDK.
+ *
+ * One of these per task, whether a handler is delivered one task or a batch: a
+ * batch handler receives a `TaskContext[]`, so a single-task handler's `ctx` is
+ * literally the batch-of-one element. Lease, cancellation and settlement are per
+ * task, which is why they live here rather than on anything batch-shaped.
+ */
 export class TaskContext {
     store;
     task;
@@ -13,11 +21,20 @@ export class TaskContext {
     // 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) {
+    // Set once this task reached a terminal state through succeed()/fail(). The
+    // worker reads it to know which tasks a batch handler already decided, so it
+    // neither settles them twice nor keeps renewing their leases — the bookkeeping
+    // every ack/nack-style handler otherwise has to carry itself.
+    isSettled = false;
+    backoffMs;
+    backoffMaxMs;
+    constructor(store, task, workerId, leaseMs, opts = {}) {
         this.store = store;
         this.task = task;
         this.workerId = workerId;
         this.leaseMs = leaseMs;
+        this.backoffMs = opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+        this.backoffMaxMs = opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS;
     }
     get taskId() {
         return this.task.id;
@@ -43,6 +60,18 @@ export class TaskContext {
     get payload() {
         return this.task.payload;
     }
+    /**
+     * True once this task reached a terminal state — whether the handler settled
+     * it with succeed()/fail() or the worker settled it on the handler's behalf.
+     * The heartbeat and the settlement paths both read it.
+     */
+    get settled() {
+        return this.isSettled;
+    }
+    /** @internal Called by the worker when it finalizes this task itself. */
+    markSettled() {
+        this.isSettled = true;
+    }
     /**
      * 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
@@ -66,18 +95,37 @@ export class TaskContext {
     // 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;
+        this.observeCancel(cancelRequested(task));
         return task;
     }
+    /**
+     * @internal The same observation from just the flag, for a caller that read it
+     * without materializing a Task — the shared heartbeat, whose statement returns
+     * only the id and the cancel column precisely so it does not have to drag
+     * every payload back on every beat.
+     */
+    observeCancel(cancelRequested) {
+        if (cancelRequested)
+            this.cancelSeen = true;
+    }
     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.
+        // One gate for every write through this context, so "may I still write?" is
+        // answered in one place rather than at each call site.
+        //
+        // Lease lost: nothing this context writes may be recorded any more. Checked
+        // 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);
+        // Settled: the task is terminal, so the statement would match no row and come
+        // back as a lost lease — telling the handler "another worker took this" when
+        // the truth is "you already finished it", and flipping lostLease on the way.
+        // Refuse here instead, without the round trip and without corrupting the
+        // lease state.
+        if (this.isSettled)
+            throw new LostLease(this.task.id);
         try {
             return this.observe(await write());
         }
@@ -113,6 +161,49 @@ export class TaskContext {
             this.cancelSeen = true;
         return this.cancelSeen || t.status === "canceled";
     }
+    // ------------------------------------------------------------- settlement
+    // Finalizing a task is normally the worker's job, decided by whether the
+    // handler returned or threw. These two let a handler decide one task itself,
+    // which is what a batch needs: four of 256 tasks failing for four different
+    // reasons is the ordinary case, not the edge one, and it cannot be expressed
+    // by a single return value or a single throw.
+    //
+    // Settling twice is a no-op rather than an error. Handlers built on ack/nack
+    // queues all end up carrying a `finalizedIds` set to guarantee exactly that;
+    // holding it here instead is the point.
+    /**
+     * Finalize this task as succeeded, now, without waiting for the handler to
+     * return. `complete` semantics: a cancel requested while it ran wins and the
+     * task finalizes as canceled instead, its result discarded. Returns null if
+     * this task was already settled.
+     */
+    async succeed(result = null) {
+        if (this.isSettled)
+            return null;
+        const task = await this.owned(() => this.store.complete({ taskId: this.task.id, workerId: this.workerId, result }));
+        this.markSettled();
+        return task;
+    }
+    /**
+     * Finalize this task as failed, now. `error` may be a string reason, an Error,
+     * a TaskError (which carries its own retryability), or a ready envelope.
+     * Retryable failures get the worker's backoff and are re-queued while attempts
+     * remain, exactly as a thrown error would be. Returns null if already settled.
+     */
+    async fail(error = "task failed", opts = {}) {
+        if (this.isSettled)
+            return null;
+        const [envelope, retryable] = asEnvelope(error, opts.retryable ?? true);
+        const task = await this.owned(() => this.store.fail({
+            taskId: this.task.id,
+            workerId: this.workerId,
+            error: envelope,
+            retryable,
+            delayMs: failDelayMs(this.task.attempt, retryable, this.backoffMs, this.backoffMaxMs),
+        }));
+        this.markSettled();
+        return task;
+    }
     async submit(task, payload, opts = {}) {
         return this.store.submit({
             name: taskName(task),

package/dist/errors.d.ts

@@ -9,6 +9,15 @@ export declare function errorEnvelope(e: {
     retryable: boolean;
     details?: Record<string, unknown>;
 }): Record<string, unknown>;
+/**
+ * How an arbitrary thrown value becomes an envelope. Split out from `asEnvelope`
+ * below because the worker also reaches it directly, for a thrown plain object —
+ * which `asEnvelope` reads as a ready envelope, the right call for `ctx.fail` and
+ * the wrong one for something that was thrown. Both must agree on `code` and on
+ * deriving `type` from the error's name, or the same error reads differently
+ * depending on which way it was recorded.
+ */
+export declare function exceptionEnvelope(err: unknown, retryable?: boolean): Record<string, unknown>;
 export declare class CairnQError extends Error {
     constructor(message?: string);
 }
@@ -26,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
@@ -53,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;
@@ -84,3 +122,21 @@ export declare class TaskError extends CairnQError {
     });
     envelope(): Record<string, unknown>;
 }
+/** What a handler may pass to `ctx.fail`. */
+export type FailReason = string | Error | TaskError | Record<string, unknown>;
+/**
+ * Normalize anything that can end a task into [envelope, retryable].
+ *
+ * Shared by both ways a failure is recorded — a handler passing a reason to
+ * `ctx.fail`, and the worker classifying an error that ended an attempt — so the
+ * two cannot disagree about what a given error means. It lives here, beside the
+ * envelope constructors it dispatches to, rather than in the module that happens
+ * to expose it to handlers.
+ *
+ * A handler failing one task of a batch has a reason, not an exception object:
+ * `item.fail("no source records", { retryable: false })` is the shape the real
+ * code wants. A TaskError carries its own retryability and wins over the option;
+ * everything else takes the caller's. A ready envelope passes through, which is
+ * how the worker hands in the ones it composes itself.
+ */
+export declare function asEnvelope(error: FailReason, retryable: boolean): [Record<string, unknown>, boolean];

package/dist/errors.js

@@ -12,6 +12,23 @@ export function errorEnvelope(e) {
         details: e.details ?? {},
     };
 }
+/**
+ * How an arbitrary thrown value becomes an envelope. Split out from `asEnvelope`
+ * below because the worker also reaches it directly, for a thrown plain object —
+ * which `asEnvelope` reads as a ready envelope, the right call for `ctx.fail` and
+ * the wrong one for something that was thrown. Both must agree on `code` and on
+ * deriving `type` from the error's name, or the same error reads differently
+ * depending on which way it was recorded.
+ */
+export function exceptionEnvelope(err, retryable = true) {
+    const e = err;
+    return errorEnvelope({
+        type: e?.name ?? "Error",
+        code: "handler_error",
+        message: String(e?.message ?? err),
+        retryable,
+    });
+}
 export class CairnQError extends Error {
     constructor(message) {
         super(message);
@@ -50,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) {
@@ -66,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
@@ -110,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;
@@ -161,3 +220,29 @@ export class TaskError extends CairnQError {
         });
     }
 }
+/**
+ * Normalize anything that can end a task into [envelope, retryable].
+ *
+ * Shared by both ways a failure is recorded — a handler passing a reason to
+ * `ctx.fail`, and the worker classifying an error that ended an attempt — so the
+ * two cannot disagree about what a given error means. It lives here, beside the
+ * envelope constructors it dispatches to, rather than in the module that happens
+ * to expose it to handlers.
+ *
+ * A handler failing one task of a batch has a reason, not an exception object:
+ * `item.fail("no source records", { retryable: false })` is the shape the real
+ * code wants. A TaskError carries its own retryability and wins over the option;
+ * everything else takes the caller's. A ready envelope passes through, which is
+ * how the worker hands in the ones it composes itself.
+ */
+export function asEnvelope(error, retryable) {
+    if (error instanceof TaskError)
+        return [error.envelope(), error.retryable];
+    if (error instanceof Error)
+        return [exceptionEnvelope(error, retryable), retryable];
+    if (typeof error === "object" && error !== null)
+        return [error, retryable];
+    // A bare reason is a TaskError in everything but the throwing, so let
+    // TaskError own its own type/code defaults rather than restating them.
+    return [new TaskError(String(error), { retryable }).envelope(), retryable];
+}

package/dist/index.d.ts

@@ -2,9 +2,12 @@ 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 { Handler, TypedHandler, WorkerOptions } 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";
@@ -13,4 +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;
+        });
+    }
+}