@amqp-contract/worker 0.23.1 → 0.25.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { extractConsumer, extractQueue, isQueueWithTtlBackoffInfrastructure } from "@amqp-contract/contract";
-import { AmqpClient, MessageValidationError, TechnicalError, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, startConsumeSpan } from "@amqp-contract/core";
-import { Future, Result } from "@swan-io/boxed";
+import { AmqpClient, MessageValidationError, TechnicalError, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, safeJsonParse, startConsumeSpan } from "@amqp-contract/core";
+import { ResultAsync, err, errAsync, ok, okAsync } from "neverthrow";
 import { gunzip, inflate } from "node:zlib";
 import { promisify } from "node:util";
 //#region src/decompression.ts
@@ -21,52 +21,55 @@ function isSupportedEncoding(encoding) {
 *
 * @param buffer - The buffer to decompress
 * @param contentEncoding - The content-encoding header value (e.g., 'gzip', 'deflate')
-* @returns A Future with the decompressed buffer or a TechnicalError
+* @returns A ResultAsync resolving to the decompressed buffer or a TechnicalError
 *
 * @internal
 */
 function decompressBuffer(buffer, contentEncoding) {
-	if (!contentEncoding) return Future.value(Result.Ok(buffer));
+	if (!contentEncoding) return okAsync(buffer);
 	const normalizedEncoding = contentEncoding.toLowerCase();
-	if (!isSupportedEncoding(normalizedEncoding)) return Future.value(Result.Error(new TechnicalError(`Unsupported content-encoding: "${contentEncoding}". Supported encodings are: ${SUPPORTED_ENCODINGS.join(", ")}. Please check your publisher configuration.`)));
+	if (!isSupportedEncoding(normalizedEncoding)) return errAsync(new TechnicalError(`Unsupported content-encoding: "${contentEncoding}". Supported encodings are: ${SUPPORTED_ENCODINGS.join(", ")}. Please check your publisher configuration.`));
 	switch (normalizedEncoding) {
-		case "gzip": return Future.fromPromise(gunzipAsync(buffer)).mapError((error) => new TechnicalError("Failed to decompress gzip", error));
-		case "deflate": return Future.fromPromise(inflateAsync(buffer)).mapError((error) => new TechnicalError("Failed to decompress deflate", error));
+		case "gzip": return ResultAsync.fromPromise(gunzipAsync(buffer), (error) => new TechnicalError("Failed to decompress gzip", error));
+		case "deflate": return ResultAsync.fromPromise(inflateAsync(buffer), (error) => new TechnicalError("Failed to decompress deflate", error));
 	}
 }
 //#endregion
 //#region src/errors.ts
 /**
-* Retryable errors - transient failures that may succeed on retry
-* Examples: network timeouts, rate limiting, temporary service unavailability
+* Abstract base class for all handler-signalled errors.
 *
-* Use this error type when the operation might succeed if retried.
-* The worker will apply exponential backoff and retry the message.
+* Concrete subclasses (`RetryableError`, `NonRetryableError`) discriminate on
+* the `name` property so exhaustive narrowing in user code keeps working.
+* `error instanceof HandlerError` is true for any handler error.
 */
-var RetryableError = class extends Error {
+var HandlerError = class extends Error {
 	constructor(message, cause) {
 		super(message);
 		this.cause = cause;
-		this.name = "RetryableError";
 		const ErrorConstructor = Error;
 		if (typeof ErrorConstructor.captureStackTrace === "function") ErrorConstructor.captureStackTrace(this, this.constructor);
 	}
 };
 /**
+* Retryable errors - transient failures that may succeed on retry
+* Examples: network timeouts, rate limiting, temporary service unavailability
+*
+* Use this error type when the operation might succeed if retried.
+* The worker will apply exponential backoff and retry the message.
+*/
+var RetryableError = class extends HandlerError {
+	name = "RetryableError";
+};
+/**
 * Non-retryable errors - permanent failures that should not be retried
 * Examples: invalid data, business rule violations, permanent external failures
 *
 * Use this error type when retrying would not help - the message will be
 * immediately sent to the dead letter queue (DLQ) if configured.
 */
-var NonRetryableError = class extends Error {
-	constructor(message, cause) {
-		super(message);
-		this.cause = cause;
-		this.name = "NonRetryableError";
-		const ErrorConstructor = Error;
-		if (typeof ErrorConstructor.captureStackTrace === "function") ErrorConstructor.captureStackTrace(this, this.constructor);
-	}
+var NonRetryableError = class extends HandlerError {
+	name = "NonRetryableError";
 };
 /**
 * Type guard to check if an error is a RetryableError.
@@ -137,7 +140,7 @@ function isNonRetryableError(error) {
 * ```
 */
 function isHandlerError(error) {
-	return isRetryableError(error) || isNonRetryableError(error);
+	return error instanceof HandlerError;
 }
 /**
 * Create a RetryableError with less verbosity.
@@ -152,15 +155,16 @@ function isHandlerError(error) {
 * @example
 * ```typescript
 * import { retryable } from '@amqp-contract/worker';
-* import { Future, Result } from '@swan-io/boxed';
+* import { ResultAsync } from 'neverthrow';
 *
 * const handler = ({ payload }) =>
-*   Future.fromPromise(processPayment(payload))
-*     .mapOk(() => undefined)
-*     .mapError((e) => retryable('Payment service unavailable', e));
+*   ResultAsync.fromPromise(
+*     processPayment(payload),
+*     (e) => retryable('Payment service unavailable', e),
+*   ).map(() => undefined);
 *
 * // Equivalent to:
-* // .mapError((e) => new RetryableError('Payment service unavailable', e));
+* // ResultAsync.fromPromise(processPayment(payload), (e) => new RetryableError('...', e))
 * ```
 */
 function retryable(message, cause) {
@@ -179,17 +183,17 @@ function retryable(message, cause) {
 * @example
 * ```typescript
 * import { nonRetryable } from '@amqp-contract/worker';
-* import { Future, Result } from '@swan-io/boxed';
+* import { errAsync, okAsync } from 'neverthrow';
 *
 * const handler = ({ payload }) => {
 *   if (!isValidPayload(payload)) {
-*     return Future.value(Result.Error(nonRetryable('Invalid payload format')));
+*     return errAsync(nonRetryable('Invalid payload format'));
 *   }
-*   return Future.value(Result.Ok(undefined));
+*   return okAsync(undefined);
 * };
 *
 * // Equivalent to:
-* // return Future.value(Result.Error(new NonRetryableError('Invalid payload format')));
+* // return errAsync(new NonRetryableError('Invalid payload format'));
 * ```
 */
 function nonRetryable(message, cause) {
@@ -217,23 +221,18 @@ function nonRetryable(message, cause) {
 */
 function handleError(ctx, error, msg, consumerName, consumer) {
 	if (error instanceof NonRetryableError) {
-		ctx.logger?.error("Non-retryable error, sending to DLQ immediately", {
-			consumerName,
-			errorType: error.name,
-			error: error.message
-		});
 		sendToDLQ(ctx, msg, consumer);
-		return Future.value(Result.Ok(void 0));
+		return okAsync(void 0);
 	}
 	const config = extractQueue(consumer.queue).retry;
 	if (config.mode === "immediate-requeue") return handleErrorImmediateRequeue(ctx, error, msg, consumerName, consumer, config);
 	if (config.mode === "ttl-backoff") return handleErrorTtlBackoff(ctx, error, msg, consumerName, consumer, config);
-	ctx.logger?.warn("Retry disabled (none mode), sending to DLQ", {
+	ctx.logger?.info("Retry disabled (none mode), sending to DLQ", {
 		consumerName,
-		error: error.message
+		queueName: extractQueue(consumer.queue).name
 	});
 	sendToDLQ(ctx, msg, consumer);
-	return Future.value(Result.Ok(void 0));
+	return okAsync(void 0);
 }
 /**
 * Handle error by requeuing immediately.
@@ -249,26 +248,24 @@ function handleErrorImmediateRequeue(ctx, error, msg, consumerName, consumer, co
 	const queueName = queue.name;
 	const retryCount = queue.type === "quorum" ? msg.properties.headers?.["x-delivery-count"] ?? 0 : msg.properties.headers?.["x-retry-count"] ?? 0;
 	if (retryCount >= config.maxRetries) {
-		ctx.logger?.error("Max retries exceeded, sending to DLQ (immediate-requeue mode)", {
+		ctx.logger?.info("Max retries exceeded, sending to DLQ (immediate-requeue mode)", {
 			consumerName,
 			queueName,
 			retryCount,
-			maxRetries: config.maxRetries,
-			error: error.message
+			maxRetries: config.maxRetries
 		});
 		sendToDLQ(ctx, msg, consumer);
-		return Future.value(Result.Ok(void 0));
+		return okAsync(void 0);
 	}
-	ctx.logger?.warn("Retrying message (immediate-requeue mode)", {
+	ctx.logger?.info("Retrying message (immediate-requeue mode)", {
 		consumerName,
 		queueName,
 		retryCount,
-		maxRetries: config.maxRetries,
-		error: error.message
+		maxRetries: config.maxRetries
 	});
 	if (queue.type === "quorum") {
 		ctx.amqpClient.nack(msg, false, true);
-		return Future.value(Result.Ok(void 0));
+		return okAsync(void 0);
 	} else return publishForRetry(ctx, {
 		msg,
 		exchange: msg.fields.exchange,
@@ -309,30 +306,28 @@ function handleErrorTtlBackoff(ctx, error, msg, consumerName, consumer, config)
 			consumerName,
 			queueName: consumer.queue.name
 		});
-		return Future.value(Result.Error(new TechnicalError("Queue does not have TTL-backoff infrastructure")));
+		return errAsync(new TechnicalError("Queue does not have TTL-backoff infrastructure"));
 	}
 	const queueEntry = consumer.queue;
 	const queueName = extractQueue(queueEntry).name;
 	const retryCount = msg.properties.headers?.["x-retry-count"] ?? 0;
 	if (retryCount >= config.maxRetries) {
-		ctx.logger?.error("Max retries exceeded, sending to DLQ (ttl-backoff mode)", {
+		ctx.logger?.info("Max retries exceeded, sending to DLQ (ttl-backoff mode)", {
 			consumerName,
 			queueName,
 			retryCount,
-			maxRetries: config.maxRetries,
-			error: error.message
+			maxRetries: config.maxRetries
 		});
 		sendToDLQ(ctx, msg, consumer);
-		return Future.value(Result.Ok(void 0));
+		return okAsync(void 0);
 	}
 	const delayMs = calculateRetryDelay(retryCount, config);
-	ctx.logger?.warn("Retrying message (ttl-backoff mode)", {
+	ctx.logger?.info("Retrying message (ttl-backoff mode)", {
 		consumerName,
 		queueName,
 		retryCount: retryCount + 1,
 		maxRetries: config.maxRetries,
-		delayMs,
-		error: error.message
+		delayMs
 	});
 	return publishForRetry(ctx, {
 		msg,
@@ -349,9 +344,9 @@ function handleErrorTtlBackoff(ctx, error, msg, consumerName, consumer, config)
 */
 function calculateRetryDelay(retryCount, config) {
 	const { initialDelayMs, maxDelayMs, backoffMultiplier, jitter } = config;
-	let delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, retryCount), maxDelayMs);
-	if (jitter) delay = delay * (.5 + Math.random() * .5);
-	return Math.floor(delay);
+	let delay = initialDelayMs * Math.pow(backoffMultiplier, retryCount);
+	if (jitter) delay = delay * (.5 + Math.random());
+	return Math.floor(Math.min(delay, maxDelayMs));
 }
 /**
 * Parse message content for republishing.
@@ -370,10 +365,10 @@ function parseMessageContentForRetry(ctx, msg, queueName) {
 	if (!(contentType === void 0 || contentType === "application/json" || contentType.startsWith("application/json;") || contentType.endsWith("+json"))) return msg.content;
 	try {
 		return JSON.parse(msg.content.toString());
-	} catch (err) {
+	} catch (parseErr) {
 		ctx.logger?.warn("Failed to parse JSON message for retry, using original buffer", {
 			queueName,
-			error: err
+			error: parseErr
 		});
 		return msg.content;
 	}
@@ -383,7 +378,6 @@ function parseMessageContentForRetry(ctx, msg, queueName) {
 */
 function publishForRetry(ctx, { msg, exchange, routingKey, queueName, waitQueueName, delayMs, error }) {
 	const newRetryCount = (msg.properties.headers?.["x-retry-count"] ?? 0) + 1;
-	ctx.amqpClient.ack(msg);
 	const content = parseMessageContentForRetry(ctx, msg, queueName);
 	return ctx.amqpClient.publish(exchange, routingKey, content, {
 		...msg.properties,
@@ -398,21 +392,30 @@ function publishForRetry(ctx, { msg, exchange, routingKey, queueName, waitQueueN
 				"x-retry-queue": queueName
 			} : {}
 		}
-	}).mapOkToResult((published) => {
+	}).andThen((published) => {
 		if (!published) {
 			ctx.logger?.error("Failed to publish message for retry (write buffer full)", {
 				queueName,
 				retryCount: newRetryCount,
 				...delayMs !== void 0 ? { delayMs } : {}
 			});
-			return Result.Error(new TechnicalError("Failed to publish message for retry (write buffer full)"));
+			return err(new TechnicalError("Failed to publish message for retry (write buffer full)"));
 		}
+		ctx.amqpClient.ack(msg);
 		ctx.logger?.info("Message published for retry", {
 			queueName,
 			retryCount: newRetryCount,
 			...delayMs !== void 0 ? { delayMs } : {}
 		});
-		return Result.Ok(void 0);
+		return ok(void 0);
+	}).orElse((publishError) => {
+		ctx.logger?.error("Publish for retry failed; leaving original un-ack'd for redelivery", {
+			queueName,
+			retryCount: newRetryCount,
+			...delayMs !== void 0 ? { delayMs } : {},
+			error: publishError
+		});
+		return err(publishError);
 	});
 }
 /**
@@ -449,6 +452,7 @@ function isHandlerTuple(entry) {
 * ```typescript
 * import { TypedAmqpWorker } from '@amqp-contract/worker';
 * import { defineQueue, defineMessage, defineContract, defineConsumer } from '@amqp-contract/contract';
+* import { okAsync } from 'neverthrow';
 * import { z } from 'zod';
 *
 * const orderQueue = defineQueue('order-processing');
@@ -463,19 +467,22 @@ function isHandlerTuple(entry) {
 *   }
 * });
 *
-* const worker = await TypedAmqpWorker.create({
+* const result = await TypedAmqpWorker.create({
 *   contract,
 *   handlers: {
-*     processOrder: async (message) => {
-*       console.log('Processing order', message.orderId);
-*       // Process the order...
-*     }
+*     processOrder: ({ payload }) => {
+*       console.log('Processing order', payload.orderId);
+*       return okAsync(undefined);
+*     },
 *   },
-*   urls: ['amqp://localhost']
-* }).resultToPromise();
+*   urls: ['amqp://localhost'],
+* });
+*
+* if (result.isErr()) throw result.error;
+* const worker = result.value;
 *
 * // Close when done
-* await worker.close().resultToPromise();
+* await worker.close();
 * ```
 */
 var TypedAmqpWorker = class TypedAmqpWorker {
@@ -551,18 +558,17 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* Connections are automatically shared across clients and workers with the same
 	* URLs and connection options, following RabbitMQ best practices.
 	*
-	* @param options - Configuration options for the worker
-	* @returns A Future that resolves to a Result containing the worker or an error
+	* @returns A ResultAsync that resolves to the worker or a TechnicalError.
 	*
 	* @example
 	* ```typescript
-	* const worker = await TypedAmqpWorker.create({
+	* const result = await TypedAmqpWorker.create({
 	*   contract: myContract,
 	*   handlers: {
-	*     processOrder: async ({ payload }) => console.log('Order:', payload.orderId)
+	*     processOrder: ({ payload }) => okAsync(undefined),
 	*   },
-	*   urls: ['amqp://localhost']
-	* }).resultToPromise();
+	*   urls: ['amqp://localhost'],
+	* });
 	* ```
 	*/
 	static create({ contract, handlers, urls, connectionOptions, defaultConsumerOptions, logger, telemetry, connectTimeoutMs }) {
@@ -571,12 +577,14 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			connectionOptions,
 			connectTimeoutMs
 		}), handlers, defaultConsumerOptions ?? {}, logger, telemetry);
-		return worker.waitForConnectionReady().flatMapOk(() => worker.consumeAll()).flatMap((result) => result.match({
-			Ok: () => Future.value(Result.Ok(worker)),
-			Error: (error) => worker.close().tapError((closeError) => {
-				logger?.warn("Failed to close worker after setup failure", { error: closeError });
-			}).map(() => Result.Error(error))
-		}));
+		const setup = worker.waitForConnectionReady().andThen(() => worker.consumeAll());
+		return new ResultAsync((async () => {
+			const setupResult = await setup;
+			if (setupResult.isOk()) return ok(worker);
+			const closeResult = await worker.close();
+			if (closeResult.isErr()) logger?.warn("Failed to close worker after setup failure", { error: closeResult.error });
+			return err(setupResult.error);
+		})());
 	}
 	/**
 	* Close the AMQP channel and connection.
@@ -584,26 +592,25 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* This gracefully closes the connection to the AMQP broker,
 	* stopping all message consumption and cleaning up resources.
 	*
-	* @returns A Future that resolves to a Result indicating success or failure
-	*
 	* @example
 	* ```typescript
-	* const closeResult = await worker.close().resultToPromise();
+	* const closeResult = await worker.close();
 	* if (closeResult.isOk()) {
 	*   console.log('Worker closed successfully');
 	* }
 	* ```
 	*/
 	close() {
-		return Future.all(Array.from(this.consumerTags).map((consumerTag) => this.amqpClient.cancel(consumerTag).mapErrorToResult((error) => {
+		const cancellations = Array.from(this.consumerTags).map((consumerTag) => this.amqpClient.cancel(consumerTag).orElse((error) => {
 			this.logger?.warn("Failed to cancel consumer during close", {
 				consumerTag,
 				error
 			});
-			return Result.Ok(void 0);
-		}))).map(Result.all).tapOk(() => {
+			return ok(void 0);
+		}));
+		return ResultAsync.combine(cancellations).andTee(() => {
 			this.consumerTags.clear();
-		}).flatMapOk(() => this.amqpClient.close()).mapOk(() => void 0);
+		}).andThen(() => this.amqpClient.close()).map(() => void 0);
 	}
 	/**
 	* Start consuming for every entry in `contract.consumers` and `contract.rpcs`.
@@ -612,7 +619,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		const consumerNames = Object.keys(this.contract.consumers ?? {});
 		const rpcNames = Object.keys(this.contract.rpcs ?? {});
 		const allNames = [...consumerNames, ...rpcNames];
-		return Future.all(allNames.map((name) => this.consume(name))).map(Result.all).mapOk(() => void 0);
+		return ResultAsync.combine(allNames.map((name) => this.consume(name))).map(() => void 0);
 	}
 	waitForConnectionReady() {
 		return this.amqpClient.waitForConnect();
@@ -633,9 +640,9 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	validateSchema(schema, data, context) {
 		const rawValidation = schema["~standard"].validate(data);
 		const validationPromise = rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation);
-		return Future.fromPromise(validationPromise).mapError((error) => new TechnicalError(`Error validating ${context.field}`, error)).mapOkToResult((result) => {
-			if (result.issues) return Result.Error(new TechnicalError(`${context.field} validation failed`, new MessageValidationError(context.consumerName, result.issues)));
-			return Result.Ok(result.value);
+		return ResultAsync.fromPromise(validationPromise, (error) => new TechnicalError(`Error validating ${context.field}`, error)).andThen((result) => {
+			if (result.issues) return err(new TechnicalError(`${context.field} validation failed`, new MessageValidationError(context.consumerName, result.issues)));
+			return ok(result.value);
 		});
 	}
 	/**
@@ -647,18 +654,18 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	*/
 	parseAndValidateMessage(msg, consumer, consumerName) {
 		const context = { consumerName: String(consumerName) };
-		const parsePayload = decompressBuffer(msg.content, msg.properties.contentEncoding).mapErrorToResult((error) => Result.Error(new TechnicalError("Failed to decompress message", error))).mapOkToResult((buffer) => Result.fromExecution(() => JSON.parse(buffer.toString())).mapError((error) => new TechnicalError("Failed to parse JSON", error))).flatMapOk((parsed) => this.validateSchema(consumer.message.payload, parsed, {
+		const parsePayload = decompressBuffer(msg.content, msg.properties.contentEncoding).andThen((buffer) => safeJsonParse(buffer, (error) => new TechnicalError("Failed to parse JSON", error))).andThen((parsed) => this.validateSchema(consumer.message.payload, parsed, {
 			...context,
 			field: "payload"
 		}));
 		const parseHeaders = consumer.message.headers ? this.validateSchema(consumer.message.headers, msg.properties.headers ?? {}, {
 			...context,
 			field: "headers"
-		}) : Future.value(Result.Ok(void 0));
-		return Future.allFromDict({
-			payload: parsePayload,
-			headers: parseHeaders
-		}).map(Result.allFromDict);
+		}) : okAsync(void 0);
+		return ResultAsync.combine([parsePayload, parseHeaders]).map(([payload, headers]) => ({
+			payload,
+			headers
+		}));
 	}
 	/**
 	* Validate an RPC handler's response and publish it back to the caller's reply
@@ -687,7 +694,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				rpcName: String(rpcName),
 				queueName
 			});
-			return Future.value(Result.Error(new NonRetryableError(`RPC "${String(rpcName)}" received a message without replyTo; cannot deliver response`)));
+			return errAsync(new NonRetryableError(`RPC "${String(rpcName)}" received a message without replyTo; cannot deliver response`));
 		}
 		if (typeof correlationId !== "string" || correlationId.length === 0) {
 			this.logger?.error("RPC handler returned a response but the incoming message has no correlationId", {
@@ -695,85 +702,127 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				queueName,
 				replyTo
 			});
-			return Future.value(Result.Error(new NonRetryableError(`RPC "${String(rpcName)}" received a message without correlationId; cannot deliver response`)));
+			return errAsync(new NonRetryableError(`RPC "${String(rpcName)}" received a message without correlationId; cannot deliver response`));
 		}
 		let rawValidation;
 		try {
 			rawValidation = responseSchema["~standard"].validate(response);
 		} catch (error) {
-			return Future.value(Result.Error(new NonRetryableError("RPC response schema validation threw", error)));
+			return errAsync(new NonRetryableError("RPC response schema validation threw", error));
 		}
 		const validationPromise = rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation);
-		return Future.fromPromise(validationPromise).mapError((error) => new NonRetryableError("RPC response schema validation threw", error)).mapOkToResult((validation) => {
-			if (validation.issues) return Result.Error(new NonRetryableError(`RPC response for "${String(rpcName)}" failed schema validation`, new MessageValidationError(String(rpcName), validation.issues)));
-			return Result.Ok(validation.value);
-		}).flatMapOk((validatedResponse) => this.amqpClient.publish("", replyTo, validatedResponse, {
+		return ResultAsync.fromPromise(validationPromise, (error) => new NonRetryableError("RPC response schema validation threw", error)).andThen((validation) => {
+			if (validation.issues) return err(new NonRetryableError(`RPC response for "${String(rpcName)}" failed schema validation`, new MessageValidationError(String(rpcName), validation.issues)));
+			return ok(validation.value);
+		}).andThen((validatedResponse) => this.amqpClient.publish("", replyTo, validatedResponse, {
 			correlationId,
 			contentType: "application/json"
-		}).mapErrorToResult((error) => Result.Error(new NonRetryableError("Failed to publish RPC response", error))).mapOkToResult((published) => published ? Result.Ok(void 0) : Result.Error(new NonRetryableError("Failed to publish RPC response: channel buffer full"))));
+		}).mapErr((error) => new NonRetryableError("Failed to publish RPC response", error)).andThen((published) => published ? ok(void 0) : err(new NonRetryableError("Failed to publish RPC response: channel buffer full"))));
+	}
+	/**
+	* Parse and validate the message; on failure, nack(requeue=false) so the
+	* queue's DLX (if configured) receives the poison message and bypass the
+	* retry pipeline — a malformed payload is deterministic and retrying it
+	* would burn the queue's retry budget on a guaranteed failure.
+	*/
+	parseAndValidateOrNack(msg, consumer, name) {
+		return this.parseAndValidateMessage(msg, consumer, name).orElse((parseError) => {
+			this.amqpClient.nack(msg, false, false);
+			return errAsync(parseError);
+		});
+	}
+	/**
+	* Invoke the handler and ack the message on success. Returns the handler's
+	* response (RPC) or `undefined` (regular consumer). Errors propagate as
+	* `HandlerError` for downstream RPC reply publishing or routing via
+	* {@link handleError}.
+	*/
+	runHandler(handler, validatedMessage, msg) {
+		return handler(validatedMessage, msg);
+	}
+	/**
+	* For RPC handlers, validate and publish the reply on the caller's
+	* `replyTo` / `correlationId`. For non-RPC consumers, this is a no-op that
+	* resolves to `okAsync(undefined)`.
+	*/
+	publishReplyIfRpc(msg, view, name, handlerResponse) {
+		if (!view.isRpc || !view.responseSchema) return okAsync(void 0);
+		const queueName = extractQueue(view.consumer.queue).name;
+		return this.publishRpcResponse(msg, queueName, name, view.responseSchema, handlerResponse);
 	}
 	/**
 	* Process a single consumed message: validate, invoke handler, optionally
-	* publish the RPC response, record telemetry, and handle errors.
+	* publish the RPC response, record telemetry, and route errors.
+	*
+	* The caller-supplied `state` is mutated as the message is ack'd/nack'd so
+	* the consume callback's catch-all guard can tell whether a defensive nack
+	* is still needed (see {@link consumeSingle}).
+	*
+	* Success-vs-failure telemetry is data-driven: the chain resolves to
+	* `ok(undefined)` only on handler success (and reply-publish success for
+	* RPC). Handler failures — even when {@link handleError} routes them
+	* successfully to retry/DLQ — are classified as failures for metrics by
+	* re-failing the chain with a `TechnicalError` whose `cause` is the
+	* original `HandlerError`. The terminal `orTee` unwraps the cause before
+	* recording the span exception so traces keep the original
+	* `RetryableError` / `NonRetryableError` class as the exception type.
 	*/
-	processMessage(msg, view, name, handler) {
-		const { consumer, isRpc, responseSchema } = view;
+	processMessage(msg, view, name, handler, state) {
+		const { consumer } = view;
 		const queueName = extractQueue(consumer.queue).name;
 		const startTime = Date.now();
 		const span = startConsumeSpan(this.telemetry, queueName, String(name), { "messaging.rabbitmq.message.delivery_tag": msg.fields.deliveryTag });
-		let messageHandled = false;
-		let firstError;
-		return this.parseAndValidateMessage(msg, consumer, name).flatMap((parseResult) => parseResult.match({
-			Ok: (validatedMessage) => handler(validatedMessage, msg).flatMapOk((handlerResponse) => {
-				if (isRpc && responseSchema) return this.publishRpcResponse(msg, queueName, name, responseSchema, handlerResponse).flatMapOk(() => {
-					this.logger?.info("Message consumed successfully", {
-						consumerName: String(name),
-						queueName
-					});
-					this.amqpClient.ack(msg);
-					messageHandled = true;
-					return Future.value(Result.Ok(void 0));
-				});
-				this.logger?.info("Message consumed successfully", {
-					consumerName: String(name),
-					queueName
-				});
-				this.amqpClient.ack(msg);
-				messageHandled = true;
-				return Future.value(Result.Ok(void 0));
-			}).flatMapError((handlerError) => {
-				this.logger?.error("Error processing message", {
+		return this.parseAndValidateOrNack(msg, consumer, name).orTee((parseError) => {
+			this.logger?.error("Failed to parse/validate message; sending to DLQ", {
+				consumerName: String(name),
+				queueName,
+				error: parseError
+			});
+			state.messageHandled = true;
+		}).andThen((validatedMessage) => this.runHandler(handler, validatedMessage, msg).andThen((handlerResponse) => this.publishReplyIfRpc(msg, view, name, handlerResponse).andTee(() => {
+			this.logger?.info("Message consumed successfully", {
+				consumerName: String(name),
+				queueName
+			});
+			this.amqpClient.ack(msg);
+			state.messageHandled = true;
+		})).orElse((handlerError) => {
+			this.logger?.error("Error processing message", {
+				consumerName: String(name),
+				queueName,
+				errorType: handlerError.name,
+				retryCount: msg.properties.headers?.["x-delivery-count"] ?? msg.properties.headers?.["x-retry-count"] ?? 0,
+				error: handlerError.message
+			});
+			return handleError({
+				amqpClient: this.amqpClient,
+				logger: this.logger
+			}, handlerError, msg, String(name), consumer).andTee(() => {
+				state.messageHandled = true;
+			}).andThen(() => errAsync(new TechnicalError(`Handler "${String(name)}" failed: ${handlerError.message}`, handlerError)));
+		})).andTee(() => {
+			try {
+				endSpanSuccess(span);
+				recordConsumeMetric(this.telemetry, queueName, String(name), true, Date.now() - startTime);
+			} catch (telemetryError) {
+				this.logger?.warn("Telemetry recording threw; ignoring", {
 					consumerName: String(name),
 					queueName,
-					errorType: handlerError.name,
-					error: handlerError.message
+					error: telemetryError
 				});
-				firstError = handlerError;
-				return handleError({
-					amqpClient: this.amqpClient,
-					logger: this.logger
-				}, handlerError, msg, String(name), consumer);
-			}),
-			Error: (parseError) => {
-				firstError = parseError;
-				this.logger?.error("Failed to parse/validate message; sending to DLQ", {
+			}
+		}).orTee((error) => {
+			const reportedError = error.cause instanceof Error ? error.cause : error;
+			try {
+				endSpanError(span, reportedError);
+				recordConsumeMetric(this.telemetry, queueName, String(name), false, Date.now() - startTime);
+			} catch (telemetryError) {
+				this.logger?.warn("Telemetry recording threw; ignoring", {
 					consumerName: String(name),
 					queueName,
-					error: parseError
+					error: telemetryError
 				});
-				this.amqpClient.nack(msg, false, false);
-				return Future.value(Result.Error(parseError));
-			}
-		})).map((result) => {
-			const durationMs = Date.now() - startTime;
-			if (messageHandled) {
-				endSpanSuccess(span);
-				recordConsumeMetric(this.telemetry, queueName, String(name), true, durationMs);
-			} else {
-				endSpanError(span, result.isError() ? result.error : firstError ?? /* @__PURE__ */ new Error("Unknown error"));
-				recordConsumeMetric(this.telemetry, queueName, String(name), false, durationMs);
 			}
-			return result;
 		});
 	}
 	/**
@@ -789,9 +838,18 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				});
 				return;
 			}
+			const state = { messageHandled: false };
 			try {
-				await this.processMessage(msg, view, name, handler).toPromise();
+				await this.processMessage(msg, view, name, handler, state);
 			} catch (error) {
+				if (state.messageHandled) {
+					this.logger?.error("Uncaught error in consume callback after message was already handled; not nacking", {
+						consumerName: String(name),
+						queueName,
+						error
+					});
+					return;
+				}
 				this.logger?.error("Uncaught error in consume callback; nacking message", {
 					consumerName: String(name),
 					queueName,
@@ -799,64 +857,77 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				});
 				this.amqpClient.nack(msg, false, false);
 			}
-		}, this.consumerOptions[name]).tapOk((consumerTag) => {
+		}, this.consumerOptions[name]).andTee((consumerTag) => {
 			this.consumerTags.add(consumerTag);
-		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(name)}"`, error)).mapOk(() => void 0);
+		}).map(() => void 0).mapErr((error) => new TechnicalError(`Failed to start consuming for "${String(name)}"`, error));
 	}
 };
 //#endregion
 //#region src/handlers.ts
 /**
-* Validate that a consumer exists in the contract
+* Build the list of available handler-target names — every key under
+* `contract.consumers` plus every key under `contract.rpcs`.
 */
-function validateConsumerExists(contract, consumerName) {
+function availableHandlerNames(contract) {
+	const consumers = contract.consumers ? Object.keys(contract.consumers) : [];
+	const rpcs = contract.rpcs ? Object.keys(contract.rpcs) : [];
+	return [...consumers, ...rpcs];
+}
+function formatAvailable(names) {
+	return names.length > 0 ? names.join(", ") : "none";
+}
+/**
+* Validate that a name maps to a contract entry — either a `consumers` key
+* or an `rpcs` key. The two name spaces are disjoint by contract definition.
+*/
+function validateHandlerTargetExists(contract, name) {
 	const consumers = contract.consumers;
-	if (!consumers || !(consumerName in consumers)) {
-		const availableConsumers = consumers ? Object.keys(consumers) : [];
-		const available = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
-		throw new Error(`Consumer "${consumerName}" not found in contract. Available consumers: ${available}`);
+	const rpcs = contract.rpcs;
+	if (!(!!consumers && Object.hasOwn(consumers, name)) && !(!!rpcs && Object.hasOwn(rpcs, name))) {
+		const available = formatAvailable(availableHandlerNames(contract));
+		throw new Error(`Handler target "${name}" not found in contract. Available consumers and RPCs: ${available}`);
 	}
 }
 /**
-* Validate that all handlers reference valid consumers
+* Validate that every key in `handlers` maps to a contract entry —
+* either a `consumers` key or an `rpcs` key.
 */
 function validateHandlers(contract, handlers) {
-	const consumers = contract.consumers;
-	const availableConsumers = Object.keys(consumers ?? {});
-	const availableConsumerNames = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
-	for (const handlerName of Object.keys(handlers)) if (!consumers || !(handlerName in consumers)) throw new Error(`Consumer "${handlerName}" not found in contract. Available consumers: ${availableConsumerNames}`);
+	for (const handlerName of Object.keys(handlers)) validateHandlerTargetExists(contract, handlerName);
 }
-function defineHandler(contract, consumerName, handler, options) {
-	validateConsumerExists(contract, String(consumerName));
+function defineHandler(contract, name, handler, options) {
+	validateHandlerTargetExists(contract, String(name));
 	if (options) return [handler, options];
 	return handler;
 }
 /**
-* Define multiple type-safe handlers for consumers in a contract.
+* Define multiple type-safe handlers for consumers and RPCs in a contract.
+*
+* **Recommended:** This function creates handlers that return
+* `ResultAsync<void, HandlerError>` (consumers) or
+* `ResultAsync<TResponse, HandlerError>` (RPCs), providing explicit error
+* handling and better control over retry behavior.
 *
-* **Recommended:** This function creates handlers that return `Future<Result<void, HandlerError>>`,
-* providing explicit error handling and better control over retry behavior.
+* The handlers object must contain exactly one entry per `consumers` and
+* `rpcs` key in the contract — see {@link WorkerInferHandlers}.
 *
 * @template TContract - The contract definition type
-* @param contract - The contract definition containing the consumers
-* @param handlers - An object with handler functions for each consumer
+* @param contract - The contract definition containing the consumers and RPCs
+* @param handlers - An object with handler functions for each consumer and RPC
 * @returns A type-safe handlers object that can be used with TypedAmqpWorker
 *
 * @example
 * ```typescript
 * import { defineHandlers, RetryableError } from '@amqp-contract/worker';
-* import { Future } from '@swan-io/boxed';
-* import { orderContract } from './contract';
+* import { okAsync, ResultAsync } from 'neverthrow';
 *
 * const handlers = defineHandlers(orderContract, {
 *   processOrder: ({ payload }) =>
-*     Future.fromPromise(processPayment(payload))
-*       .mapOk(() => undefined)
-*       .mapError((error) => new RetryableError('Payment failed', error)),
-*   notifyOrder: ({ payload }) =>
-*     Future.fromPromise(sendNotification(payload))
-*       .mapOk(() => undefined)
-*       .mapError((error) => new RetryableError('Notification failed', error)),
+*     ResultAsync.fromPromise(
+*       processPayment(payload),
+*       (error) => new RetryableError('Payment failed', error),
+*     ).map(() => undefined),
+*   calculate: ({ payload }) => okAsync({ sum: payload.a + payload.b }),
 * });
 * ```
 */
@@ -865,6 +936,6 @@ function defineHandlers(contract, handlers) {
 	return handlers;
 }
 //#endregion
-export { MessageValidationError, NonRetryableError, RetryableError, TypedAmqpWorker, defineHandler, defineHandlers, isHandlerError, isNonRetryableError, isRetryableError, nonRetryable, retryable };
+export { HandlerError, MessageValidationError, NonRetryableError, RetryableError, TypedAmqpWorker, defineHandler, defineHandlers, isHandlerError, isNonRetryableError, isRetryableError, nonRetryable, retryable };
 
 //# sourceMappingURL=index.mjs.map