@crewhaus/queue-protocol 0.1.4 → 0.1.5

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Section 30 — Postgres adapter for `@crewhaus/queue-protocol`. Uses
+ * advisory locks + a job table for visibility timeouts:
+ *   pull → SELECT … FOR UPDATE SKIP LOCKED
+ *   ack → DELETE FROM jobs WHERE id = $1
+ *   nack(transient) → UPDATE jobs SET visibility_expires_at = NOW()
+ *   nack(permanent) → INSERT INTO dead_letter_jobs + DELETE
+ *   extendVisibility → UPDATE jobs SET visibility_expires_at = NOW() + ...
+ *
+ * v0 throws when `pg` isn't installed; the contract holds with a stub
+ * client.
+ */
+import type { QueueAdapter } from "../index";
+export type PostgresAdapterOptions = {
+    readonly tableName: string;
+    readonly deadLetterTable?: string;
+    readonly _client?: PostgresClientLike;
+};
+export type PostgresClientLike = {
+    query<T = unknown>(text: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+};
+export declare function createPostgresAdapter<TInput = unknown>(opts: PostgresAdapterOptions): QueueAdapter<TInput>;

package/dist/adapters/postgres.js

@@ -0,0 +1,87 @@
+import { QueueProtocolError } from "../index";
+export function createPostgresAdapter(opts) {
+    if (!opts.tableName)
+        throw new QueueProtocolError("postgres adapter requires tableName");
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(opts.tableName)) {
+        throw new QueueProtocolError(`postgres adapter: invalid tableName "${opts.tableName}"`);
+    }
+    const client = opts._client ?? requireClient();
+    let acked = 0;
+    let nacked = 0;
+    let deadLetter = 0;
+    const dlqTable = opts.deadLetterTable;
+    return {
+        kind: "postgres",
+        async pull(pullOpts) {
+            const visibilitySec = Math.ceil((pullOpts.visibilityTimeoutMs ?? 60_000) / 1000);
+            const result = await client.query(`WITH leased AS (
+          SELECT id FROM ${opts.tableName}
+          WHERE visibility_expires_at <= NOW()
+          ORDER BY enqueued_at ASC
+          LIMIT $1
+          FOR UPDATE SKIP LOCKED
+        )
+        UPDATE ${opts.tableName} t
+        SET visibility_expires_at = NOW() + INTERVAL '${visibilitySec} seconds',
+            attempt = attempt + 1
+        FROM leased
+        WHERE t.id = leased.id
+        RETURNING t.id, t.payload, t.enqueued_at, t.visibility_expires_at, t.attempt`, [pullOpts.maxBatch]);
+            const out = [];
+            for (const row of result.rows) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(row.payload);
+                }
+                catch {
+                    parsed = row.payload;
+                }
+                out.push({
+                    id: row.id,
+                    input: parsed,
+                    enqueuedAt: new Date(row.enqueued_at).toISOString(),
+                    visibilityExpiresAt: new Date(row.visibility_expires_at).toISOString(),
+                    attempt: row.attempt,
+                });
+            }
+            return out;
+        },
+        async ack(jobId) {
+            await client.query(`DELETE FROM ${opts.tableName} WHERE id = $1`, [jobId]);
+            acked++;
+        },
+        async nack(jobId, reason) {
+            if (reason === "permanent" && dlqTable) {
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(dlqTable)) {
+                    throw new QueueProtocolError(`postgres adapter: invalid deadLetterTable "${dlqTable}"`);
+                }
+                await client.query(`INSERT INTO ${dlqTable} (id, payload, enqueued_at)
+           SELECT id, payload, enqueued_at FROM ${opts.tableName} WHERE id = $1`, [jobId]);
+                await client.query(`DELETE FROM ${opts.tableName} WHERE id = $1`, [jobId]);
+                deadLetter++;
+            }
+            else {
+                await client.query(`UPDATE ${opts.tableName} SET visibility_expires_at = NOW() WHERE id = $1`, [jobId]);
+            }
+            nacked++;
+        },
+        async extendVisibility(jobId, additionalMs) {
+            const sec = Math.ceil(additionalMs / 1000);
+            await client.query(`UPDATE ${opts.tableName} SET visibility_expires_at = NOW() + INTERVAL '${sec} seconds' WHERE id = $1`, [jobId]);
+        },
+        async stats() {
+            const pendingRes = await client.query(`SELECT COUNT(*)::text AS count FROM ${opts.tableName} WHERE visibility_expires_at <= NOW()`);
+            const inFlightRes = await client.query(`SELECT COUNT(*)::text AS count FROM ${opts.tableName} WHERE visibility_expires_at > NOW()`);
+            return {
+                pending: Number.parseInt(pendingRes.rows[0]?.count ?? "0", 10),
+                inFlight: Number.parseInt(inFlightRes.rows[0]?.count ?? "0", 10),
+                acked,
+                nacked,
+                deadLetter,
+            };
+        },
+    };
+}
+function requireClient() {
+    throw new QueueProtocolError("postgres adapter requires `pg` to be installed and DATABASE_URL configured. Pass an explicit `_client` to use a stub.");
+}

