@retinue/agentkit 0.1.0

package/dist/adapters/bullmq/export.d.ts

@@ -0,0 +1,31 @@
+/**
+ * BullMQ `ExportDispatcher` (#134).
+ *
+ * A third queue, and for the same reason extraction got its own: a hundred-page PDF render must not sit in
+ * front of a user's next message, and rendering is CPU-bound where a run waits on a provider. The id, escaping
+ * and timeout behaviour are `dispatcher.ts`'s, reused rather than re-derived — the length-prefix fix exists
+ * because `${tenant}-${id}` is *ambiguous*, and a second implementation is a second chance to forget that.
+ */
+import type { ExportDispatcher } from "../../export/index.js";
+import { type JobDispatcherOptions } from "./dispatcher.js";
+/** Hyphen, not a colon: BullMQ rejects a queue name containing `:` outright. See `RUN_QUEUE_NAME`. */
+export declare const EXPORT_QUEUE_NAME = "agentkit-exports";
+export declare const EXPORT_JOB_NAME = "export";
+export type ExportJobData = {
+    readonly tenantId: string;
+    readonly exportId: string;
+};
+export interface ExportQueue {
+    add(name: string, data: ExportJobData, opts?: {
+        readonly jobId?: string;
+        readonly attempts?: number;
+    }): Promise<unknown>;
+    close?(): Promise<void>;
+}
+/** Tenant-qualified and unambiguous, built by the same function a run's id is. */
+export declare const exportJobId: (input: {
+    readonly tenantId: string;
+    readonly exportId: string;
+}) => string;
+export declare const createBullMqExportDispatcher: (queue: ExportQueue, options?: JobDispatcherOptions) => ExportDispatcher;
+//# sourceMappingURL=export.d.ts.map

package/dist/adapters/bullmq/export.js

@@ -0,0 +1,53 @@
+/**
+ * BullMQ `ExportDispatcher` (#134).
+ *
+ * A third queue, and for the same reason extraction got its own: a hundred-page PDF render must not sit in
+ * front of a user's next message, and rendering is CPU-bound where a run waits on a provider. The id, escaping
+ * and timeout behaviour are `dispatcher.ts`'s, reused rather than re-derived — the length-prefix fix exists
+ * because `${tenant}-${id}` is *ambiguous*, and a second implementation is a second chance to forget that.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { QUEUE_ATTEMPTS, runJobId } from "./dispatcher.js";
+/** Hyphen, not a colon: BullMQ rejects a queue name containing `:` outright. See `RUN_QUEUE_NAME`. */
+export const EXPORT_QUEUE_NAME = "agentkit-exports";
+export const EXPORT_JOB_NAME = "export";
+/** Tenant-qualified and unambiguous, built by the same function a run's id is. */
+export const exportJobId = (input) => runJobId({ tenantId: input.tenantId, runId: input.exportId });
+const unavailable = (cause) => new AgentPlatformError({
+    code: "provider_unavailable",
+    message: "Could not enqueue the export: the job queue is unreachable",
+    retryable: true,
+}, { cause });
+export const createBullMqExportDispatcher = (queue, options = {}) => {
+    const timeoutMs = options.enqueueTimeoutMs ?? 5_000;
+    return {
+        async enqueueExport({ tenantId, exportId }) {
+            const add = queue.add(EXPORT_JOB_NAME, { tenantId, exportId }, 
+            // The dedup that matters: an export claimed once must be rendered once, and the store's unique
+            // constraint already guarantees one row per (artifact, version, format) — this stops a duplicated
+            // *message* becoming a second render of that row.
+            { jobId: exportJobId({ tenantId, exportId }), attempts: QUEUE_ATTEMPTS });
+            let timer;
+            try {
+                await Promise.race([
+                    add,
+                    new Promise((_resolve, reject) => {
+                        // A connection that is open-but-dead fails neither fast nor at all, so the timeout is part of the
+                        // guarantee rather than a nicety.
+                        timer = setTimeout(() => reject(unavailable(new Error(`enqueue timed out after ${timeoutMs}ms`))), timeoutMs);
+                    }),
+                ]);
+            }
+            catch (error) {
+                throw error instanceof AgentPlatformError ? error : unavailable(error);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                // The losing promise must not become an unhandled rejection when the timeout wins.
+                void Promise.resolve(add).catch(() => undefined);
+            }
+        },
+    };
+};
+//# sourceMappingURL=export.js.map

