bunqueue-client 0.1.5 → 0.1.7

package/dist/connection.js

@@ -5,12 +5,21 @@
  * pipelining (many in-flight commands per socket). Uses only `node:`
  * builtins (net/tls), which Node, Bun and Deno all support.
  */
+import { EventEmitter } from 'node:events';
 import { pack, unpack } from 'msgpackr';
+import { Backpressure } from './backpressure.js';
 import { AuthError, CommandError, CommandTimeoutError, ConnectionClosedError } from './errors.js';
 import { compact, FrameParser, frame, PROTOCOL_VERSION } from './frame.js';
+import { nowMs, Telemetry } from './observability.js';
 import { openSocket } from './socket-factory.js';
-/** A single pipelined TCP connection to a bunqueue server. */
-export class Connection {
+/**
+ * A single pipelined TCP connection to a bunqueue server.
+ *
+ * Emits typed lifecycle events for observability: `connect`, `disconnect` and
+ * `reconnect_scheduled` (payloads mirror the telemetry events). Attach a
+ * telemetry sink via the `onTelemetry` option for per-command latency metrics.
+ */
+export class Connection extends EventEmitter {
     host;
     port;
     token;
@@ -31,13 +40,19 @@ export class Connection {
     // socket is presumed dead and torn down so the next call reconnects.
     maxCommandTimeouts = 3;
     consecutiveTimeouts = 0;
+    telemetry;
+    backpressure;
     constructor(options = {}) {
+        super();
         this.host = options.host ?? 'localhost';
         this.port = options.port ?? 6789;
         this.token = options.token;
         this.tls = options.tls;
         this.connectTimeoutMs = options.connectTimeoutMs ?? 5000;
         this.commandTimeoutMs = options.commandTimeoutMs ?? 10_000;
+        this.telemetry = new Telemetry(options, (event, payload) => this.emit(event, payload));
+        const maxInFlight = options.maxInFlight ?? 0;
+        this.backpressure = new Backpressure(maxInFlight, () => this.telemetry.backpressure(this.pending.size, maxInFlight));
     }
     get isConnected() {
         return this.connected;
@@ -73,6 +88,7 @@ export class Connection {
             this.failedAttempts += 1;
             const backoff = Math.min(500 * 2 ** (this.failedAttempts - 1), 5000);
             this.nextAttemptAt = Date.now() + backoff;
+            this.telemetry.reconnectScheduled(this.host, this.port, this.failedAttempts, backoff);
             throw err;
         })
             .finally(() => {
@@ -81,6 +97,7 @@ export class Connection {
         return this.connecting;
     }
     async doConnect() {
+        const startMs = nowMs();
         const socket = await openSocket(this.host, this.port, this.tls, this.connectTimeoutMs);
         socket.setNoDelay(true);
         // TCP keepalive (~15s idle) surfaces a half-open link (cloud LB/NAT idle
@@ -94,6 +111,7 @@ export class Connection {
         this.connected = true;
         this.connectGeneration += 1;
         this.consecutiveTimeouts = 0;
+        this.telemetry.connected(this.host, this.port, this.connectGeneration, startMs);
         // INVARIANT (H3): connected is flipped true before Auth, which is safe
         // ONLY because call() writes the Auth frame synchronously — there is no
         // `await` between this line and the Auth socket.write, so no concurrent
@@ -103,8 +121,10 @@ export class Connection {
         if (this.token) {
             try {
                 await this.call({ cmd: 'Auth', token: this.token });
+                this.telemetry.auth(true);
             }
             catch (err) {
+                this.telemetry.auth(false);
                 this.teardown();
                 if (err instanceof CommandError)
                     throw new AuthError(err.message);
@@ -119,16 +139,24 @@ export class Connection {
     async call(command, timeoutMs) {
         if (!this.connected)
             await this.connect();
+        // Backpressure: park here if too many commands are already in flight. The
+        // socket may be torn down while parked, so re-check after the gate.
+        const gate = this.backpressure.acquire(this.pending.size);
+        if (gate)
+            await gate;
         const socket = this.socket;
-        if (!socket)
+        if (!this.connected || !socket)
             throw new ConnectionClosedError('not connected');
         this.reqCounter = (this.reqCounter + 1) & 0x7fffffff;
         const reqId = String(this.reqCounter);
         const payload = pack({ ...compact(command), reqId });
         const gen = this.connectGeneration; // snapshot: a timeout must not tear down a newer conn
+        const startMs = nowMs();
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(reqId);
+                this.backpressure.release();
+                this.telemetry.timeout(command.cmd, reqId);
                 this.noteTimeout(gen);
                 reject(new CommandTimeoutError(`no response for ${command.cmd} within timeout`));
             }, timeoutMs ?? this.commandTimeoutMs);
@@ -136,6 +164,7 @@ export class Connection {
                 resolve: (response) => {
                     clearTimeout(timer);
                     this.consecutiveTimeouts = 0; // any reply means the link is alive
+                    this.telemetry.command(command.cmd, reqId, startMs, response.ok);
                     if (!response.ok) {
                         reject(new CommandError(String(response.error ?? 'unknown server error')));
                     }
@@ -153,6 +182,7 @@ export class Connection {
                 if (err) {
                     const entry = this.pending.get(reqId);
                     this.pending.delete(reqId);
+                    this.backpressure.release();
                     entry?.reject(new ConnectionClosedError(`send failed: ${err.message}`));
                     this.teardown();
                 }
@@ -209,6 +239,7 @@ export class Connection {
             const entry = this.pending.get(String(reqId));
             if (entry) {
                 this.pending.delete(String(reqId));
+                this.backpressure.release();
                 entry.resolve(response);
             }
         }
@@ -228,6 +259,8 @@ export class Connection {
             this.teardown();
     }
     teardown() {
+        const wasConnected = this.socket !== null;
+        const gen = this.connectGeneration;
         this.connected = false;
         const socket = this.socket;
         this.socket = null;
@@ -241,5 +274,8 @@ export class Connection {
             clearTimeout(entry.timer);
             entry.reject(new ConnectionClosedError('connection lost'));
         }
+        this.backpressure.clear(); // release parked callers; they re-check + fail/reconnect
+        if (wasConnected)
+            this.telemetry.disconnected(this.host, this.port, gen);
     }
 }

package/dist/flow-types.d.ts

@@ -1,6 +1,7 @@
 /** FlowProducer types. */
 import type { Connection, TlsOption } from './connection.js';
 import type { Job } from './job.js';
+import type { Observability } from './observability.js';
 import type { JobOptions } from './types.js';
 export interface FlowJob<T = unknown> {
     name: string;
@@ -19,7 +20,7 @@ export interface FlowStep<T = unknown> {
     data?: T;
     opts?: JobOptions;
 }
-export interface FlowProducerOptions {
+export interface FlowProducerOptions extends Observability {
     host?: string;
     port?: number;
     token?: string;

package/dist/flow.js

@@ -14,7 +14,14 @@ export class FlowProducer {
     constructor(opts = {}) {
         this.connection =
             opts.connection ??
-                new Connection({ host: opts.host, port: opts.port, token: opts.token, tls: opts.tls });
+                new Connection({
+                    host: opts.host,
+                    port: opts.port,
+                    token: opts.token,
+                    tls: opts.tls,
+                    logger: opts.logger,
+                    onTelemetry: opts.onTelemetry,
+                });
         this.ownsConnection = opts.connection === undefined;
     }
     /** Add a flow tree. Children are created (and processed) BEFORE their parent. */
@@ -58,13 +65,15 @@ export class FlowProducer {
                     ...jobPayload(step.name, step.data),
                     __flowParentId: prevId ?? undefined,
                 });
-                const response = await this.connection.call(compact({
+                // Connection.call compacts internally, so no outer compact() is needed
+                // (nesting it confused generic inference of `data`/`response`).
+                const response = await this.connection.call({
                     cmd: 'PUSH',
                     queue: step.queueName,
                     data,
                     ...wireJobOptions(step.opts),
                     dependsOn: prevId ? [prevId] : undefined,
-                }));
+                });
                 const id = String(response.id);
                 jobIds.push(id);
                 prevId = id;

package/dist/index.d.ts

@@ -7,16 +7,21 @@ export type { DlqFilter, DlqStats } from './bunqueue/dlq-rate-limit.js';
 export type { BatchConfig, BatchProcessor, BunqueueConnection, BunqueueDebounceConfig, BunqueueDeduplicationConfig, BunqueueDlqConfig, BunqueueMiddleware, BunqueueOptions, CircuitBreakerConfig, CircuitState, JobTtlConfig, PriorityAgingConfig, RateLimiterOptions, RetryConfig, RetryStrategy, TriggerRule, } from './bunqueue/types.js';
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection.js';
 export { Connection } from './connection.js';
+export { ConnectionPool } from './connection-pool.js';
+export type { ConnectionLike } from './connection-types.js';
 export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
 export { FlowProducer } from './flow.js';
 export type { FlowJob, FlowProducerOptions, FlowStep, GetFlowOptions, JobNode, } from './flow-types.js';
 export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
 export type { JobRaw } from './job.js';
 export { Job } from './job.js';
+export type { Logger, LogLevel, Observability, TelemetryEvent, TelemetryHandler, } from './observability.js';
+export { consoleLogger, noopLogger } from './observability.js';
 export type { BulkJobEntry, QueueOptions } from './queue.js';
 export { Queue } from './queue.js';
 export type { SchedulerOptions } from './queue-admin.js';
+export type { BatchResponse, CountResponse, DataResponse, JobCountsResponse, JobResponse, JobsResponse, OkResponse, PausedResponse, ProgressResponse, PulledJobResponse, PulledJobsResponse, ResultResponse, StateResponse, WaitJobResponse, } from './responses.js';
 export type { BackoffOptions, DeduplicationOptions, JobCounts, JobOptions, JobStateName, RepeatOptions, } from './types.js';
 export { Worker } from './worker.js';
-export type { Processor, WorkerOptions } from './worker-types.js';
-export declare const __version__ = "0.1.2";
+export type { AckBatchOptions, Processor, WorkerEventMap, WorkerOptions, } from './worker-types.js';
+export declare const __version__ = "0.1.7";

package/dist/index.js

@@ -5,10 +5,12 @@
 // Simple Mode (Bunqueue): all-in-one Queue + Worker, 1:1 with the official client
 export { Bunqueue } from './bunqueue/bunqueue.js';
 export { Connection } from './connection.js';
+export { ConnectionPool } from './connection-pool.js';
 export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
 export { FlowProducer } from './flow.js';
 export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
 export { Job } from './job.js';
+export { consoleLogger, noopLogger } from './observability.js';
 export { Queue } from './queue.js';
 export { Worker } from './worker.js';
-export const __version__ = '0.1.2';
+export const __version__ = '0.1.7';

package/dist/job.d.ts

@@ -2,7 +2,7 @@
  * Job wrapper: read view over the server job record + per-job operations.
  * Mirrors the official TS client's Job surface (TCP mode).
  */
-import type { Connection } from './connection.js';
+import type { ConnectionLike } from './connection-types.js';
 export type JobRaw = Record<string, unknown>;
 export type ProgressHook = (job: Job, progress: number) => void;
 export declare class Job<T = unknown> {
@@ -10,7 +10,7 @@ export declare class Job<T = unknown> {
     readonly token: string | undefined;
     private readonly conn;
     private readonly onProgress;
-    constructor(raw: JobRaw, connection?: Connection, token?: string, onProgress?: ProgressHook);
+    constructor(raw: JobRaw, connection?: ConnectionLike, token?: string, onProgress?: ProgressHook);
     get id(): string;
     get queue(): string;
     get data(): T;

package/dist/observability.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** Silent logger (the default). */
+export declare const noopLogger: Logger;
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export declare function consoleLogger(min?: LogLevel): Logger;
+/** A single telemetry data point. A discriminated union keyed on `type`. */
+export type TelemetryEvent = {
+    type: 'command';
+    cmd: string;
+    reqId: string;
+    durationMs: number;
+    ok: boolean;
+} | {
+    type: 'command_timeout';
+    cmd: string;
+    reqId: string;
+} | {
+    type: 'connect';
+    host: string;
+    port: number;
+    generation: number;
+    durationMs: number;
+} | {
+    type: 'disconnect';
+    host: string;
+    port: number;
+    generation: number;
+} | {
+    type: 'reconnect_scheduled';
+    host: string;
+    port: number;
+    attempt: number;
+    delayMs: number;
+} | {
+    type: 'auth';
+    ok: boolean;
+} | {
+    type: 'backpressure';
+    inFlight: number;
+    maxInFlight: number;
+};
+export type TelemetryHandler = (event: TelemetryEvent) => void;
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export declare const LIFECYCLE_EVENTS: readonly ["connect", "disconnect", "reconnect_scheduled"];
+export interface Observability {
+    /** Structured logger; defaults to {@link noopLogger}. */
+    logger?: Logger;
+    /**
+     * Telemetry sink for metrics and tracing. Receives every command's latency,
+     * connect/disconnect/reconnect, auth and backpressure events. Bridge it to
+     * OpenTelemetry spans or Prometheus counters without the SDK depending on
+     * either.
+     */
+    onTelemetry?: TelemetryHandler;
+}
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export declare const nowMs: () => number;
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export declare class Telemetry {
+    private readonly logger;
+    private readonly sink;
+    private readonly emit;
+    constructor(obs: Observability | undefined, emit: (event: string, payload: unknown) => void);
+    /** Observability must never break the client: swallow consumer errors. */
+    private static safely;
+    get log(): Logger;
+    /** Record a completed command's latency and outcome. */
+    command(cmd: string, reqId: string, startMs: number, ok: boolean): void;
+    timeout(cmd: string, reqId: string): void;
+    connected(host: string, port: number, generation: number, startMs: number): void;
+    disconnected(host: string, port: number, generation: number): void;
+    reconnectScheduled(host: string, port: number, attempt: number, delayMs: number): void;
+    auth(ok: boolean): void;
+    backpressure(inFlight: number, maxInFlight: number): void;
+    private dispatch;
+}

package/dist/observability.js

@@ -0,0 +1,110 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+/** Silent logger (the default). */
+export const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export function consoleLogger(min = 'info') {
+    const floor = LEVELS[min];
+    const line = (lvl, msg, meta) => {
+        if (LEVELS[lvl] < floor)
+            return;
+        const suffix = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+        const sink = lvl === 'debug' ? console.log : console[lvl];
+        sink(`[bunqueue] ${lvl} ${msg}${suffix}`);
+    };
+    return {
+        debug: (m, meta) => line('debug', m, meta),
+        info: (m, meta) => line('info', m, meta),
+        warn: (m, meta) => line('warn', m, meta),
+        error: (m, meta) => line('error', m, meta),
+    };
+}
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export const LIFECYCLE_EVENTS = ['connect', 'disconnect', 'reconnect_scheduled'];
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export const nowMs = () => performance.now();
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export class Telemetry {
+    logger;
+    sink;
+    emit;
+    constructor(obs, emit) {
+        // Wrap the user logger so a throwing logger can never break the transport
+        // hot path (dispatch runs inside socket 'data' handlers and connect).
+        const inner = obs?.logger ?? noopLogger;
+        this.logger =
+            inner === noopLogger
+                ? inner
+                : {
+                    debug: (m, meta) => Telemetry.safely(() => inner.debug(m, meta)),
+                    info: (m, meta) => Telemetry.safely(() => inner.info(m, meta)),
+                    warn: (m, meta) => Telemetry.safely(() => inner.warn(m, meta)),
+                    error: (m, meta) => Telemetry.safely(() => inner.error(m, meta)),
+                };
+        this.sink = obs?.onTelemetry;
+        this.emit = emit;
+    }
+    /** Observability must never break the client: swallow consumer errors. */
+    static safely(fn) {
+        try {
+            fn();
+        }
+        catch {
+            /* consumer logging/telemetry error — intentionally ignored */
+        }
+    }
+    get log() {
+        return this.logger;
+    }
+    /** Record a completed command's latency and outcome. */
+    command(cmd, reqId, startMs, ok) {
+        this.dispatch({ type: 'command', cmd, reqId, durationMs: nowMs() - startMs, ok });
+    }
+    timeout(cmd, reqId) {
+        this.logger.warn('command timed out', { cmd, reqId });
+        this.dispatch({ type: 'command_timeout', cmd, reqId });
+    }
+    connected(host, port, generation, startMs) {
+        this.logger.info('connected', { host, port, generation });
+        this.dispatch({ type: 'connect', host, port, generation, durationMs: nowMs() - startMs });
+    }
+    disconnected(host, port, generation) {
+        this.logger.info('disconnected', { host, port, generation });
+        this.dispatch({ type: 'disconnect', host, port, generation });
+    }
+    reconnectScheduled(host, port, attempt, delayMs) {
+        this.logger.warn('reconnect scheduled', { host, port, attempt, delayMs });
+        this.dispatch({ type: 'reconnect_scheduled', host, port, attempt, delayMs });
+    }
+    auth(ok) {
+        this.dispatch({ type: 'auth', ok });
+    }
+    backpressure(inFlight, maxInFlight) {
+        this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
+    }
+    dispatch(event) {
+        // A throwing sink or lifecycle listener must never break the transport:
+        // dispatch runs inside socket 'data' handlers and the connect path.
+        Telemetry.safely(() => this.sink?.(event));
+        if (LIFECYCLE_EVENTS.includes(event.type)) {
+            Telemetry.safely(() => this.emit(event.type, event));
+        }
+    }
+}

package/dist/queue-admin.js

@@ -2,6 +2,7 @@
  * Queue admin surface: DLQ, stall/DLQ configs, rate limits, schedulers,
  * monitoring and webhooks. Merged onto Queue.prototype by queue.ts.
  */
+import { CommandError } from './errors.js';
 import { compact } from './frame.js';
 import { jobPayload, wireJobOptions } from './types.js';
 export const adminMethods = {
@@ -50,6 +51,10 @@ export const adminMethods = {
     // ---------------------------------------------------------------- scheduler
     /** Create/update a recurring job scheduler (cron pattern or fixed interval). */
     async upsertJobScheduler(schedulerId, repeat, template = {}) {
+        // Priority and deduplication of spawned jobs travel as TOP-LEVEL Cron
+        // fields (the handler reads cmd.priority/uniqueKey/dedup); inside
+        // jobOptions the server's CronJobOptions silently ignores them.
+        const dedup = template.opts?.deduplication;
         await this.call(compact({
             cmd: 'Cron',
             name: schedulerId,
@@ -57,9 +62,14 @@ export const adminMethods = {
             data: jobPayload(template.name ?? schedulerId, template.data ?? {}),
             schedule: repeat.pattern,
             repeatEvery: repeat.every,
+            priority: template.opts?.priority,
             timezone: repeat.tz,
             immediately: repeat.immediately,
             maxLimit: repeat.limit,
+            uniqueKey: dedup?.id,
+            dedup: dedup
+                ? compact({ ttl: dedup.ttl, extend: dedup.extend, replace: dedup.replace })
+                : undefined,
             skipMissedOnRestart: repeat.skipMissedOnRestart,
             skipIfNoWorker: repeat.skipIfNoWorker,
             preventOverlap: repeat.preventOverlap,
@@ -74,8 +84,12 @@ export const adminMethods = {
             const response = await this.call({ cmd: 'CronGet', name: schedulerId });
             return (response.cron ?? response.data ?? null);
         }
-        catch {
-            return null; // not-found surfaces as a CommandError
+        catch (err) {
+            // Only 'Cron job not found' maps to null; connection loss, timeouts and
+            // real server errors must surface, not masquerade as a missing scheduler.
+            if (err instanceof CommandError && /not found/i.test(err.message))
+                return null;
+            throw err;
         }
     },
     async getJobSchedulers() {

package/dist/queue-control.d.ts

@@ -38,6 +38,11 @@ export declare const controlMethods: {
     moveJobToDelayed(this: Ctx, id: string, delayMs: number): Promise<void>;
     extendJobLock(this: Ctx, id: string, token: string, durationMs: number): Promise<void>;
     moveJobToCompleted(this: Ctx, id: string, returnValue: unknown, token?: string): Promise<void>;
+    /**
+     * Explicit failure path: mirrors the worker's FAIL wire so the stacktrace
+     * and the UnrecoverableError "do not retry" intent are persisted (#111
+     * silent-loss class), not just the message.
+     */
     moveJobToFailed(this: Ctx, id: string, error: Error | string, token?: string): Promise<void>;
 };
 export type QueueControlApi = typeof controlMethods;

package/dist/queue-control.js

@@ -2,7 +2,9 @@
  * Queue control surface: pause/drain/clean, promotion, retry and per-job
  * mutations. Methods are merged onto Queue.prototype by queue.ts.
  */
+import { UnrecoverableError } from './errors.js';
 import { compact } from './frame.js';
+import { MAX_STACK_LINES } from './worker-types.js';
 export const controlMethods = {
     async pause() {
         await this.call({ cmd: 'Pause', queue: this.name });
@@ -11,8 +13,7 @@ export const controlMethods = {
         await this.call({ cmd: 'Resume', queue: this.name });
     },
     async isPaused() {
-        const response = await this.call({ cmd: 'IsPaused', queue: this.name });
-        return response.paused === true;
+        return (await this.call({ cmd: 'IsPaused', queue: this.name })).paused === true;
     },
     async drain() {
         await this.call({ cmd: 'Drain', queue: this.name });
@@ -23,7 +24,7 @@ export const controlMethods = {
     /** Remove old jobs; returns how many were removed. */
     async clean(graceMs, limit, state) {
         const response = await this.call(compact({ cmd: 'Clean', queue: this.name, grace: graceMs, limit, state }));
-        return Number(response.count ?? 0);
+        return response.count ?? 0;
     },
     async remove(id) {
         await this.call({ cmd: 'Cancel', id });
@@ -37,7 +38,7 @@ export const controlMethods = {
     /** Promote delayed jobs to waiting; returns how many were promoted. */
     async promoteJobs(opts = {}) {
         const response = await this.call(compact({ cmd: 'PromoteJobs', queue: this.name, count: opts.count }));
-        return Number(response.count ?? 0);
+        return response.count ?? 0;
     },
     /** BullMQ contract: failed → waiting. */
     async retryJob(id) {
@@ -48,9 +49,9 @@ export const controlMethods = {
             await this.call({ cmd: 'RetryCompleted', queue: this.name });
             return;
         }
-        // `count` is accepted for API parity but not sent: the server has no
-        // partial RetryDlq — it retries the whole DLQ (BullMQ semantics).
-        await this.call({ cmd: 'RetryDlq', queue: this.name });
+        // `count` caps how many DLQ entries are retried (server >= 2.8.29). Older
+        // servers ignore the field and retry the whole DLQ — forward-compatible.
+        await this.call(compact({ cmd: 'RetryDlq', queue: this.name, count: opts.count }));
     },
     async retryCompleted(id) {
         await this.call(compact({ cmd: 'RetryCompleted', queue: this.name, id }));
@@ -80,8 +81,25 @@ export const controlMethods = {
     async moveJobToCompleted(id, returnValue, token) {
         await this.call(compact({ cmd: 'ACK', id, result: returnValue, token }));
     },
+    /**
+     * Explicit failure path: mirrors the worker's FAIL wire so the stacktrace
+     * and the UnrecoverableError "do not retry" intent are persisted (#111
+     * silent-loss class), not just the message.
+     */
     async moveJobToFailed(id, error, token) {
-        const message = typeof error === 'string' ? error : error.message;
-        await this.call(compact({ cmd: 'FAIL', id, error: message, token }));
+        const err = typeof error === 'string' ? undefined : error;
+        const message = err ? err.message || err.name : error;
+        // Keep the FIRST lines (message + throw site), like the worker path.
+        const stack = err
+            ? (err.stack ?? err.message).split('\n').slice(0, MAX_STACK_LINES)
+            : undefined;
+        await this.call(compact({
+            cmd: 'FAIL',
+            id,
+            error: message,
+            stack,
+            unrecoverable: err instanceof UnrecoverableError ? true : undefined,
+            token,
+        }));
     },
 };