cairnq 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",

package/src/backoff.ts

@@ -0,0 +1,53 @@
+/**
+ * Retry backoff, in its own module because two callers need it.
+ *
+ * The worker computes it when a handler's failure ends an attempt; TaskContext
+ * computes it when a handler fails one task of a batch itself. Keeping it in
+ * worker.ts would make context.ts import the module that imports it.
+ */
+
+export const DEFAULT_RETRY_BACKOFF_MS = 1_000;
+export const DEFAULT_RETRY_BACKOFF_MAX_MS = 30_000;
+
+/**
+ * Exponential backoff with equal jitter: the window doubles per attempt up to
+ * `maxMs`, and the delay lands uniformly in its upper half, `[w/2, w)`.
+ *
+ * The jitter is what keeps a fleet from retrying in lockstep. Failures align
+ * when the downstream fails fast enough that a whole concurrency batch raises
+ * at once (connection refused, DNS gone), and capped exponential backoff then
+ * *preserves* that alignment — once every task sits at `maxMs`, they all retry
+ * on the same beat forever. Spreading over half the window breaks it; keeping
+ * the lower half as a floor means jitter never shortens the wait to less than
+ * half of what plain exponential backoff would have asked for.
+ *
+ * `rand` is injected so tests can pin an exact delay.
+ */
+export function retryDelayMs(
+  attempt: number,
+  baseMs: number,
+  maxMs: number,
+  rand: () => number = Math.random,
+): number {
+  if (baseMs <= 0) return 0;
+  const exponent = Math.max(0, attempt - 1);
+  const window = Math.min(maxMs, baseMs * 2 ** exponent);
+  const floor = Math.floor(window / 2);
+  return floor + Math.floor(rand() * (window - floor));
+}
+
+/**
+ * The delay a `fail` write should carry. Not just the backoff: a permanent
+ * failure is never re-run, so it always delays 0. Both settlement paths — the
+ * worker's and a handler's `ctx.fail` — go through this, so they cannot end up
+ * backing off differently.
+ */
+export function failDelayMs(
+  attempt: number,
+  retryable: boolean,
+  baseMs: number,
+  maxMs: number,
+  rand: () => number = Math.random,
+): number {
+  return retryable ? retryDelayMs(attempt, baseMs, maxMs, rand) : 0;
+}

package/src/client.ts

@@ -1,11 +1,12 @@
 import type { BackpressureOptions } from "./backpressure.js";
+import { type RetentionOptions, RetentionSweeper } from "./retention.js";
 import { TaskCanceled, TaskFailed } from "./errors.js";
 import { isFailed, isSucceeded, type Task, type TaskStatus } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
 import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
