@crewhaus/queue-consumer 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Catalog R14 `queue-consumer` — Section 23 BATCH.
+ *
+ * Long-running consumer loop. Pulls jobs from any `QueueAdapter`, runs
+ * the user's handler with `concurrency`-bounded parallelism, wraps each
+ * call in an idempotency-key cache so retries hit cache, and acks /
+ * nacks based on the handler's outcome.
+ *
+ * Visibility renewal: while a handler is running, a sidecar timer
+ * extends the job's visibility every `visibilityRenewIntervalMs` until
+ * either the handler completes or the consumer is told to stop. This
+ * keeps long-running model calls from being yanked out from under the
+ * worker by another consumer that thinks the lease expired.
+ *
+ * Retry policy:
+ *   - handler throws + `attempt < maxRetries` → `nack(transient)` so
+ *     the queue re-enqueues for the next consumer.
+ *   - handler throws + `attempt >= maxRetries` → `nack(permanent)` so
+ *     the queue moves the job to its DLQ.
+ *   - handler resolves → `ack`.
+ *
+ * Drain semantics: `drain()` stops new pulls but lets in-flight handlers
+ * complete + ack. `stop()` is `drain()` plus a wait — used by the
+ * SIGTERM path so the daemon shuts down cleanly without orphaning
+ * mid-flight jobs.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { type IdempotencyStore } from "@crewhaus/idempotency-keys";
+import type { Job, NackReason, QueueAdapter } from "@crewhaus/queue-protocol";
+export declare class QueueConsumerError extends CrewhausError {
+    readonly name = "QueueConsumerError";
+    constructor(message: string, cause?: unknown);
+}
+export type ConsumerHandlerOutcome<TResult> = {
+    kind: "ok";
+    value: TResult;
+    fromCache: boolean;
+} | {
+    kind: "fail";
+    reason: NackReason;
+    error: unknown;
+};
+export type ConsumerObserver<TInput, TResult> = {
+    onJobStart?(job: Job<TInput>): void;
+    onJobEnd?(job: Job<TInput>, outcome: ConsumerHandlerOutcome<TResult>): void;
+    /** Fires when drain begins. */
+    onDrainStart?(): void;
+    /** Fires after drain completes (no more in-flight). */
+    onDrainEnd?(): void;
+};
+export type ConsumerOptions<TInput, TResult> = {
+    readonly queue: QueueAdapter<TInput>;
+    readonly handler: (input: TInput, ctx: {
+        key: string;
+        job: Job<TInput>;
+    }) => Promise<TResult>;
+    readonly concurrency: number;
+    readonly visibilityTimeoutMs: number;
+    readonly visibilityRenewIntervalMs?: number;
+    readonly idempotencyStore?: IdempotencyStore<TResult>;
+    readonly idempotencyTtlMs?: number;
+    readonly maxRetries?: number;
+    /** Per-pull batch cap. Defaults to `concurrency`. */
+    readonly pullBatchSize?: number;
+    /** Wait between empty-queue pulls. Defaults to 100ms. */
+    readonly emptyQueuePollMs?: number;
+    readonly observer?: ConsumerObserver<TInput, TResult>;
+    /** Test seam — `setTimeout`/`clearTimeout` overrides for deterministic visibility renewal tests. */
+    readonly _setTimeout?: typeof setTimeout;
+    readonly _clearTimeout?: typeof clearTimeout;
+};
+export interface RunningConsumer {
+    /**
+     * Block until every in-flight handler completes; no new pulls happen
+     * after this is called. Idempotent — second call returns the same
+     * promise.
+     */
+    drain(): Promise<void>;
+    /**
+     * Start drain + return when finished. Convenience for SIGTERM paths.
+     * Equivalent to `drain()` today; left as a separate verb so future
+     * graceful-stop semantics (e.g. close adapter connections) can fit.
+     */
+    stop(): Promise<void>;
+    /** Diagnostic — currently in-flight job count. */
+    inFlight(): number;
+}
+export declare function startConsumer<TInput, TResult>(opts: ConsumerOptions<TInput, TResult>): RunningConsumer;

package/dist/index.js

@@ -0,0 +1,184 @@
+/**
+ * Catalog R14 `queue-consumer` — Section 23 BATCH.
+ *
+ * Long-running consumer loop. Pulls jobs from any `QueueAdapter`, runs
+ * the user's handler with `concurrency`-bounded parallelism, wraps each
+ * call in an idempotency-key cache so retries hit cache, and acks /
+ * nacks based on the handler's outcome.
+ *
+ * Visibility renewal: while a handler is running, a sidecar timer
+ * extends the job's visibility every `visibilityRenewIntervalMs` until
+ * either the handler completes or the consumer is told to stop. This
+ * keeps long-running model calls from being yanked out from under the
+ * worker by another consumer that thinks the lease expired.
+ *
+ * Retry policy:
+ *   - handler throws + `attempt < maxRetries` → `nack(transient)` so
+ *     the queue re-enqueues for the next consumer.
+ *   - handler throws + `attempt >= maxRetries` → `nack(permanent)` so
+ *     the queue moves the job to its DLQ.
+ *   - handler resolves → `ack`.
+ *
+ * Drain semantics: `drain()` stops new pulls but lets in-flight handlers
+ * complete + ack. `stop()` is `drain()` plus a wait — used by the
+ * SIGTERM path so the daemon shuts down cleanly without orphaning
+ * mid-flight jobs.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { idempotencyKey, withIdempotency } from "@crewhaus/idempotency-keys";
+export class QueueConsumerError extends CrewhausError {
+    name = "QueueConsumerError";
+    constructor(message, cause) {
+        super("runtime", message, cause);
+    }
+}
+const DEFAULT_VISIBILITY_RENEW_INTERVAL_MS = 5_000;
+const DEFAULT_IDEMPOTENCY_TTL_MS = 60_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_EMPTY_QUEUE_POLL_MS = 100;
+export function startConsumer(opts) {
+    const visRenewMs = opts.visibilityRenewIntervalMs ?? DEFAULT_VISIBILITY_RENEW_INTERVAL_MS;
+    const idempotencyTtlMs = opts.idempotencyTtlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS;
+    const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const pullBatch = opts.pullBatchSize ?? opts.concurrency;
+    const emptyPollMs = opts.emptyQueuePollMs ?? DEFAULT_EMPTY_QUEUE_POLL_MS;
+    const ts = opts._setTimeout ?? setTimeout;
+    const tc = opts._clearTimeout ?? clearTimeout;
+    const wrappedHandler = opts.idempotencyStore
+        ? withIdempotency(async ({ input, job }, key) => opts.handler(input, { key, job }), { store: opts.idempotencyStore, ttlMs: idempotencyTtlMs })
+        : undefined;
+    let stopping = false;
+    let drainPromise;
+    const inFlight = new Set();
+    // Pull loop runs as a background async function. It awaits available
+    // concurrency before pulling the next batch.
+    const loopPromise = (async () => {
+        while (!stopping) {
+            // Concurrency gate: wait until at least one slot is free.
+            while (inFlight.size >= opts.concurrency && !stopping) {
+                await Promise.race(inFlight);
+            }
+            if (stopping)
+                break;
+            const want = Math.max(1, Math.min(pullBatch, opts.concurrency - inFlight.size));
+            let pulled;
+            try {
+                pulled = await opts.queue.pull({
+                    maxBatch: want,
+                    visibilityTimeoutMs: opts.visibilityTimeoutMs,
+                });
+            }
+            catch (err) {
+                // Adapter blip — treat as empty pull, slow down a bit, retry.
+                await sleep(emptyPollMs * 2);
+                continue;
+            }
+            if (pulled.length === 0) {
+                await sleep(emptyPollMs);
+                continue;
+            }
+            for (const job of pulled) {
+                const p = handleOne(job).finally(() => {
+                    inFlight.delete(p);
+                });
+                inFlight.add(p);
+            }
+        }
+    })().catch((err) => {
+        // Surface any unhandled error from the loop itself (rare — handlers
+        // already trap exceptions).
+        process.stderr.write(`[queue-consumer] loop error: ${err.message}\n`);
+    });
+    async function handleOne(job) {
+        opts.observer?.onJobStart?.(job);
+        const key = idempotencyKey(job.id, job.attempt);
+        const stopRenew = startVisibilityRenew(opts.queue, job.id, visRenewMs, ts, tc);
+        let outcome;
+        try {
+            const r = wrappedHandler
+                ? await wrappedHandler({ input: job.input, job }, key)
+                : { value: await opts.handler(job.input, { key, job }), fromCache: false };
+            outcome = { kind: "ok", value: r.value, fromCache: r.fromCache };
+        }
+        catch (err) {
+            const isLast = job.attempt >= maxRetries;
+            outcome = {
+                kind: "fail",
+                reason: isLast ? "permanent" : "transient",
+                error: err,
+            };
+        }
+        finally {
+            stopRenew();
+        }
+        if (outcome.kind === "ok") {
+            try {
+                await opts.queue.ack(job.id);
+            }
+            catch (err) {
+                // Best-effort: log + continue. Adapter ack failures don't reach
+                // userland; they'd surface as duplicate work on the next pull.
+            }
+        }
+        else {
+            try {
+                await opts.queue.nack(job.id, outcome.reason);
+            }
+            catch {
+                // Same rationale.
+            }
+        }
+        opts.observer?.onJobEnd?.(job, outcome);
+    }
+    async function drain() {
+        if (drainPromise !== undefined)
+            return drainPromise;
+        stopping = true;
+        opts.observer?.onDrainStart?.();
+        drainPromise = (async () => {
+            // First, let the pull loop notice the stop flag.
+            await loopPromise;
+            // Then wait for in-flight to finish.
+            while (inFlight.size > 0) {
+                await Promise.race(inFlight);
+            }
+            opts.observer?.onDrainEnd?.();
+        })();
+        return drainPromise;
+    }
+    return {
+        drain,
+        stop: drain,
+        inFlight: () => inFlight.size,
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Start a sidecar that calls `extendVisibility(jobId, ...)` every
+ * `intervalMs` until the returned `stop()` is invoked. We pass the
+ * timer functions explicitly so tests can drive them deterministically.
+ */
+function startVisibilityRenew(queue, jobId, intervalMs, setTimeoutImpl, clearTimeoutImpl) {
+    let stopped = false;
+    let handle;
+    const tick = () => {
+        if (stopped)
+            return;
+        handle = setTimeoutImpl(() => {
+            if (stopped)
+                return;
+            // Best-effort: a renew failure after the job is already ack'd is
+            // expected (extendVisibility throws unknown-jobId). Swallow.
+            queue.extendVisibility(jobId, intervalMs * 2).catch(() => { });
+            tick();
+        }, intervalMs);
+    };
+    tick();
+    return () => {
+        stopped = true;
+        if (handle !== undefined)
+            clearTimeoutImpl(handle);
+    };
+}

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@crewhaus/queue-consumer",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Long-running consumer loop for the BATCH target — visibility-timeout-aware, SIGTERM-drains (Section 23 BATCH)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4",
-    "@crewhaus/idempotency-keys": "0.1.4",
-    "@crewhaus/queue-protocol": "0.1.4"
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/idempotency-keys": "0.1.5",
+    "@crewhaus/queue-protocol": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -34,5 +37,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,400 +0,0 @@
-import { afterEach, describe, expect, spyOn, test } from "bun:test";
-import { createInMemoryIdempotencyStore } from "@crewhaus/idempotency-keys";
-import { type Job, type QueueAdapter, createInMemoryQueue } from "@crewhaus/queue-protocol";
-import { type ConsumerObserver, QueueConsumerError, startConsumer } from "./index.js";
-
-describe("startConsumer", () => {
-  test("processes 50 jobs at concurrency 4 (T3 end-to-end)", async () => {
-    const queue = createInMemoryQueue<number>();
-    for (let i = 0; i < 50; i++) await queue.enqueue(i);
-
-    const seen: number[] = [];
-    const consumer = startConsumer<number, number>({
-      queue,
-      handler: async (input) => {
-        seen.push(input);
-        return input * 2;
-      },
-      concurrency: 4,
-      visibilityTimeoutMs: 5_000,
-    });
-
-    // Wait until all are ack'd or 5s.
-    const deadline = Date.now() + 5_000;
-    while (Date.now() < deadline) {
-      const stats = await queue.stats();
-      if (stats.acked >= 50 && stats.pending === 0) break;
-      await new Promise((r) => setTimeout(r, 10));
-    }
-    await consumer.drain();
-
-    const stats = await queue.stats();
-    expect(stats.acked).toBe(50);
-    expect(stats.pending).toBe(0);
-    expect(seen.sort((a, b) => a - b)).toEqual(Array.from({ length: 50 }, (_, i) => i));
-  });
-
-  test("transient failure → nack(transient) → retry succeeds (T3)", async () => {
-    const queue = createInMemoryQueue<{ id: number }>();
-    await queue.enqueue({ id: 7 });
-
-    let calls = 0;
-    const consumer = startConsumer<{ id: number }, string>({
-      queue,
-      handler: async (input) => {
-        calls += 1;
-        if (calls === 1) throw new Error("transient");
-        return `ok-${input.id}`;
-      },
-      concurrency: 1,
-      visibilityTimeoutMs: 5_000,
-      maxRetries: 3,
-    });
-
-    // Wait for ack + at least 2 calls.
-    const deadline = Date.now() + 3_000;
-    while (Date.now() < deadline) {
-      const stats = await queue.stats();
-      if (stats.acked === 1) break;
-      await new Promise((r) => setTimeout(r, 10));
-    }
-    await consumer.drain();
-
-    expect(calls).toBe(2);
-    const stats = await queue.stats();
-    expect(stats.acked).toBe(1);
-    expect(stats.deadLetter).toBe(0);
-  });
-
-  test("permanent failure (attempts >= maxRetries) → DLQ", async () => {
-    const queue = createInMemoryQueue<string>();
-    await queue.enqueue("doomed");
-
-    const consumer = startConsumer<string, string>({
-      queue,
-      handler: async () => {
-        throw new Error("permanent");
-      },
-      concurrency: 1,
-      visibilityTimeoutMs: 5_000,
-      maxRetries: 2,
-    });
-
-    const deadline = Date.now() + 3_000;
-    while (Date.now() < deadline) {
-      const stats = await queue.stats();
-      if (stats.deadLetter === 1) break;
-      await new Promise((r) => setTimeout(r, 10));
-    }
-    await consumer.drain();
-
-    const stats = await queue.stats();
-    expect(stats.deadLetter).toBe(1);
-    expect(stats.acked).toBe(0);
-  });
-
-  test("idempotency-store cache hit on retry — handler invoked once across attempts (T9)", async () => {
-    const queue = createInMemoryQueue<{ id: string }>();
-    const store = createInMemoryIdempotencyStore<string>();
-    await queue.enqueue({ id: "k1" });
-
-    let calls = 0;
-    let calls2 = 0;
-
-    // First consumer ack's the job — cache the result by jobId+attempt=1 key.
-    const c1 = startConsumer<{ id: string }, string>({
-      queue,
-      handler: async (input) => {
-        calls += 1;
-        return `result-for-${input.id}`;
-      },
-      concurrency: 1,
-      visibilityTimeoutMs: 5_000,
-      idempotencyStore: store,
-      idempotencyTtlMs: 60_000,
-    });
-    let deadline = Date.now() + 2_000;
-    while (Date.now() < deadline) {
-      if ((await queue.stats()).acked === 1) break;
-      await new Promise((r) => setTimeout(r, 10));
-    }
-    await c1.drain();
-
-    // Re-enqueue an identical job — but force a different jobId via a
-    // separate enqueue so attempt=1 is fresh; idempotency-keys keys on
-    // (jobId, attempt) so this should NOT hit the cache (different
-    // job).
-    await queue.enqueue({ id: "k1" });
-    const c2 = startConsumer<{ id: string }, string>({
-      queue,
-      handler: async (input) => {
-        calls2 += 1;
-        return `result-for-${input.id}`;
-      },
-      concurrency: 1,
-      visibilityTimeoutMs: 5_000,
-      idempotencyStore: store,
-      idempotencyTtlMs: 60_000,
-    });
-    deadline = Date.now() + 2_000;
-    while (Date.now() < deadline) {
-      if ((await queue.stats()).acked === 2) break;
-      await new Promise((r) => setTimeout(r, 10));
-    }
-    await c2.drain();
-
-    expect(calls).toBe(1);
-    expect(calls2).toBe(1);
-
-    // T9: same (jobId, attempt) → cache hit. Drive that branch by
-    // re-running handleOne synthetically: store.set then read back.
-    const key1 = "fixed-key";
-    let calls3 = 0;
-    const wrapped = async (input: string) => {
-      calls3 += 1;
-      return `unique-${Math.random()}`;
-    };
-    void wrapped;
-    // Direct store check — same key returns same value.
-    await store.set(key1, "cached", 60_000);
-    expect(await store.get(key1)).toBe("cached");
-    expect(await store.get(key1)).toBe("cached");
-  });
-
-  test("drain() blocks new pulls and lets in-flight finish (SIGTERM contract)", async () => {
-    const queue = createInMemoryQueue<string>();
-    for (let i = 0; i < 5; i++) await queue.enqueue(`j${i}`);
-
-    let inFlightDuringDrain = 0;
-    let onJobStartCount = 0;
-    const observer: ConsumerObserver<string, string> = {
-      onJobStart: () => {
-        onJobStartCount += 1;
-      },
-    };
-
-    const consumer = startConsumer<string, string>({
-      queue,
-      handler: async (input) => {
-        await new Promise((r) => setTimeout(r, 50));
-        return `done-${input}`;
-      },
-      concurrency: 2,
-      visibilityTimeoutMs: 5_000,
-      observer,
-    });
-
-    // Let a couple of jobs start.
-    await new Promise((r) => setTimeout(r, 30));
-    inFlightDuringDrain = consumer.inFlight();
-    expect(inFlightDuringDrain).toBeGreaterThan(0);
-
-    await consumer.drain();
-    expect(consumer.inFlight()).toBe(0);
-
-    // After drain: ack count >= jobs that started before drain.
-    const stats = await queue.stats();
-    expect(stats.acked).toBeGreaterThanOrEqual(inFlightDuringDrain);
-    expect(onJobStartCount).toBe(stats.acked);
-    // Pending jobs that hadn't been pulled yet remain.
-    expect(stats.pending + stats.acked).toBe(5);
-  });
-});
-
-describe("QueueConsumerError", () => {
-  test("carries the runtime code, stable name, and cause chain", () => {
-    const cause = new Error("adapter exploded");
-    const err = new QueueConsumerError("consumer failed", cause);
-    expect(err).toBeInstanceOf(Error);
-    expect(err.name).toBe("QueueConsumerError");
-    expect(err.code).toBe("runtime");
-    expect(err.message).toBe("consumer failed");
-    expect(err.cause).toBe(cause);
-    expect(err.toJSON()).toMatchObject({
-      name: "QueueConsumerError",
-      code: "runtime",
-      message: "consumer failed",
-      cause: { name: "Error", message: "adapter exploded" },
-    });
-  });
-
-  test("constructs without a cause", () => {
-    const err = new QueueConsumerError("no cause");
-    expect(err.cause).toBeUndefined();
-  });
-});
-
-describe("startConsumer — pull loop error surfacing", () => {
-  let stderrSpy: ReturnType<typeof spyOn> | undefined;
-
-  afterEach(() => {
-    stderrSpy?.mockRestore();
-    stderrSpy = undefined;
-  });
-
-  test("an unhandled error in the pull loop is written to stderr and stops the loop", async () => {
-    // Capture stderr so the loop-error log doesn't pollute test output AND we
-    // can assert it fired. No real stderr write, no real I/O.
-    const writes: string[] = [];
-    stderrSpy = spyOn(process.stderr, "write").mockImplementation((chunk: unknown): boolean => {
-      writes.push(String(chunk));
-      return true;
-    });
-
-    // A malformed adapter: `pull` resolves a non-array, so `pulled.length`
-    // throws a TypeError OUTSIDE the loop's pull try/catch (that try only
-    // guards the awaited pull call). This is the exact "rare loop error"
-    // path the catch handler exists for.
-    const badQueue: QueueAdapter<number> = {
-      kind: "bad",
-      pull: async () => null as unknown as ReadonlyArray<Job<number>>,
-      ack: async () => {},
-      nack: async () => {},
-      extendVisibility: async () => {},
-      stats: async () => ({ pending: 0, inFlight: 0, acked: 0, nacked: 0, deadLetter: 0 }),
-    };
-
-    const consumer = startConsumer<number, number>({
-      queue: badQueue,
-      handler: async (n) => n,
-      concurrency: 1,
-      visibilityTimeoutMs: 5_000,
-    });
-
-    // drain() awaits the (now-rejected-then-caught) loopPromise; it must
-    // resolve, not hang, because the catch handler swallows the throw.
-    await consumer.drain();
-
-    expect(writes.length).toBe(1);
-    expect(writes[0]).toContain("[queue-consumer] loop error:");
-    // The TypeError message about reading a property of null is surfaced.
-    expect(writes[0]).toMatch(/null|length/i);
-    expect(consumer.inFlight()).toBe(0);
-  });
-});
-
-describe("startConsumer — visibility renewal sidecar", () => {
-  test("fires extendVisibility on each renew tick and swallows renew failures", async () => {
-    // Deterministic timer control: capture scheduled callbacks instead of
-    // arming the real clock, so we drive renewal ticks by hand — no real
-    // timers, no leaked handles.
-    const scheduled: Array<{ id: number; fn: () => void; delay: number }> = [];
-    let nextId = 1;
-    const cleared: number[] = [];
-    const fakeSetTimeout = ((fn: () => void, delay?: number) => {
-      const id = nextId++;
-      scheduled.push({ id, fn, delay: delay ?? 0 });
-      return id as unknown as ReturnType<typeof setTimeout>;
-    }) as unknown as typeof setTimeout;
-    const fakeClearTimeout = ((handle: unknown) => {
-      cleared.push(handle as number);
-    }) as unknown as typeof clearTimeout;
-
-    // extendVisibility rejects so we also cover the `.catch(() => {})` swallow.
-    const extendCalls: Array<{ jobId: string; additionalMs: number }> = [];
-    let releaseHandler!: () => void;
-    const handlerGate = new Promise<void>((resolve) => {
-      releaseHandler = resolve;
-    });
-
-    const queue = createInMemoryQueue<string>();
-    await queue.enqueue("renew-job");
-    const baseExtend = queue.extendVisibility.bind(queue);
-    const renewQueue: QueueAdapter<string> = {
-      ...queue,
-      kind: queue.kind,
-      pull: queue.pull.bind(queue),
-      ack: queue.ack.bind(queue),
-      nack: queue.nack.bind(queue),
-      stats: queue.stats.bind(queue),
-      extendVisibility: async (jobId: string, additionalMs: number) => {
-        extendCalls.push({ jobId, additionalMs });
-        await baseExtend(jobId, additionalMs).catch(() => {});
-        // Force the renew-failure branch to exercise the swallowing catch.
-        throw new Error("extendVisibility failed (job already acked)");
-      },
-      enqueue: queue.enqueue.bind(queue),
-    } as unknown as QueueAdapter<string>;
-
-    const consumer = startConsumer<string, string>({
-      queue: renewQueue,
-      handler: async () => {
-        // Hold the job in-flight until we've driven a renew tick.
-        await handlerGate;
-        return "done";
-      },
-      concurrency: 1,
-      visibilityTimeoutMs: 5_000,
-      visibilityRenewIntervalMs: 1_000,
-      _setTimeout: fakeSetTimeout,
-      _clearTimeout: fakeClearTimeout,
-    });
-
-    // Wait until the handler is in-flight and the renew sidecar has armed
-    // its first timer (via the fake setTimeout).
-    const deadline = Date.now() + 2_000;
-    while (Date.now() < deadline && scheduled.length === 0) {
-      await new Promise((r) => setTimeout(r, 5));
-    }
-    expect(scheduled.length).toBeGreaterThan(0);
-
-    // Fire the first renew tick: this invokes extendVisibility(jobId, 2000)
-    // and re-arms the next tick.
-    const firstTick = scheduled.shift();
-    expect(firstTick).toBeDefined();
-    firstTick?.fn();
-    // Let the rejected extendVisibility promise settle through its catch.
-    await new Promise((r) => setTimeout(r, 5));
-
-    expect(extendCalls.length).toBeGreaterThanOrEqual(1);
-    // intervalMs (1000) * 2 is the additional visibility window the tick requests.
-    expect(extendCalls[0]?.additionalMs).toBe(2_000);
-    // jobId is whatever the in-memory adapter assigned to the single enqueued job.
-    expect(typeof extendCalls[0]?.jobId).toBe("string");
-    expect(extendCalls[0]?.jobId.length).toBeGreaterThan(0);
-    // The tick re-armed a follow-up renew timer.
-    expect(scheduled.length).toBeGreaterThanOrEqual(1);
-
-    // Release the handler so the job completes and stopRenew() clears the
-    // outstanding timer (covers the clearTimeout path).
-    releaseHandler();
-    await consumer.drain();
-    expect(cleared.length).toBeGreaterThanOrEqual(1);
-  });
-
-  test("stopRenew before any tick fires clears the armed timer", async () => {
-    const scheduled: Array<() => void> = [];
-    const cleared: number[] = [];
-    const fakeSetTimeout = ((fn: () => void) => {
-      scheduled.push(fn);
-      return scheduled.length as unknown as ReturnType<typeof setTimeout>;
-    }) as unknown as typeof setTimeout;
-    const fakeClearTimeout = ((handle: unknown) => {
-      cleared.push(handle as number);
-    }) as unknown as typeof clearTimeout;
-
-    const queue = createInMemoryQueue<string>();
-    await queue.enqueue("fast-job");
-
-    const consumer = startConsumer<string, string>({
-      queue,
-      // Resolves immediately — stopRenew() runs in the finally before any
-      // renew tick is driven, so the armed timer is cleared, not fired.
-      handler: async () => "ok",
-      concurrency: 1,
-      visibilityTimeoutMs: 5_000,
-      visibilityRenewIntervalMs: 1_000,
-      _setTimeout: fakeSetTimeout,
-      _clearTimeout: fakeClearTimeout,
-    });
-
-    const deadline = Date.now() + 2_000;
-    while (Date.now() < deadline && (await queue.stats()).acked === 0) {
-      await new Promise((r) => setTimeout(r, 5));
-    }
-    await consumer.drain();
-    expect((await queue.stats()).acked).toBe(1);
-    // The renew timer was armed then cleared on handler completion.
-    expect(cleared.length).toBeGreaterThanOrEqual(1);
-  });
-});

package/src/index.ts

@@ -1,250 +0,0 @@
-/**
- * Catalog R14 `queue-consumer` — Section 23 BATCH.
- *
- * Long-running consumer loop. Pulls jobs from any `QueueAdapter`, runs
- * the user's handler with `concurrency`-bounded parallelism, wraps each
- * call in an idempotency-key cache so retries hit cache, and acks /
- * nacks based on the handler's outcome.
- *
- * Visibility renewal: while a handler is running, a sidecar timer
- * extends the job's visibility every `visibilityRenewIntervalMs` until
- * either the handler completes or the consumer is told to stop. This
- * keeps long-running model calls from being yanked out from under the
- * worker by another consumer that thinks the lease expired.
- *
- * Retry policy:
- *   - handler throws + `attempt < maxRetries` → `nack(transient)` so
- *     the queue re-enqueues for the next consumer.
- *   - handler throws + `attempt >= maxRetries` → `nack(permanent)` so
- *     the queue moves the job to its DLQ.
- *   - handler resolves → `ack`.
- *
- * Drain semantics: `drain()` stops new pulls but lets in-flight handlers
- * complete + ack. `stop()` is `drain()` plus a wait — used by the
- * SIGTERM path so the daemon shuts down cleanly without orphaning
- * mid-flight jobs.
- */
-import { CrewhausError } from "@crewhaus/errors";
-import { type IdempotencyStore, idempotencyKey, withIdempotency } from "@crewhaus/idempotency-keys";
-import type { Job, NackReason, QueueAdapter } from "@crewhaus/queue-protocol";
-
-export class QueueConsumerError extends CrewhausError {
-  override readonly name = "QueueConsumerError";
-  constructor(message: string, cause?: unknown) {
-    super("runtime", message, cause);
-  }
-}
-
-export type ConsumerHandlerOutcome<TResult> =
-  | { kind: "ok"; value: TResult; fromCache: boolean }
-  | { kind: "fail"; reason: NackReason; error: unknown };
-
-export type ConsumerObserver<TInput, TResult> = {
-  onJobStart?(job: Job<TInput>): void;
-  onJobEnd?(job: Job<TInput>, outcome: ConsumerHandlerOutcome<TResult>): void;
-  /** Fires when drain begins. */
-  onDrainStart?(): void;
-  /** Fires after drain completes (no more in-flight). */
-  onDrainEnd?(): void;
-};
-
-export type ConsumerOptions<TInput, TResult> = {
-  readonly queue: QueueAdapter<TInput>;
-  readonly handler: (input: TInput, ctx: { key: string; job: Job<TInput> }) => Promise<TResult>;
-  readonly concurrency: number;
-  readonly visibilityTimeoutMs: number;
-  readonly visibilityRenewIntervalMs?: number;
-  readonly idempotencyStore?: IdempotencyStore<TResult>;
-  readonly idempotencyTtlMs?: number;
-  readonly maxRetries?: number;
-  /** Per-pull batch cap. Defaults to `concurrency`. */
-  readonly pullBatchSize?: number;
-  /** Wait between empty-queue pulls. Defaults to 100ms. */
-  readonly emptyQueuePollMs?: number;
-  readonly observer?: ConsumerObserver<TInput, TResult>;
-  /** Test seam — `setTimeout`/`clearTimeout` overrides for deterministic visibility renewal tests. */
-  readonly _setTimeout?: typeof setTimeout;
-  readonly _clearTimeout?: typeof clearTimeout;
-};
-
-export interface RunningConsumer {
-  /**
-   * Block until every in-flight handler completes; no new pulls happen
-   * after this is called. Idempotent — second call returns the same
-   * promise.
-   */
-  drain(): Promise<void>;
-  /**
-   * Start drain + return when finished. Convenience for SIGTERM paths.
-   * Equivalent to `drain()` today; left as a separate verb so future
-   * graceful-stop semantics (e.g. close adapter connections) can fit.
-   */
-  stop(): Promise<void>;
-  /** Diagnostic — currently in-flight job count. */
-  inFlight(): number;
-}
-
-const DEFAULT_VISIBILITY_RENEW_INTERVAL_MS = 5_000;
-const DEFAULT_IDEMPOTENCY_TTL_MS = 60_000;
-const DEFAULT_MAX_RETRIES = 3;
-const DEFAULT_EMPTY_QUEUE_POLL_MS = 100;
-
-export function startConsumer<TInput, TResult>(
-  opts: ConsumerOptions<TInput, TResult>,
-): RunningConsumer {
-  const visRenewMs = opts.visibilityRenewIntervalMs ?? DEFAULT_VISIBILITY_RENEW_INTERVAL_MS;
-  const idempotencyTtlMs = opts.idempotencyTtlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS;
-  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
-  const pullBatch = opts.pullBatchSize ?? opts.concurrency;
-  const emptyPollMs = opts.emptyQueuePollMs ?? DEFAULT_EMPTY_QUEUE_POLL_MS;
-  const ts = opts._setTimeout ?? setTimeout;
-  const tc = opts._clearTimeout ?? clearTimeout;
-
-  const wrappedHandler = opts.idempotencyStore
-    ? withIdempotency<{ input: TInput; job: Job<TInput> }, TResult>(
-        async ({ input, job }, key) => opts.handler(input, { key, job }),
-        { store: opts.idempotencyStore, ttlMs: idempotencyTtlMs },
-      )
-    : undefined;
-
-  let stopping = false;
-  let drainPromise: Promise<void> | undefined;
-  const inFlight = new Set<Promise<void>>();
-
-  // Pull loop runs as a background async function. It awaits available
-  // concurrency before pulling the next batch.
-  const loopPromise = (async () => {
-    while (!stopping) {
-      // Concurrency gate: wait until at least one slot is free.
-      while (inFlight.size >= opts.concurrency && !stopping) {
-        await Promise.race(inFlight);
-      }
-      if (stopping) break;
-
-      const want = Math.max(1, Math.min(pullBatch, opts.concurrency - inFlight.size));
-      let pulled: ReadonlyArray<Job<TInput>>;
-      try {
-        pulled = await opts.queue.pull({
-          maxBatch: want,
-          visibilityTimeoutMs: opts.visibilityTimeoutMs,
-        });
-      } catch (err) {
-        // Adapter blip — treat as empty pull, slow down a bit, retry.
-        await sleep(emptyPollMs * 2);
-        continue;
-      }
-
-      if (pulled.length === 0) {
-        await sleep(emptyPollMs);
-        continue;
-      }
-
-      for (const job of pulled) {
-        const p = handleOne(job).finally(() => {
-          inFlight.delete(p);
-        });
-        inFlight.add(p);
-      }
-    }
-  })().catch((err) => {
-    // Surface any unhandled error from the loop itself (rare — handlers
-    // already trap exceptions).
-    process.stderr.write(`[queue-consumer] loop error: ${(err as Error).message}\n`);
-  });
-
-  async function handleOne(job: Job<TInput>): Promise<void> {
-    opts.observer?.onJobStart?.(job);
-    const key = idempotencyKey(job.id, job.attempt);
-    const stopRenew = startVisibilityRenew(opts.queue, job.id, visRenewMs, ts, tc);
-    let outcome: ConsumerHandlerOutcome<TResult>;
-    try {
-      const r = wrappedHandler
-        ? await wrappedHandler({ input: job.input, job }, key)
-        : { value: await opts.handler(job.input, { key, job }), fromCache: false };
-      outcome = { kind: "ok", value: r.value, fromCache: r.fromCache };
-    } catch (err) {
-      const isLast = job.attempt >= maxRetries;
-      outcome = {
-        kind: "fail",
-        reason: isLast ? "permanent" : "transient",
-        error: err,
-      };
-    } finally {
-      stopRenew();
-    }
-    if (outcome.kind === "ok") {
-      try {
-        await opts.queue.ack(job.id);
-      } catch (err) {
-        // Best-effort: log + continue. Adapter ack failures don't reach
-        // userland; they'd surface as duplicate work on the next pull.
-      }
-    } else {
-      try {
-        await opts.queue.nack(job.id, outcome.reason);
-      } catch {
-        // Same rationale.
-      }
-    }
-    opts.observer?.onJobEnd?.(job, outcome);
-  }
-
-  async function drain(): Promise<void> {
-    if (drainPromise !== undefined) return drainPromise;
-    stopping = true;
-    opts.observer?.onDrainStart?.();
-    drainPromise = (async () => {
-      // First, let the pull loop notice the stop flag.
-      await loopPromise;
-      // Then wait for in-flight to finish.
-      while (inFlight.size > 0) {
-        await Promise.race(inFlight);
-      }
-      opts.observer?.onDrainEnd?.();
-    })();
-    return drainPromise;
-  }
-
-  return {
-    drain,
-    stop: drain,
-    inFlight: () => inFlight.size,
-  };
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-/**
- * Start a sidecar that calls `extendVisibility(jobId, ...)` every
- * `intervalMs` until the returned `stop()` is invoked. We pass the
- * timer functions explicitly so tests can drive them deterministically.
- */
-function startVisibilityRenew(
-  queue: QueueAdapter<unknown>,
-  jobId: string,
-  intervalMs: number,
-  setTimeoutImpl: typeof setTimeout,
-  clearTimeoutImpl: typeof clearTimeout,
-): () => void {
-  let stopped = false;
-  let handle: ReturnType<typeof setTimeoutImpl> | undefined;
-
-  const tick = (): void => {
-    if (stopped) return;
-    handle = setTimeoutImpl(() => {
-      if (stopped) return;
-      // Best-effort: a renew failure after the job is already ack'd is
-      // expected (extendVisibility throws unknown-jobId). Swallow.
-      queue.extendVisibility(jobId, intervalMs * 2).catch(() => {});
-      tick();
-    }, intervalMs);
-  };
-  tick();
-
-  return () => {
-    stopped = true;
-    if (handle !== undefined) clearTimeoutImpl(handle);
-  };
-}