docs: sync docs, READMEs, and agent rules with the 3.0 API

- fix non-compiling .getOrThrow() on E=never in the quick starts and the
  stale unthrown-4 recover() comment
- add the missing MessageValidationError arm to the request-reply
  tutorial's errCases snippets and prose
- document worker close() draining (drainTimeoutMs), middleware arrays,
  standalone topology in defineContract (+ setupAmqpTopology escape
  hatch), the { data, message? } RPC error shape, curated
  ConsumerOptions, strict connectTimeoutMs, AsyncAPI 3.1 and the
  failOnMissingConverter default flip, and the new exports
- AGENTS.md: fix the invariant-5 test pointer and extend the
  load-bearing invariant map to 16 entries covering the new guards

Author: btravers

.agents/rules/handlers.md

@@ -38,7 +38,7 @@ All handlers (consumer and RPC) receive a third `helpers` argument — `{ contex
 
 When the RPC declares an `errors` map (`defineRpc(queue, { request, response, errors })`), the handler may also return `Err(rpcError(code, data))` for a declared code — the worker validates `data` against the declared schema, publishes an error reply (marked by the `RPC_ERROR_CODE_HEADER` header), and **acks the request**; typed business errors never enter the retry/DLQ pipeline. Undeclared codes or invalid error data are contract violations routed to the DLQ. See `packages/worker/src/worker.ts` (`publishRpcErrorReply`) and [docs/guide/error-model.md](../../docs/guide/error-model.md#typed-rpc-errors-rpcerror).
 
-You can define RPC handlers either with `defineHandler` / `defineHandlers` (overloaded against `InferRpcNames<TContract>`, and `validateHandlerTargetExists` checks both `contract.consumers` and `contract.rpcs`) or inline inside `TypedAmqpWorker.create({ handlers: { … } })`. The inline `handlers` parameter is typed against `WorkerInferHandlers<TContract>`, so each name (consumer or RPC) gets the correct signature inferred:
+You can define RPC handlers either with `declareHandler` / `declareHandlers` (overloaded against `InferRpcNames<TContract>`, and `validateHandlerTargetExists` checks both `contract.consumers` and `contract.rpcs`) or inline inside `TypedAmqpWorker.create({ handlers: { … } })`. The inline `handlers` parameter is typed against `WorkerInferHandlers<TContract>`, so each name (consumer or RPC) gets the correct signature inferred:
 
 ```typescript
 import { fromPromise, OkAsync } from "unthrown";
@@ -91,23 +91,23 @@ RPC error semantics worth knowing:
 - **Client-side timeout** → call resolves to `Err(RpcTimeoutError)`; pending state is cleared. If a reply still arrives, it's logged at `warn` and counted via `recordLateRpcReply` (telemetry hook for tuning) — it's not retried.
 - **Client closed mid-call** → call resolves to `Err(RpcCancelledError)`.
 
-## Using `defineHandler` / `defineHandlers`
+## Using `declareHandler` / `declareHandlers`
 