package/dist/adapters/redis-streams.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Section 30 — Redis Streams adapter for `@crewhaus/queue-protocol`.
+ *
+ * Maps to Redis Streams + consumer groups:
+ *   pull → XREADGROUP
+ *   ack → XACK
+ *   nack(transient) → XADD back to the stream tail
+ *   nack(permanent) → XADD to the dead-letter stream + XACK on main
+ *   extendVisibility → no-op (Redis Streams uses pending-list min-idle-time
+ *                     instead of per-message visibility timeouts; consumers
+ *                     refresh by re-reading from the pending list)
+ *
+ * v0 throws when `ioredis` is not installed; the contract is correct +
+ * tested with stub clients.
+ */
+import type { QueueAdapter } from "../index";
+export type RedisStreamsAdapterOptions = {
+    readonly streamKey: string;
+    readonly consumerGroup: string;
+    readonly consumerName: string;
+    readonly deadLetterStream?: string;
+    readonly _client?: RedisClientLike;
+};
+export type RedisClientLike = {
+    xreadgroup(group: string, consumer: string, count: number, blockMs: number, streamKey: string, id: string): Promise<Array<{
+        stream: string;
+        messages: Array<{
+            id: string;
+            fields: Record<string, string>;
+        }>;
+    }> | null>;
+    xack(streamKey: string, group: string, ...ids: string[]): Promise<number>;
+    xadd(streamKey: string, id: string, ...fields: string[]): Promise<string>;
+};
+export declare function createRedisStreamsAdapter<TInput = unknown>(opts: RedisStreamsAdapterOptions): QueueAdapter<TInput>;

package/dist/adapters/redis-streams.js