package/dist/adapters/bullmq/extraction.d.ts

@@ -0,0 +1,42 @@
+/**
+ * BullMQ `ExtractionDispatcher` (#131) — the durable enqueue behind document extraction.
+ *
+ * Its own queue, not the run queue, and that is the decision worth stating. A shared queue would let a
+ * hundred-page PDF sit in front of a user's next message, which is precisely what AC-2 forbids; and the two
+ * kinds of work want different concurrency, because extraction is CPU-bound and a run is mostly waiting on a
+ * provider. Separate queues let a deployment give extraction one worker and runs ten.
+ *
+ * The id, escaping and timeout behaviour are `dispatcher.ts`'s, reused rather than re-derived: the ambiguity
+ * bug that `runJobId`'s length prefix fixes is a property of tenant-qualified ids in general, not of runs.
+ */
+import type { ExtractionDispatcher } from "../../documents/index.js";
+import { type JobDispatcherOptions } from "./dispatcher.js";
+/** Hyphen, not a colon: BullMQ rejects a queue name containing `:` outright. See `RUN_QUEUE_NAME`. */
+export declare const EXTRACTION_QUEUE_NAME = "agentkit-extractions";
+export declare const EXTRACTION_JOB_NAME = "extract";
+export type ExtractionJobData = {
+    readonly tenantId: string;
+    readonly fileId: string;
+};
+/** The queue surface this adapter needs, structurally satisfied by BullMQ's `Queue`. */
+export interface ExtractionQueue {
+    add(name: string, data: ExtractionJobData, opts?: {
+        readonly jobId?: string;
+        readonly attempts?: number;
+    }): Promise<unknown>;
+    close?(): Promise<void>;
+}
+/**
+ * The job id, tenant-qualified and unambiguous.
+ *
+ * Deliberately the same construction as a run's — `runJobId` takes the second part under the name `runId`,
+ * and the file id goes there. Sharing it rather than writing a near-copy is the point: the length prefix
+ * exists because `${tenant}-${id}` is *ambiguous* (tenant `a-b`/file `c` and tenant `a`/file `b-c` collide),
+ * and a second implementation is a second chance to forget that.
+ */
+export declare const extractionJobId: (input: {
+    readonly tenantId: string;
+    readonly fileId: string;
+}) => string;
+export declare const createBullMqExtractionDispatcher: (queue: ExtractionQueue, options?: JobDispatcherOptions) => ExtractionDispatcher;
+//# sourceMappingURL=extraction.d.ts.map

package/dist/adapters/bullmq/extraction.js

@@ -0,0 +1,63 @@
+/**
+ * BullMQ `ExtractionDispatcher` (#131) — the durable enqueue behind document extraction.
+ *
+ * Its own queue, not the run queue, and that is the decision worth stating. A shared queue would let a
+ * hundred-page PDF sit in front of a user's next message, which is precisely what AC-2 forbids; and the two
+ * kinds of work want different concurrency, because extraction is CPU-bound and a run is mostly waiting on a
+ * provider. Separate queues let a deployment give extraction one worker and runs ten.
+ *
+ * The id, escaping and timeout behaviour are `dispatcher.ts`'s, reused rather than re-derived: the ambiguity
+ * bug that `runJobId`'s length prefix fixes is a property of tenant-qualified ids in general, not of runs.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { QUEUE_ATTEMPTS, runJobId } from "./dispatcher.js";
+/** Hyphen, not a colon: BullMQ rejects a queue name containing `:` outright. See `RUN_QUEUE_NAME`. */
+export const EXTRACTION_QUEUE_NAME = "agentkit-extractions";
+export const EXTRACTION_JOB_NAME = "extract";
+/**
+ * The job id, tenant-qualified and unambiguous.
+ *
+ * Deliberately the same construction as a run's — `runJobId` takes the second part under the name `runId`,
+ * and the file id goes there. Sharing it rather than writing a near-copy is the point: the length prefix
+ * exists because `${tenant}-${id}` is *ambiguous* (tenant `a-b`/file `c` and tenant `a`/file `b-c` collide),
+ * and a second implementation is a second chance to forget that.
+ */
+export const extractionJobId = (input) => runJobId({ tenantId: input.tenantId, runId: input.fileId });
+const unavailable = (cause) => new AgentPlatformError({
+    code: "provider_unavailable",
+    message: "Could not enqueue the extraction: the job queue is unreachable",
+    retryable: true,
+}, { cause });
+export const createBullMqExtractionDispatcher = (queue, options = {}) => {
+    const timeoutMs = options.enqueueTimeoutMs ?? 5_000;
+    return {
+        async enqueueExtraction({ tenantId, fileId }) {
+            const add = queue.add(EXTRACTION_JOB_NAME, { tenantId, fileId }, 
+            // The dedup that matters here: an upload retried by a client must not extract the same file twice.
+            // `attempts: 1` for the same reason the run queue uses it — the caller owns retries, and multiplying
+            // two retry policies gives backoff neither layer intended.
+            { jobId: extractionJobId({ tenantId, fileId }), attempts: QUEUE_ATTEMPTS });
+            let timer;
+            try {
+                await Promise.race([
+                    add,
+                    new Promise((_resolve, reject) => {
+                        // A connection that is open-but-dead fails neither fast nor at all, so the timeout is part of
+                        // the guarantee rather than a nicety.
+                        timer = setTimeout(() => reject(unavailable(new Error(`enqueue timed out after ${timeoutMs}ms`))), timeoutMs);
+                    }),
+                ]);
+            }
+            catch (error) {
+                throw error instanceof AgentPlatformError ? error : unavailable(error);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                // The losing promise must not become an unhandled rejection when the timeout wins.
+                void Promise.resolve(add).catch(() => undefined);
+            }
+        },
+    };
+};
+//# sourceMappingURL=extraction.js.map