-import { pollWait } from "./wait.js";
+import { pollWait, pollWaitByKey } from "./wait.js";
 
 export type SubmitOptions = Omit<SubmitInput, "name" | "payload">;
 export interface CallOptions extends SubmitOptions {
@@ -15,10 +16,18 @@ 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 class CairnQ {
+  /** null unless `retention` was configured. */
+  private readonly sweeper: RetentionSweeper | null;
+
   constructor(
     private readonly _store: TaskStore,
     opts: ClientOptions = {},
@@ -28,6 +37,13 @@ export class CairnQ {
     if (opts.maxQueueDepth != null) {
       _store.useBackpressure(opts as BackpressureOptions);
     }
+    // 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: string, opts: { busyTimeoutMs?: number } & ClientOptions = {}): CairnQ {
@@ -50,8 +66,11 @@ export class CairnQ {
     return this._store.connect();
   }
 
-  close(): Promise<void> {
-    return this._store.close();
+  /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+   * store) and close the store. */
+  async close(): Promise<void> {
+    await this.sweeper?.stop();
+    await this._store.close();
   }
 
   /** Enqueue a task. With `maxQueueDepth` configured this blocks while the
@@ -114,6 +133,9 @@ export class CairnQ {
     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: string,
     opts: { timeoutMs?: number; pollMs?: number } = {},
@@ -124,9 +146,25 @@ export class CairnQ {
     });
   }
 
+  /** 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> {
+    return pollWaitByKey(this._store, key, {
+      timeoutMs: opts.timeoutMs ?? 30_000,
+      pollMs: opts.pollMs,
+    });
+  }
+
   /** 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. */
   async call(name: string, payload?: unknown, opts?: CallOptions): Promise<unknown>;
   async call<P, R>(task: TaskDef<P, R>, payload?: P, opts?: CallOptions): Promise<R>;
   async call(task: string | TaskDef, payload?: unknown, opts: CallOptions = {}): Promise<unknown> {

package/src/context.ts

@@ -1,24 +1,48 @@
-import { LostLease } from "./errors.js";
+import { DEFAULT_RETRY_BACKOFF_MAX_MS, DEFAULT_RETRY_BACKOFF_MS, failDelayMs } from "./backoff.js";
+import { asEnvelope, type FailReason, LostLease } from "./errors.js";
 import { cancelRequested, type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
 import { pollWait } from "./wait.js";
 
-/** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
+export interface TaskContextOptions {
+  retryBackoffMs?: number;
+  retryBackoffMaxMs?: number;
+}
+
+/**
+ * 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 {
   private readonly abort = new AbortController();
   private leaseLost = false;
   // Cancellation is monotonic: once the DB has told us a cancel was requested it
   // can't be taken back, so canceled() can answer from this without a re-read.
   private cancelSeen = false;
+  // 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.
+  private isSettled = false;
+  private readonly backoffMs: number;
+  private readonly backoffMaxMs: number;
 
   constructor(
     private readonly store: TaskStore,
     private readonly task: Task,
     public readonly workerId: string,
     private readonly leaseMs: number,
-  ) {}
+    opts: TaskContextOptions = {},
+  ) {
+    this.backoffMs = opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+    this.backoffMaxMs = opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS;
+  }
 
   get taskId(): string {
     return this.task.id;
@@ -44,6 +68,19 @@ export class TaskContext {
   get payload(): any {
     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(): boolean {
+    return this.isSettled;
+  }
+
+  /** @internal Called by the worker when it finalizes this task itself. */
+  markSettled(): void {
+    this.isSettled = true;
+  }
 
   /**
    * True once this worker has lost the task's lease — it expired and another
@@ -70,17 +107,36 @@ export class TaskContext {
   // Every owned write returns the current row, so cancellation and lease loss
   // ride along on writes the handler was making anyway.
   private observe(task: Task): Task {
-    if (cancelRequested(task)) this.cancelSeen = true;
+    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: boolean): void {
+    if (cancelRequested) this.cancelSeen = true;
+  }
+
   private async owned(write: () => Promise<Task>): Promise<Task> {
-    // Short-circuit once the lease is known lost: nothing this context writes
-    // may be recorded any more. Locally, not just via the store's ownership
-    // check — after an abandoned (timed-out) attempt the same worker may
-    // re-claim this task under the same workerId, and a zombie handler's write
-    // would then pass ownership against the NEW attempt.
+    // 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());
     } catch (err) {
@@ -119,6 +175,57 @@ export class TaskContext {
     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: unknown = null): Promise<Task | 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: FailReason = "task failed",
+    opts: { retryable?: boolean } = {},
+  ): Promise<Task | null> {
+    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;
+  }
+
   /** Submit a child task; parent/root/correlation are wired automatically. */
   submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;
   submit<P, R>(task: TaskDef<P, R>, payload?: P, opts?: SubmitOptions): Promise<Task>;

package/src/errors.ts

@@ -20,6 +20,24 @@ export function errorEnvelope(e: {
   };
 }
 
+/**
+ * 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: unknown, retryable = true): Record<string, unknown> {
+  const e = err as { name?: string; message?: string };
+  return errorEnvelope({
+    type: e?.name ?? "Error",
+    code: "handler_error",
+    message: String(e?.message ?? err),
+    retryable,
+  });
+}
+
 export class CairnQError extends Error {
   constructor(message?: string) {
     super(message);
@@ -59,8 +77,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: Task | null): string {
-  if (!task) return "task not found — wrong database file, or already purged?";
+function timeoutDetail(task: Task | null, key: string | null): string {
+  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) {
@@ -76,23 +98,33 @@ function timeoutDetail(task: Task | null): string {
   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 {
   readonly task: Task | null;
+  readonly key: string | null;
   constructor(
     public taskId: string,
-    opts: { timeoutMs?: number; task?: Task | null } = {},
+    opts: { timeoutMs?: number; task?: Task | null; key?: string | null } = {},
   ) {
+    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.name = "TaskTimeout";
     this.task = opts.task ?? null;
+    this.key = key;
   }
 }
 
@@ -128,6 +160,36 @@ export class TaskCanceled extends CairnQError {
   }
 }
 
+/**
+ * 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 {
+  constructor(
+    readonly lateMs: number,
+    readonly intervalMs: number,
+    readonly leaseMs: number,
+  ) {
+    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.name = "EventLoopBlocked";
+  }
+}
+
 /** A worker write affected 0 rows: the lease expired and was reclaimed. */
 export class LostLease extends CairnQError {
   constructor(public taskId: string) {
@@ -183,3 +245,33 @@ export class TaskError extends CairnQError {
     });
   }
 }
+
+/** 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 function asEnvelope(
+  error: FailReason,
+  retryable: boolean,
+): [Record<string, unknown>, boolean] {
+  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/src/index.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";
@@ -31,6 +34,8 @@ export {
   TaskCanceled,
   TaskError,
   LostLease,
+  EventLoopBlocked,
   ProtocolVersionMismatch,
   SerializationError,
 } from "./errors.js";
+export type { FailReason } from "./errors.js";

package/src/retention.ts

@@ -0,0 +1,136 @@
+import type { PurgeInput, TaskStore } from "./store/base.js";
+
+/** 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;
+
+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 class RetentionSweeper {
+  /** Whether the scheduled loop is running. */
+  private active = false;
+  /** Set by stop(), so a drain in progress can cut itself short too. */
+  private stopping = false;
+  /** Resolves the current sleep early, so stop() need not wait out an interval. */
+  private wake: (() => void) | null = null;
+  /** The loop itself, awaited by stop() so no purge outlives the store. */
+  private loop: Promise<void> | null = null;
+  private readonly intervalMs: number;
+  private readonly purgeInput: PurgeInput;
+
+  constructor(
+    private readonly store: TaskStore,
+    private readonly opts: RetentionOptions,
+  ) {
+    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(): void {
+    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(): Promise<void> {
+    this.stopping = true;
+    this.active = false;
+    this.wake?.();
+    await this.loop;
+    this.loop = null;
+  }
+
+  private async run(): Promise<void> {
+    // 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(): Promise<number> {
+    const limit = this.purgeInput.limit as number;
+    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. */
+  private sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      timer.unref?.();
+      this.wake = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+    }).finally(() => {
+      this.wake = null;
+    });
+  }
+}