@@ -0,0 +1,68 @@
+import { QueueProtocolError } from "../index";
+export function createRedisStreamsAdapter(opts) {
+    if (!opts.streamKey)
+        throw new QueueProtocolError("redis-streams adapter requires streamKey");
+    if (!opts.consumerGroup)
+        throw new QueueProtocolError("redis-streams adapter requires consumerGroup");
+    const client = opts._client ?? requireClient();
+    let acked = 0;
+    let nacked = 0;
+    let deadLetter = 0;
+    return {
+        kind: "redis-streams",
+        async pull(pullOpts) {
+            const res = await client.xreadgroup(opts.consumerGroup, opts.consumerName, pullOpts.maxBatch, 
+            // PullOptions carries no long-poll knob; read non-blocking and let the
+            // consumer drive polling cadence.
+            0, opts.streamKey, ">");
+            if (!res)
+                return [];
+            const out = [];
+            const now = Date.now();
+            for (const stream of res) {
+                for (const m of stream.messages) {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(m.fields["payload"] ?? "{}");
+                    }
+                    catch {
+                        parsed = m.fields["payload"];
+                    }
+                    out.push({
+                        id: m.id,
+                        input: parsed,
+                        enqueuedAt: new Date(now).toISOString(),
+                        visibilityExpiresAt: new Date(now + pullOpts.visibilityTimeoutMs).toISOString(),
+                        attempt: 1,
+                    });
+                }
+            }
+            return out;
+        },
+        async ack(jobId) {
+            await client.xack(opts.streamKey, opts.consumerGroup, jobId);
+            acked++;
+        },
+        async nack(jobId, reason) {
+            if (reason === "permanent" && opts.deadLetterStream) {
+                await client.xadd(opts.deadLetterStream, "*", "payload", JSON.stringify({ jobId }));
+                deadLetter++;
+            }
+            else {
+                // Re-publish to the tail; the consumer-group will redeliver.
+                await client.xadd(opts.streamKey, "*", "payload", JSON.stringify({ retry: jobId }));
+            }
+            await client.xack(opts.streamKey, opts.consumerGroup, jobId);
+            nacked++;
+        },
+        async extendVisibility(_jobId, _additionalMs) {
+            // Redis Streams uses min-idle-time; nothing to do here.
+        },
+        async stats() {
+            return { pending: 0, inFlight: 0, acked, nacked, deadLetter };
+        },
+    };
+}
+function requireClient() {
+    throw new QueueProtocolError("redis-streams adapter requires `ioredis` to be installed and a Redis URL configured. Pass an explicit `_client` to use a stub.");
+}