-Use `defineHandler` (single) or `defineHandlers` (object) for full type inference and a runtime check that the name exists in the contract. Both helpers accept consumer **and** RPC names — they're overloaded against `InferConsumerNames` and `InferRpcNames`, and `validateHandlerTargetExists` inspects both `contract.consumers` and `contract.rpcs` (an unknown name throws _"Handler target X not found in contract"_).
+Use `declareHandler` (single) or `declareHandlers` (object) for full type inference and a runtime check that the name exists in the contract. Both helpers accept consumer **and** RPC names — they're overloaded against `InferConsumerNames` and `InferRpcNames`, and `validateHandlerTargetExists` inspects both `contract.consumers` and `contract.rpcs` (an unknown name throws _"Handler target X not found in contract"_).
 
 ```typescript
-import { defineHandler, RetryableError, NonRetryableError } from "@amqp-contract/worker";
+import { declareHandler, RetryableError, NonRetryableError } from "@amqp-contract/worker";
 import { ErrAsync, fromPromise, OkAsync } from "unthrown";
 
-const processOrderHandler = defineHandler(contract, "processOrder", ({ payload }) =>
+const processOrderHandler = declareHandler(contract, "processOrder", ({ payload }) =>
   fromPromise(
     processPayment(payload.orderId),
     (error) => new RetryableError("Payment service unavailable", error),
   ).map(() => undefined),
 );
 
 // Permanent failures use NonRetryableError → DLQ, never retried
-const validateOrderHandler = defineHandler(contract, "validateOrder", ({ payload }) => {
+const validateOrderHandler = declareHandler(contract, "validateOrder", ({ payload }) => {
   if (payload.amount < 1) {
     return ErrAsync(new NonRetryableError("Invalid amount"));
   }
@@ -201,5 +201,5 @@ For the authoritative list, read [`packages/worker/src/index.ts`](../../packages
 
 - Classes: `TypedAmqpWorker`, `RetryableError`, `NonRetryableError`, `MessageValidationError` (the error classes are unthrown `TaggedError`s). `HandlerError` is a **type** (`RetryableError | NonRetryableError`), not a class.
 - Factories / guards: `retryable`, `nonRetryable`, `isRetryableError`, `isNonRetryableError`, `isHandlerError`
-- Helpers: `defineHandler`, `defineHandlers` (both accept consumer **and** RPC names)
+- Helpers: `declareHandler`, `declareHandlers` (both accept consumer **and** RPC names)
 - Types: `CreateWorkerOptions`, `ConsumerOptions`, `WorkerConsumedMessage`, `WorkerInferConsumedMessage`, `WorkerInferConsumerHandler`, `WorkerInferConsumerHandlerEntry`, `WorkerInferConsumerHeaders`, `WorkerInferHandlers` (consumers ∪ rpcs), `WorkerInferRpcConsumedMessage`, `WorkerInferRpcHandler`, `WorkerInferRpcHandlerEntry`, `WorkerInferRpcHeaders`, `WorkerInferRpcRequest`, `WorkerInferRpcResponse`

.agents/rules/recipes.md

@@ -8,17 +8,17 @@ End-to-end how-tos for the changes that come up most. Each recipe lists the exac
 2. **Queue** — `defineQueue(...)` with a `deadLetter` and a `retry` mode (immediate-requeue or ttl-backoff). Quorum by default; classic only if you need priority/exclusive/auto-delete.
 3. **Consumer entry** — `defineEventConsumer(eventPublisher, queue, { routingKey: ... })`. The queue↔exchange binding is auto-generated.
 4. **Add to `defineContract`** under `consumers: { ... }`. Don't add the queue or binding yourself — they're auto-extracted.
-5. **Handler** — implement with `defineHandler(contract, "yourConsumerName", ({ payload, headers }) => …)` returning `AsyncResult<void, HandlerError>`. See [handlers.md](./handlers.md).
+5. **Handler** — implement with `declareHandler(contract, "yourConsumerName", ({ payload, headers }) => …)` returning `AsyncResult<void, HandlerError>`. See [handlers.md](./handlers.md).
 6. **Tests** — integration test in `src/__tests__/<consumer>.spec.ts` using `it` from `@amqp-contract/testing/extension`. Mock the handler with `vi.fn().mockReturnValue(OkAsync(undefined))`.
 7. **Changeset** — `pnpm changeset` with a minor bump. Public API surface grew.
 
 ## Add a new RPC
 
 1. **Schemas** — request and response, both via `defineMessage`.
 2. **Queue** — `defineQueue(...)` for the RPC. Quorum by default. **Configure a `deadLetter`** even though replies, not the queue, drive most failure modes: missing `replyTo` / `correlationId` and response-schema mismatches are surfaced as `NonRetryableError` and the worker `nack`s them without requeue, so without a DLX they're dropped silently.
-3. **RPC entry** — `defineRpc(queue, { request, response })`.
+3. **RPC entry** — `defineRpc(queue, { request, response })`. Typed business errors go in an optional `errors` map whose entries are `{ data: schema, message?: string }` (the raw Standard Schema, NOT `defineMessage`); the optional `message` is the default human message when the handler constructs the error without one.
 4. **Add to `defineContract`** under `rpcs: { ... }`.
-5. **Server-side handler** — define it with `defineHandler(contract, "yourRpcName", ({ payload }) => OkAsync({ /* response */ }))`, via `defineHandlers`, or inline in the `handlers` object passed to `TypedAmqpWorker.create({ handlers: { … } })`. All three are RPC-aware: `defineHandler` / `defineHandlers` are overloaded against `InferRpcNames` and validate the name against both `contract.consumers` and `contract.rpcs`. The worker validates the response against the response schema and publishes back automatically.
+5. **Server-side handler** — define it with `declareHandler(contract, "yourRpcName", ({ payload }) => OkAsync({ /* response */ }))`, via `declareHandlers`, or inline in the `handlers` object passed to `TypedAmqpWorker.create({ handlers: { … } })`. All three are RPC-aware: `declareHandler` / `declareHandlers` are overloaded against `InferRpcNames` and validate the name against both `contract.consumers` and `contract.rpcs`. The worker validates the response against the response schema and publishes back automatically.
 6. **Client call** — `client.call("yourRpcName", request, { timeoutMs: 5_000 })`. `timeoutMs` is required.
 7. **Tests** — round-trip integration test (worker + client both wired up). For "no server" scenarios, just create the client without a worker; for "request validation fails", pass a deliberately wrong payload through `as unknown as ...`.
 8. **Changeset** — minor bump.

.agents/rules/testing.md

@@ -48,7 +48,7 @@ describe("Order Processing", () => {
 
     publishMessage("orders-exchange", "order.created", { orderId: "123" });
 
-    const messages = await waitForMessages({ nbEvents: 1, timeout: 5000 });
+    const messages = await waitForMessages({ count: 1, timeoutMs: 5000 });
     expect(messages).toHaveLength(1);
     expect(messages[0]).toMatchObject({ orderId: "123" });
   });

AGENTS.md

@@ -90,13 +90,18 @@ Each invariant maps to a named guarding test — extend the mapping when you add
 2. **NonRetryableError → exactly one `nack(requeue=false)`** (DLQ, never republished/acked) — `packages/worker/src/invariants.spec.ts`.
 3. **Retryable without retry config → DLQ, not infinite requeue** — `packages/worker/src/invariants.spec.ts`.
 4. **Immediate-requeue honors the retry budget** (requeue below, DLQ at) — `packages/worker/src/invariants.spec.ts`.
-5. **Validation failures bypass the retry pipeline** (deterministic poison → DLQ) — `packages/worker/src/__tests__/worker-retry.spec.ts`.
+5. **Validation failures bypass the retry pipeline** (deterministic poison → DLQ on first delivery, zero retry publishes) — `packages/worker/src/__tests__/worker-retry.spec.ts` ("an invalid payload on a retry-configured queue goes straight to the DLQ with zero retries").
 6. **A message is acked/nacked exactly once** — `packages/worker/src/__tests__/worker-double-ack.spec.ts`.
 7. **Middleware short-circuit skips the handler; its result routes like a handler result** — `packages/worker/src/middleware.spec.ts` + `tests/src/middleware.spec.ts`.
 8. **Middleware-substituted payloads are re-validated before the handler** — `packages/worker/src/middleware.spec.ts` ("threads substituted payloads…") + `tests/src/middleware.spec.ts` ("blocks handler execution when the substitution fails the schema").
-9. **RPC replies require `replyTo` + `correlationId`; undeclared error codes/invalid error data → DLQ, never a malformed reply** — `tests/src/rpc.spec.ts` (undeclared-code and invalid-error-data timeout tests).
-10. **Worker creation fails fast on missing handlers, before any connection is acquired** — `packages/worker/src/worker-cleanup.spec.ts`.
+9. **RPC replies require `replyTo` + `correlationId`; undeclared error codes/invalid error data → DLQ, never a malformed reply** — `tests/src/rpc.spec.ts` (undeclared-code/invalid-error-data timeout tests + "RPC DLQ routing" describe: DLQ delivery for undeclared codes and reply-less requests).
+10. **Worker creation fails fast on missing or non-callable handlers, before any connection is acquired** — `packages/worker/src/worker-cleanup.spec.ts`.
 11. **`createContext` failure routes to DLQ; the handler never runs** — `tests/src/middleware.spec.ts` ("routes a throwing createContext…").
+12. **Compressed and plain payloads survive the wire byte-for-byte** (the channel must never JSON-serialize a Buffer) — `tests/src/compression.spec.ts`.
+13. **`worker.close()` drains in-flight handlers before closing the channel** (their acks land; no redelivery of completed work) — `packages/worker/src/__tests__/worker-close-drain.spec.ts`.
+14. **A classic-queue immediate-requeue retry republishes to THIS queue via the default exchange** (never the original exchange — sibling queues must not see duplicates) — `packages/worker/src/invariants.spec.ts`.
+15. **Connection-pool leases are idempotent and close/create-race-safe** (double release never underflows; an acquire racing the last release gets a fresh connection) — `packages/core/src/connection-manager.spec.ts`.
+16. **Telemetry never throws into the data path** (a buggy provider degrades to "no telemetry") — `packages/core/src/telemetry.spec.ts` ("throwing telemetry providers") + `packages/client/src/interceptors.spec.ts` (sync-throwing interceptor → Defect).
 
 ## Workflow rules for agents
 

README.md

@@ -82,17 +82,18 @@ const worker = await TypedAmqpWorker.create({
     },
   },
   urls: ["amqp://localhost"],
-}).getOrThrow();
+}).get();
 
 // 6. Type-safe publishing with validation
 const client = await TypedAmqpClient.create({
   contract,
   urls: ["amqp://localhost"],
-}).getOrThrow();
+}).get();
 
 // publish() returns an AsyncResult instead of throwing — awaiting it yields a
-// Result. unthrown 4 gates get() to infallible results, so clear the error
-// channel with recover() first (or use .match()). See the error model guide.
+// Result. create()/close() have an empty error channel (E = never), so .get()
+// is correct there; publish() still has a modeled error, so extract it with
+// .getOrThrow() (or handle it with .match()). See the error model guide.
 await client
   .publish("orderCreated", {
     orderId: "ORD-123", // ✅ TypeScript knows!
@@ -101,8 +102,8 @@ await client
   .getOrThrow();
 
 // 7. Clean up
-await client.close().getOrThrow();
-await worker.close().getOrThrow();
+await client.close().get();
+await worker.close().get();
 ```
 
 ▶ For the full runnable version (including the RabbitMQ Docker command), follow the [5-minute quick start](https://btravstack.github.io/amqp-contract/guide/getting-started).
@@ -138,7 +139,7 @@ docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4-management
 | [@amqp-contract/contract](./packages/contract) | Contract builder and type definitions |
 | [@amqp-contract/client](./packages/client)     | Type-safe client for publishing       |
 | [@amqp-contract/worker](./packages/worker)     | Type-safe worker with retry support   |
-| [@amqp-contract/asyncapi](./packages/asyncapi) | AsyncAPI 3.0 generator                |
+| [@amqp-contract/asyncapi](./packages/asyncapi) | AsyncAPI 3.1 generator                |
 
 ## Contributing
 

docs/examples/command-pattern.md

@@ -93,14 +93,14 @@ Only one place implements the command. The worker runs as part of the `payment-s
 // payment-service/src/worker.ts
 import {
   TypedAmqpWorker,
-  defineHandler,
+  declareHandler,
   RetryableError,
   NonRetryableError,
 } from "@amqp-contract/worker";
 import { fromPromise, type AsyncResult, type Result } from "unthrown";
 import { contract } from "@org/payment-contract";
 
-const chargeHandler = defineHandler(contract, "chargeCustomer", ({ payload }) =>
+const chargeHandler = declareHandler(contract, "chargeCustomer", ({ payload }) =>
   fromPromise(
     chargeProvider({
       customerId: payload.customerId,

docs/how-to/add-middleware.md

@@ -19,14 +19,14 @@ A middleware proves something once and passes the result downstream. Handlers re
 ```typescript
 import {
   composeMiddleware,
-  defineMiddleware,
+  declareMiddleware,
   nonRetryable,
   TypedAmqpWorker,
   type EmptyContext,
 } from "@amqp-contract/worker";
 import { ErrAsync } from "unthrown";
 
-const auth = defineMiddleware<EmptyContext, { tenantId: string }>((args, next) => {
+const auth = declareMiddleware<EmptyContext, { tenantId: string }>((args, next) => {
   const tenantId = args.rawMessage.properties.headers?.["x-tenant-id"];
   if (typeof tenantId !== "string") {
     // Short-circuit: routes like any handler error. The handler never runs.
@@ -46,12 +46,12 @@ const worker = await TypedAmqpWorker.create({
 }).get();
 ```
 
-The two type parameters on `defineMiddleware` are the context going in and the context coming out. Without any middleware or `createContext`, handlers get `EmptyContext`.
+The two type parameters on `declareMiddleware` are the context going in and the context coming out. Without any middleware or `createContext`, handlers get `EmptyContext`.
 
 ## Chain several middleware
 
 ```typescript
-const timing = defineMiddleware<{ tenantId: string }, { tenantId: string }>((args, next) => {
+const timing = declareMiddleware<{ tenantId: string }, { tenantId: string }>((args, next) => {
   const start = Date.now();
   return next().tap(() => {
     console.log(`${args.handlerName} (${args.context.tenantId}): ${Date.now() - start}ms`);
@@ -63,6 +63,8 @@ middleware: composeMiddleware(auth, timing),
 
 `composeMiddleware(outermost, …, innermost)` runs left to right. Context types accumulate along the chain, so `timing` sees the `tenantId` that `auth` added, and handlers see the final accumulated type.
 
+The `middleware` option also accepts an array directly — `middleware: [auth, timing]` — with the first entry outermost, mirroring the client's interceptor arrays. At runtime it composes exactly like `composeMiddleware(...)`, but the array form does not thread the stepwise context types across entries: when middleware accumulate typed context for the handlers, pre-compose with `composeMiddleware` so the chain's final context type is inferred into `helpers.context`.
+
 Because `next()` returns the handler's `AsyncResult`, a middleware can post-process it with `.tap`, `.mapErr` or `.flatMapErr`.
 
 ## Inject dependencies per message
@@ -97,7 +99,7 @@ For a dependency-injection graph, [demesne](https://btravstack.github.io/demesne
 `next({ payload })` replaces the payload for everything downstream.
 
 ```typescript
-const normalize = defineMiddleware<EmptyContext, EmptyContext>((args, next) =>
+const normalize = declareMiddleware<EmptyContext, EmptyContext>((args, next) =>
   next({ payload: { ...args.message.payload, email: args.message.payload.email.toLowerCase() } }),
 );
 ```