package/dist/adapters/bullmq/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * BullMQ/Redis adapters — the durable job queue behind `JobDispatcher` (#105).
+ *
+ * `bullmq` and `ioredis` are imported only inside this directory, which is where the dependency
+ * boundary checker expects an adapter's client coupling to live.
+ */
+export * from "./dispatcher.js";
+export * from "./extraction.js";
+export * from "./export.js";
+export * from "./queue.js";
+export * from "./lock.js";
+export * from "./consumer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/bullmq/index.js

@@ -0,0 +1,13 @@
+/**
+ * BullMQ/Redis adapters — the durable job queue behind `JobDispatcher` (#105).
+ *
+ * `bullmq` and `ioredis` are imported only inside this directory, which is where the dependency
+ * boundary checker expects an adapter's client coupling to live.
+ */
+export * from "./dispatcher.js";
+export * from "./extraction.js";
+export * from "./export.js";
+export * from "./queue.js";
+export * from "./lock.js";
+export * from "./consumer.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/bullmq/lock.d.ts

@@ -0,0 +1,77 @@
+import type { DistributedLockStore } from "../../runtime/index.js";
+/**
+ * The Redis surface this lock needs, kept narrow deliberately.
+ *
+ * Not `ioredis`'s `Redis` directly: its `set` is heavily overloaded, so relying on structural
+ * compatibility would make an accidental argument-order change typecheck. `createIoredisLockClient`
+ * adapts it explicitly instead.
+ */
+export interface LockRedis {
+    /** `SET key value PX ttl NX` — returns "OK" when it took the lock, null when someone else holds it. */
+    setIfAbsent(key: string, value: string, ttlMs: number): Promise<string | null>;
+    /** `EVAL script numKeys key arg…` — returns the script's integer reply. */
+    runScript(script: string, key: string, args: readonly string[]): Promise<number>;
+}
+/**
+ * Release, guarded by the token.
+ *
+ * A plain `DEL` is the bug this exists to avoid: a holder whose lease expired *while it was still
+ * working* would delete its successor's lock, and two workers would then believe they hold the
+ * conversation. That turns "the lock is slow" into "the lock is broken", which is AC-2.
+ */
+export declare const RELEASE_SCRIPT = "\nif redis.call('get', KEYS[1]) == ARGV[1] then\n  return redis.call('del', KEYS[1])\nend\nreturn 0";
+/**
+ * Renew, guarded by the same token.
+ *
+ * `PEXPIRE` on its own is the same bug one step later: a stale holder would extend a lock it no longer
+ * owns, keeping the rightful holder out.
+ */
+export declare const RENEW_SCRIPT = "\nif redis.call('get', KEYS[1]) == ARGV[1] then\n  return redis.call('pexpire', KEYS[1], ARGV[2])\nend\nreturn 0";
+/** What the adapter actually returns. Wider than the port, which has no `renew`. */
+export type LockHandle = {
+    /** Compare-and-delete. Safe to call twice; safe to call after expiry. */
+    readonly released: () => Promise<void>;
+    /** Compare-and-extend. `false` means the lock is no longer ours — stop working. */
+    readonly renew: (ttlMs?: number) => Promise<boolean>;
+    /** Unique per acquisition, not per worker. See `createRedisLockStore`. */
+    readonly token: string;
+    readonly key: string;
+};
+export type RedisLockOptions = {
+    /** Namespace, so a lock cannot collide with the queue's own keys. */
+    readonly keyPrefix?: string;
+    /** Injectable for tests. Production uses `crypto.randomUUID`. */
+    readonly newToken?: () => string;
+};
+export type RedisLockStore = DistributedLockStore & {
+    acquire(key: string, ttlMs: number): Promise<LockHandle | null>;
+};
+export declare const createRedisLockStore: (redis: LockRedis, options?: RedisLockOptions) => RedisLockStore;
+/**
+ * Adapts `ioredis` explicitly. The argument order of `SET key value PX ttl NX` matters and is easy to
+ * transpose, so it is written once here rather than at every call site.
+ */
+export declare const createIoredisLockClient: (redis: {
+    set(...args: readonly (string | number)[]): Promise<string | null>;
+    eval(...args: readonly (string | number)[]): Promise<unknown>;
+}) => LockRedis;
+export type RenewalHandle = {
+    readonly stop: () => void;
+    readonly lost: () => boolean;
+};
+/**
+ * Heartbeat-driven renewal (AC-4).
+ *
+ * Renews on a timer and **stops the moment a renewal fails**. That is the important half: a renewal
+ * that returns false means the lock is no longer ours, and continuing to renew would be asserting
+ * ownership we lost. `lost()` lets the worker notice and stand down rather than carrying on with a
+ * lock it does not hold — the same shape as the worker's existing `ClaimLostError` path.
+ *
+ * Renews at a fraction of the TTL rather than at the TTL, so one slow round trip does not drop a lock
+ * that is still legitimately held.
+ */
+export declare const startLockRenewal: (handle: LockHandle, options: {
+    readonly ttlMs: number;
+    readonly everyMs?: number;
+}) => RenewalHandle;
+//# sourceMappingURL=lock.d.ts.map

package/dist/adapters/bullmq/lock.js

@@ -0,0 +1,126 @@
+/**
+ * Redis `DistributedLockStore` (#106) — per-conversation mutual exclusion across worker processes.
+ *
+ * **Read this before relying on it for safety, because you should not.** This is a single-instance
+ * lock. Under a Redis failover, a network partition, or a clock jump, two holders are possible. It is
+ * *not* a consensus lock and no amount of care in this file makes it one.
+ *
+ * The safety property lives in the database, where #98 put it: the run coordinator's slot table with
+ * `SELECT … FOR UPDATE`, and `RunStore`'s lease compare-and-set. The worker already says as much where
+ * it declares this dependency — *"Optional belt-and-suspenders mutual exclusion around the atomic
+ * claim"* — and `locks?` is optional precisely so a deployment can run without it.
+ *
+ * What this buys is **contention**: workers that would otherwise all pile onto the same slot row back
+ * off at Redis instead. That is worth having on a hot path, and it is all it is worth.
+ */
+import { randomUUID } from "node:crypto";
+/**
+ * Release, guarded by the token.
+ *
+ * A plain `DEL` is the bug this exists to avoid: a holder whose lease expired *while it was still
+ * working* would delete its successor's lock, and two workers would then believe they hold the
+ * conversation. That turns "the lock is slow" into "the lock is broken", which is AC-2.
+ */
+export const RELEASE_SCRIPT = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('del', KEYS[1])
+end
+return 0`;
+/**
+ * Renew, guarded by the same token.
+ *
+ * `PEXPIRE` on its own is the same bug one step later: a stale holder would extend a lock it no longer
+ * owns, keeping the rightful holder out.
+ */
+export const RENEW_SCRIPT = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('pexpire', KEYS[1], ARGV[2])
+end
+return 0`;
+export const createRedisLockStore = (redis, options = {}) => {
+    const prefix = options.keyPrefix ?? "agentkit-lock:";
+    // Per *acquisition*, not per worker. A worker that acquires, loses the lease, and re-acquires must
+    // not be able to release the intervening holder's lock with a handle it kept from last time.
+    const newToken = options.newToken ?? (() => randomUUID());
+    return {
+        async acquire(key, ttlMs) {
+            const namespaced = `${prefix}${key}`;
+            const token = newToken();
+            // NX is the mutual exclusion; PX is AC-3. Together they mean a dead holder's lock frees itself
+            // with no reaper, no operator, and no second liveness clock to drift out of step.
+            const acquired = await redis.setIfAbsent(namespaced, token, ttlMs);
+            if (acquired === null)
+                return null;
+            let releasedAlready = false;
+            return {
+                token,
+                key: namespaced,
+                async released() {
+                    // Idempotent: a caller that releases in a `finally` after an error path may well call twice,
+                    // and the second call must not become a delete of whatever holds the key by then.
+                    if (releasedAlready)
+                        return;
+                    releasedAlready = true;
+                    await redis.runScript(RELEASE_SCRIPT, namespaced, [token]);
+                },
+                async renew(nextTtlMs = ttlMs) {
+                    if (releasedAlready)
+                        return false;
+                    const extended = await redis.runScript(RENEW_SCRIPT, namespaced, [token, String(nextTtlMs)]);
+                    return extended === 1;
+                },
+            };
+        },
+    };
+};
+/**
+ * Adapts `ioredis` explicitly. The argument order of `SET key value PX ttl NX` matters and is easy to
+ * transpose, so it is written once here rather than at every call site.
+ */
+export const createIoredisLockClient = (redis) => ({
+    async setIfAbsent(key, value, ttlMs) {
+        return redis.set(key, value, "PX", Math.max(1, Math.floor(ttlMs)), "NX");
+    },
+    async runScript(script, key, args) {
+        const reply = await redis.eval(script, 1, key, ...args);
+        return Number(reply ?? 0);
+    },
+});
+/**
+ * Heartbeat-driven renewal (AC-4).
+ *
+ * Renews on a timer and **stops the moment a renewal fails**. That is the important half: a renewal
+ * that returns false means the lock is no longer ours, and continuing to renew would be asserting
+ * ownership we lost. `lost()` lets the worker notice and stand down rather than carrying on with a
+ * lock it does not hold — the same shape as the worker's existing `ClaimLostError` path.
+ *
+ * Renews at a fraction of the TTL rather than at the TTL, so one slow round trip does not drop a lock
+ * that is still legitimately held.
+ */
+export const startLockRenewal = (handle, options) => {
+    const everyMs = options.everyMs ?? Math.max(1, Math.floor(options.ttlMs / 3));
+    let lost = false;
+    const timer = setInterval(() => {
+        void handle
+            .renew(options.ttlMs)
+            .then((ok) => {
+            if (!ok) {
+                lost = true;
+                clearInterval(timer);
+            }
+        })
+            .catch(() => {
+            // A failed round trip is not proof the lock is gone, but it is not proof it is held either.
+            // Treated as lost, because the alternative is a worker that keeps working on a maybe.
+            lost = true;
+            clearInterval(timer);
+        });
+    }, everyMs);
+    // Never hold the process open: a renewal timer must not be the reason a worker cannot exit.
+    timer.unref?.();
+    return {
+        stop: () => clearInterval(timer),
+        lost: () => lost,
+    };
+};
+//# sourceMappingURL=lock.js.map

package/dist/adapters/bullmq/queue.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The real BullMQ queue and its connection policy (#105).
+ *
+ * Separate from `dispatcher.ts` so the dispatcher stays testable without Redis, and so the connection
+ * decisions — which are the interesting part — sit in one place with their reasons.
+ */
+import { Queue } from "bullmq";
+import { Redis } from "ioredis";
+import { type JobQueue } from "./dispatcher.js";
+export type RunQueueOptions = {
+    readonly url: string;
+    /** Ceiling on establishing a connection. */
+    readonly connectTimeoutMs?: number;
+    /** Completed/failed jobs to retain. Retained, not zero — see below. */
+    readonly keepCompleted?: number;
+    readonly keepFailed?: number;
+};
+/**
+ * `ioredis` options chosen for a *producer*, which wants to fail fast.
+ *
+ * `enableOfflineQueue: false` is the one AC-4 turns on. By default ioredis buffers commands while
+ * disconnected, so `queue.add()` would sit there until the connection came back — the hang the AC
+ * names. With it off, the command rejects immediately and the dispatcher can wrap that into a typed
+ * error the API layer can turn into a real response.
+ *
+ * `maxRetriesPerRequest: 1` for the same reason: a producer would rather tell the caller now than
+ * retry silently behind a request that is already waiting. Note this is deliberately **not** the right
+ * setting for a BullMQ *worker* connection, which needs `maxRetriesPerRequest: null` for its blocking
+ * reads — a worker built here would need its own connection, not this one.
+ *
+ * `retryStrategy` backs off with jitter and gives up climbing at 2s, so a flapping Redis produces a
+ * steady trickle of reconnects rather than a thundering herd from every process at once.
+ */
+export declare const createRunQueueConnection: (options: RunQueueOptions) => Redis;
+/**
+ * The run queue.
+ *
+ * `removeOnComplete` keeps a bounded history rather than zero. Two reasons: AC-5's counts are more
+ * useful with a completed window, and a zero-retention queue makes it tempting to read `jobId` dedup
+ * as durable idempotency — it is not, since a removed job's id is immediately reusable. What stops a
+ * finished run being re-executed is `RunStore`, not this.
+ *
+ * `attempts` comes from the shared constant so the queue and the dispatcher cannot disagree about
+ * whose retry policy is in force (AC-3).
+ */
+export declare const createBullMqRunQueue: (options: RunQueueOptions) => JobQueue & {
+    readonly queue: Queue;
+    close(): Promise<void>;
+};
+//# sourceMappingURL=queue.d.ts.map

package/dist/adapters/bullmq/queue.js

@@ -0,0 +1,81 @@
+/**
+ * The real BullMQ queue and its connection policy (#105).
+ *
+ * Separate from `dispatcher.ts` so the dispatcher stays testable without Redis, and so the connection
+ * decisions — which are the interesting part — sit in one place with their reasons.
+ */
+import { Queue } from "bullmq";
+import { Redis } from "ioredis";
+import { QUEUE_ATTEMPTS, RUN_QUEUE_NAME } from "./dispatcher.js";
+/**
+ * `ioredis` options chosen for a *producer*, which wants to fail fast.
+ *
+ * `enableOfflineQueue: false` is the one AC-4 turns on. By default ioredis buffers commands while
+ * disconnected, so `queue.add()` would sit there until the connection came back — the hang the AC
+ * names. With it off, the command rejects immediately and the dispatcher can wrap that into a typed
+ * error the API layer can turn into a real response.
+ *
+ * `maxRetriesPerRequest: 1` for the same reason: a producer would rather tell the caller now than
+ * retry silently behind a request that is already waiting. Note this is deliberately **not** the right
+ * setting for a BullMQ *worker* connection, which needs `maxRetriesPerRequest: null` for its blocking
+ * reads — a worker built here would need its own connection, not this one.
+ *
+ * `retryStrategy` backs off with jitter and gives up climbing at 2s, so a flapping Redis produces a
+ * steady trickle of reconnects rather than a thundering herd from every process at once.
+ */
+export const createRunQueueConnection = (options) => new Redis(options.url, {
+    enableOfflineQueue: false,
+    maxRetriesPerRequest: 1,
+    connectTimeout: options.connectTimeoutMs ?? 3_000,
+    lazyConnect: true,
+    retryStrategy: (attempt) => {
+        const base = Math.min(2_000, 100 * 2 ** Math.min(attempt, 5));
+        // Deterministic-ish jitter without Math.random, so a retry schedule is reproducible from the
+        // attempt number when reading logs.
+        return base - (base * (attempt % 4)) / 16;
+    },
+});
+/**
+ * The run queue.
+ *
+ * `removeOnComplete` keeps a bounded history rather than zero. Two reasons: AC-5's counts are more
+ * useful with a completed window, and a zero-retention queue makes it tempting to read `jobId` dedup
+ * as durable idempotency — it is not, since a removed job's id is immediately reusable. What stops a
+ * finished run being re-executed is `RunStore`, not this.
+ *
+ * `attempts` comes from the shared constant so the queue and the dispatcher cannot disagree about
+ * whose retry policy is in force (AC-3).
+ */
+export const createBullMqRunQueue = (options) => {
+    const connection = createRunQueueConnection(options);
+    const queue = new Queue(RUN_QUEUE_NAME, {
+        connection,
+        defaultJobOptions: {
+            attempts: QUEUE_ATTEMPTS,
+            removeOnComplete: { count: options.keepCompleted ?? 1_000 },
+            removeOnFail: { count: options.keepFailed ?? 5_000 },
+        },
+    });
+    return {
+        queue,
+        add: (name, data, opts) => queue.add(name, data, opts),
+        getJobCounts: (...types) => queue.getJobCounts(...types),
+        /**
+         * Exposed so the dispatcher can clear a **finished** job holding a reusable id (#156).
+         *
+         * This object deliberately narrows the BullMQ `Queue` to the few methods the port needs, which is right — but
+         * it meant adding `getJob` to `JobQueue` and to the dispatcher changed nothing at all, because the method was
+         * never on the object the dispatcher received. The fix type-checked, the test against a raw `Queue` passed,
+         * and the real deployment silently kept the old behaviour: every approval resume still sat in `queued`.
+         *
+         * A narrowing wrapper is a second place every capability has to be added, and forgetting is invisible.
+         */
+        getJob: (jobId) => queue.getJob(jobId),
+        async close() {
+            await queue.close();
+            // The queue closes its own connection only when it created it; this one was injected.
+            await connection.quit().catch(() => undefined);
+        },
+    };
+};
+//# sourceMappingURL=queue.js.map

package/dist/adapters/memory/artifact-exports.d.ts

@@ -0,0 +1,11 @@
+/**
+ * In-memory `ArtifactExportStore` — the reference implementation (#134).
+ *
+ * The only interesting behaviour is `claim`, and it is interesting for one reason: **it must be a claim, not
+ * an insert.** Two requests for the same PDF must produce one render, and the second must be told so rather
+ * than starting a duplicate. A blind insert would render the same document twice and leave two rows pointing
+ * at two identical files.
+ */
+import type { ArtifactExportStore } from "../../persistence/index.js";
+export declare const createMemoryArtifactExportStore: () => ArtifactExportStore;
+//# sourceMappingURL=artifact-exports.d.ts.map