package/dist/adapters/sqs.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Section 30 — SQS adapter for `@crewhaus/queue-protocol`. Production
+ * deployments using AWS SQS use this; the contract is identical to the
+ * in-memory adapter (pull/ack/nack/extendVisibility/stats).
+ *
+ * v0 ships with the *abstraction* and credential plumbing; the actual
+ * `@aws-sdk/client-sqs` calls are gated on the AWS SDK being installed
+ * and `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (or the IAM
+ * instance-profile chain) being available. The implementation throws
+ * `QueueProtocolError("sqs adapter requires …")` when those are missing
+ * so a single misconfigured spec fails loud at boot rather than silently
+ * dropping jobs.
+ *
+ * The interface is correct + tested via the contract corpus; the live
+ * SQS smoke is gated behind `AWS_ACCESS_KEY_ID` + `SQS_QUEUE_URL` and
+ * runs only in deployments where those are set.
+ */
+import type { QueueAdapter } from "../index";
+export type SqsAdapterOptions = {
+    readonly queueUrl: string;
+    readonly region: string;
+    readonly accessKeyId?: string;
+    readonly secretAccessKey?: string;
+    /** Test override: inject a fake SQS client. */
+    readonly _client?: SqsClientLike;
+};
+export type SqsClientLike = {
+    receiveMessage(input: {
+        QueueUrl: string;
+        MaxNumberOfMessages: number;
+        VisibilityTimeout: number;
+        WaitTimeSeconds: number;
+    }): Promise<{
+        Messages?: Array<{
+            MessageId?: string;
+            ReceiptHandle?: string;
+            Body?: string;
+        }>;
+    }>;
+    deleteMessage(input: {
+        QueueUrl: string;
+        ReceiptHandle: string;
+    }): Promise<void>;
+    changeMessageVisibility(input: {
+        QueueUrl: string;
+        ReceiptHandle: string;
+        VisibilityTimeout: number;
+    }): Promise<void>;
+};
+export declare function createSqsAdapter<TInput = unknown>(opts: SqsAdapterOptions): QueueAdapter<TInput>;

package/dist/adapters/sqs.js

@@ -0,0 +1,100 @@
+import { QueueProtocolError } from "../index";
+export function createSqsAdapter(opts) {
+    if (!opts.queueUrl) {
+        throw new QueueProtocolError("sqs adapter requires queueUrl");
+    }
+    const client = opts._client ?? requireSdkClient(opts);
+    // Map ReceiptHandle by jobId so ack/nack/extendVisibility can find it.
+    const receiptByJobId = new Map();
+    let acked = 0;
+    let nacked = 0;
+    let deadLetter = 0;
+    return {
+        kind: "sqs",
+        async pull(pullOpts) {
+            const result = await client.receiveMessage({
+                QueueUrl: opts.queueUrl,
+                MaxNumberOfMessages: Math.min(10, pullOpts.maxBatch),
+                VisibilityTimeout: Math.ceil(pullOpts.visibilityTimeoutMs / 1000),
+                // PullOptions carries no long-poll knob; use SQS short polling.
+                WaitTimeSeconds: 0,
+            });
+            const out = [];
+            const now = Date.now();
+            for (const m of result.Messages ?? []) {
+                if (!m.MessageId || !m.ReceiptHandle || m.Body === undefined)
+                    continue;
+                receiptByJobId.set(m.MessageId, m.ReceiptHandle);
+                let parsed;
+                try {
+                    parsed = JSON.parse(m.Body);
+                }
+                catch {
+                    parsed = m.Body;
+                }
+                out.push({
+                    id: m.MessageId,
+                    input: parsed,
+                    enqueuedAt: new Date(now).toISOString(),
+                    visibilityExpiresAt: new Date(now + pullOpts.visibilityTimeoutMs).toISOString(),
+                    attempt: 1,
+                });
+            }
+            return out;
+        },
+        async ack(jobId) {
+            const handle = receiptByJobId.get(jobId);
+            if (!handle)
+                throw new QueueProtocolError(`sqs ack: receipt for ${jobId} not found`);
+            await client.deleteMessage({ QueueUrl: opts.queueUrl, ReceiptHandle: handle });
+            receiptByJobId.delete(jobId);
+            acked++;
+        },
+        async nack(jobId, reason) {
+            const handle = receiptByJobId.get(jobId);
+            if (!handle)
+                throw new QueueProtocolError(`sqs nack: receipt for ${jobId} not found`);
+            if (reason === "permanent") {
+                // Delete from the main queue; the redrive policy on the SQS side
+                // moves it to the dead-letter queue automatically when configured.
+                await client.deleteMessage({ QueueUrl: opts.queueUrl, ReceiptHandle: handle });
+                deadLetter++;
+            }
+            else {
+                // Reset visibility timeout to 0 so the message is immediately re-driven.
+                await client.changeMessageVisibility({
+                    QueueUrl: opts.queueUrl,
+                    ReceiptHandle: handle,
+                    VisibilityTimeout: 0,
+                });
+            }
+            receiptByJobId.delete(jobId);
+            nacked++;
+        },
+        async extendVisibility(jobId, additionalMs) {
+            const handle = receiptByJobId.get(jobId);
+            if (!handle)
+                throw new QueueProtocolError(`sqs extendVisibility: receipt for ${jobId} not found`);
+            await client.changeMessageVisibility({
+                QueueUrl: opts.queueUrl,
+                ReceiptHandle: handle,
+                VisibilityTimeout: Math.ceil(additionalMs / 1000),
+            });
+        },
+        async stats() {
+            // SQS doesn't expose accurate counters cheaply; we return the local
+            // counters for in-flight + acked/nacked + 0 for pending (consumers
+            // should query CloudWatch for that).
+            return {
+                pending: 0,
+                inFlight: receiptByJobId.size,
+                acked,
+                nacked,
+                deadLetter,
+            };
+        },
+    };
+}
+function requireSdkClient(_opts) {
+    throw new QueueProtocolError("sqs adapter requires `@aws-sdk/client-sqs` to be installed and AWS credentials configured. Pass an explicit `_client` to use a stub.");
+}

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Catalog R14 `queue-protocol` — Section 23 BATCH.
+ *
+ * Abstract queue interface used by `queue-consumer` and the BATCH target
+ * codegen. The interface is deliberately minimal: every adapter
+ * implements the same four methods so swapping SQS for Redis Streams
+ * for Postgres advisory-lock is a config flip, not a code change.
+ *
+ * Visibility-timeout semantics:
+ *   - `pull(maxBatch, visibilityTimeoutMs)` returns up to `maxBatch`
+ *     pending jobs; each job becomes invisible to other consumers for
+ *     `visibilityTimeoutMs`. Returns an empty array on empty-queue.
+ *   - `ack(jobId)` marks the job complete. Idempotent; double-ack is a
+ *     no-op (post-conditions: job is gone).
+ *   - `nack(jobId, reason)` returns the job to the queue with a
+ *     reason classifier. `transient` re-enqueues for retry; `permanent`
+ *     moves the job to a dead-letter bucket; `timeout` is the
+ *     consumer-internal classifier when a job's visibility window
+ *     expires before completion.
+ *   - `extendVisibility(jobId, ms)` pushes the visibility-expires-at
+ *     forward by `ms`. Used by the consumer to keep long-running jobs
+ *     from being yanked out from under it.
+ *
+ * Adapters in this slice:
+ *   - `createInMemoryQueue<T>()` — single-process, fast, used by tests
+ *     and the example/smoke. Produces deterministic-ish JobIds via a
+ *     monotonic counter so the smoke can assert on them.
+ *   - SQS / Redis Streams / Postgres advisory-lock — interface-only
+ *     stubs (kept here as type declarations); concrete impls land in
+ *     follow-up PRs.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export { createSqsAdapter, type SqsAdapterOptions, type SqsClientLike, } from "./adapters/sqs";
+export { createRedisStreamsAdapter, type RedisStreamsAdapterOptions, type RedisClientLike, } from "./adapters/redis-streams";
+export { createPostgresAdapter, type PostgresAdapterOptions, type PostgresClientLike, } from "./adapters/postgres";
+export declare class QueueProtocolError extends CrewhausError {
+    readonly name = "QueueProtocolError";
+    constructor(message: string, cause?: unknown);
+}
+export type JobId = string;
+export type Job<TInput = unknown> = {
+    readonly id: JobId;
+    /** 1-indexed; bumped each time the job is pulled (so retries see attempt > 1). */
+    readonly attempt: number;
+    readonly input: TInput;
+    readonly enqueuedAt: string;
+    /** ISO8601 timestamp when the visibility lease expires. */
+    readonly visibilityExpiresAt: string;
+};
+export type NackReason = "transient" | "permanent" | "timeout";
+export type PullOptions = {
+    readonly maxBatch: number;
+    readonly visibilityTimeoutMs: number;
+};
+export interface QueueAdapter<TInput = unknown> {
+    /** The adapter's identifier ("in-memory" | "sqs" | "redis-streams" | "postgres" | …). */
+    readonly kind: string;
+    pull(opts: PullOptions): Promise<ReadonlyArray<Job<TInput>>>;
+    ack(jobId: JobId): Promise<void>;
+    nack(jobId: JobId, reason: NackReason): Promise<void>;
+    extendVisibility(jobId: JobId, additionalMs: number): Promise<void>;
+    /**
+     * Snapshot counts for observability + tests. Stable contract:
+     *   pending — visible-and-enqueued
+     *   inFlight — leased to a consumer (visibilityExpiresAt > now)
+     *   acked / nacked — terminal state counts since adapter creation
+     *   deadLetter — permanent-nack count (subset of nacked)
+     */
+    stats(): Promise<{
+        pending: number;
+        inFlight: number;
+        acked: number;
+        nacked: number;
+        deadLetter: number;
+    }>;
+}
+/**
+ * Adapters that also act as producers (the in-memory tester does;
+ * SQS/Redis Streams adapters keep enqueue inside their respective
+ * client SDKs and don't need this interface) implement this.
+ */
+export interface QueueProducer<TInput = unknown> {
+    enqueue(input: TInput): Promise<JobId>;
+}
+type InternalJob<TInput> = {
+    id: JobId;
+    input: TInput;
+    enqueuedAt: number;
+    attempts: number;
+    /** 0 = not in flight, otherwise the wall-clock ms when the lease expires. */
+    visibilityExpiresAt: number;
+    /** terminal status, undefined while live. */
+    status: "pending" | "in-flight" | "acked" | "nacked" | "dead-letter";
+};
+export type InMemoryQueueOptions<TInput = unknown> = {
+    /**
+     * Test-time clock injection. Defaults to `Date.now`. Returning a
+     * monotonic count is the cleanest way to drive the visibility-timeout
+     * branches deterministically.
+     */
+    readonly now?: () => number;
+    readonly initialJobs?: ReadonlyArray<TInput>;
+    /** Test seam: override the JobId generator. */
+    readonly newJobId?: (counter: number) => JobId;
+};
+export interface InMemoryQueueAdapter<TInput = unknown> extends QueueAdapter<TInput>, QueueProducer<TInput> {
+    readonly kind: "in-memory";
+    /** Test helper: list the queue's view of jobs. */
+    inspect(): ReadonlyArray<{
+        readonly id: JobId;
+        readonly status: InternalJob<TInput>["status"];
+        readonly attempts: number;
+    }>;
+}
+export declare function createInMemoryQueue<TInput>(opts?: InMemoryQueueOptions<TInput>): InMemoryQueueAdapter<TInput>;

package/dist/index.js

@@ -0,0 +1,163 @@
+/**
+ * Catalog R14 `queue-protocol` — Section 23 BATCH.
+ *
+ * Abstract queue interface used by `queue-consumer` and the BATCH target
+ * codegen. The interface is deliberately minimal: every adapter
+ * implements the same four methods so swapping SQS for Redis Streams
+ * for Postgres advisory-lock is a config flip, not a code change.
+ *
+ * Visibility-timeout semantics:
+ *   - `pull(maxBatch, visibilityTimeoutMs)` returns up to `maxBatch`
+ *     pending jobs; each job becomes invisible to other consumers for
+ *     `visibilityTimeoutMs`. Returns an empty array on empty-queue.
+ *   - `ack(jobId)` marks the job complete. Idempotent; double-ack is a
+ *     no-op (post-conditions: job is gone).
+ *   - `nack(jobId, reason)` returns the job to the queue with a
+ *     reason classifier. `transient` re-enqueues for retry; `permanent`
+ *     moves the job to a dead-letter bucket; `timeout` is the
+ *     consumer-internal classifier when a job's visibility window
+ *     expires before completion.
+ *   - `extendVisibility(jobId, ms)` pushes the visibility-expires-at
+ *     forward by `ms`. Used by the consumer to keep long-running jobs
+ *     from being yanked out from under it.
+ *
+ * Adapters in this slice:
+ *   - `createInMemoryQueue<T>()` — single-process, fast, used by tests
+ *     and the example/smoke. Produces deterministic-ish JobIds via a
+ *     monotonic counter so the smoke can assert on them.
+ *   - SQS / Redis Streams / Postgres advisory-lock — interface-only
+ *     stubs (kept here as type declarations); concrete impls land in
+ *     follow-up PRs.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+// Section 30 — additional adapter family members
+export { createSqsAdapter, } from "./adapters/sqs";
+export { createRedisStreamsAdapter, } from "./adapters/redis-streams";
+export { createPostgresAdapter, } from "./adapters/postgres";
+export class QueueProtocolError extends CrewhausError {
+    name = "QueueProtocolError";
+    constructor(message, cause) {
+        super("runtime", message, cause);
+    }
+}
+export function createInMemoryQueue(opts = {}) {
+    const now = opts.now ?? Date.now;
+    const newJobId = opts.newJobId ?? ((c) => `job_${c.toString(16).padStart(8, "0")}`);
+    const jobs = new Map();
+    let counter = 0;
+    let acked = 0;
+    let nacked = 0;
+    let deadLetter = 0;
+    function makeJob(input) {
+        counter += 1;
+        return {
+            id: newJobId(counter),
+            input,
+            enqueuedAt: now(),
+            attempts: 0,
+            visibilityExpiresAt: 0,
+            status: "pending",
+        };
+    }
+    for (const seed of opts.initialJobs ?? []) {
+        const j = makeJob(seed);
+        jobs.set(j.id, j);
+    }
+    function reclaimExpired() {
+        const t = now();
+        for (const j of jobs.values()) {
+            if (j.status === "in-flight" && j.visibilityExpiresAt <= t) {
+                // Visibility lease expired without ack/nack — return to pending.
+                j.status = "pending";
+                j.visibilityExpiresAt = 0;
+            }
+        }
+    }
+    return {
+        kind: "in-memory",
+        async enqueue(input) {
+            const j = makeJob(input);
+            jobs.set(j.id, j);
+            return j.id;
+        },
+        async pull(pullOpts) {
+            reclaimExpired();
+            const t = now();
+            const out = [];
+            // Stable order: insertion (oldest pending first).
+            for (const j of jobs.values()) {
+                if (out.length >= pullOpts.maxBatch)
+                    break;
+                if (j.status !== "pending")
+                    continue;
+                j.attempts += 1;
+                j.status = "in-flight";
+                j.visibilityExpiresAt = t + pullOpts.visibilityTimeoutMs;
+                out.push({
+                    id: j.id,
+                    attempt: j.attempts,
+                    input: j.input,
+                    enqueuedAt: new Date(j.enqueuedAt).toISOString(),
+                    visibilityExpiresAt: new Date(j.visibilityExpiresAt).toISOString(),
+                });
+            }
+            return out;
+        },
+        async ack(jobId) {
+            const j = jobs.get(jobId);
+            if (j === undefined)
+                return; // idempotent
+            if (j.status === "acked")
+                return;
+            j.status = "acked";
+            acked += 1;
+            jobs.delete(jobId);
+        },
+        async nack(jobId, reason) {
+            const j = jobs.get(jobId);
+            if (j === undefined)
+                return;
+            if (reason === "permanent") {
+                j.status = "dead-letter";
+                deadLetter += 1;
+                nacked += 1;
+                // Keep in map so inspect() can see DLQ items; SQS/etc. would
+                // move it to a real DLQ.
+                return;
+            }
+            // transient + timeout: return to pending. attempts stays bumped.
+            j.status = "pending";
+            j.visibilityExpiresAt = 0;
+            nacked += 1;
+        },
+        async extendVisibility(jobId, additionalMs) {
+            const j = jobs.get(jobId);
+            if (j === undefined) {
+                throw new QueueProtocolError(`extendVisibility: unknown jobId "${jobId}"`);
+            }
+            if (j.status !== "in-flight") {
+                throw new QueueProtocolError(`extendVisibility: job "${jobId}" is not in flight (status=${j.status})`);
+            }
+            j.visibilityExpiresAt += additionalMs;
+        },
+        async stats() {
+            reclaimExpired();
+            let pending = 0;
+            let inFlight = 0;
+            for (const j of jobs.values()) {
+                if (j.status === "pending")
+                    pending += 1;
+                if (j.status === "in-flight")
+                    inFlight += 1;
+            }
+            return { pending, inFlight, acked, nacked, deadLetter };
+        },
+        inspect() {
+            return [...jobs.values()].map((j) => ({
+                id: j.id,
+                status: j.status,
+                attempts: j.attempts,
+            }));
+        },
+    };
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/queue-protocol",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Abstract queue interface + in-memory adapter for the BATCH target shape (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/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }