Connectum-Framework · intech · Jul 4, 2026 · Jul 4, 2026
diff --git a/en/api/@connectum/events-amqp/classes/AmqpAdapterError.md b/en/api/@connectum/events-amqp/classes/AmqpAdapterError.md
@@ -2,7 +2,7 @@
 
 # Class: AmqpAdapterError
 
-Defined in: [packages/events-amqp/src/errors.ts:13](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L13)
+Defined in: [packages/events-amqp/src/errors.ts:30](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L30)
 
 Base class for all AMQP adapter errors.
 
@@ -25,7 +25,7 @@ Base class for all AMQP adapter errors.
 
 > **new AmqpAdapterError**(`message`, `options?`): `AmqpAdapterError`
 
-Defined in: [packages/events-amqp/src/errors.ts:14](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L14)
+Defined in: [packages/events-amqp/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L31)
 
 #### Parameters
 

diff --git a/en/api/@connectum/events-amqp/classes/AmqpConnectionError.md b/en/api/@connectum/events-amqp/classes/AmqpConnectionError.md
@@ -2,7 +2,7 @@
 
 # Class: AmqpConnectionError
 
-Defined in: [packages/events-amqp/src/errors.ts:25](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L25)
+Defined in: [packages/events-amqp/src/errors.ts:42](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L42)
 
 Connection is absent, lost, or recovery is in progress / exhausted.
 Publishes during a disconnected window fail fast with this error;
@@ -18,7 +18,7 @@ in-flight confirms are rejected with it on connection loss.
 
 > **new AmqpConnectionError**(`message`, `options?`): `AmqpConnectionError`
 
-Defined in: [packages/events-amqp/src/errors.ts:14](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L14)
+Defined in: [packages/events-amqp/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L31)
 
 #### Parameters
 

diff --git a/en/api/@connectum/events-amqp/classes/AmqpPublishNackError.md b/en/api/@connectum/events-amqp/classes/AmqpPublishNackError.md
@@ -2,7 +2,7 @@
 
 # Class: AmqpPublishNackError
 
-Defined in: [packages/events-amqp/src/errors.ts:41](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L41)
+Defined in: [packages/events-amqp/src/errors.ts:58](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L58)
 
 The broker negatively acknowledged (nacked) a published message.
 
@@ -16,7 +16,7 @@ The broker negatively acknowledged (nacked) a published message.
 
 > **new AmqpPublishNackError**(`message`, `options?`): `AmqpPublishNackError`
 
-Defined in: [packages/events-amqp/src/errors.ts:14](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L14)
+Defined in: [packages/events-amqp/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L31)
 
 #### Parameters
 

diff --git a/en/api/@connectum/events-amqp/classes/AmqpPublishTimeoutError.md b/en/api/@connectum/events-amqp/classes/AmqpPublishTimeoutError.md
@@ -2,7 +2,7 @@
 
 # Class: AmqpPublishTimeoutError
 
-Defined in: [packages/events-amqp/src/errors.ts:48](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L48)
+Defined in: [packages/events-amqp/src/errors.ts:65](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L65)
 
 No broker outcome (ack/nack/return/connection loss) arrived within
 `publishTimeoutMs`. The message state is UNKNOWN — it may or may not
@@ -18,7 +18,7 @@ have been routed; an at-least-once producer should republish.
 
 > **new AmqpPublishTimeoutError**(`message`, `options?`): `AmqpPublishTimeoutError`
 
-Defined in: [packages/events-amqp/src/errors.ts:14](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L14)
+Defined in: [packages/events-amqp/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L31)
 
 #### Parameters
 

diff --git a/en/api/@connectum/events-amqp/classes/AmqpSerializationError.md b/en/api/@connectum/events-amqp/classes/AmqpSerializationError.md
@@ -2,7 +2,7 @@
 
 # Class: AmqpSerializationError
 
-Defined in: [packages/events-amqp/src/errors.ts:58](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L58)
+Defined in: [packages/events-amqp/src/errors.ts:75](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L75)
 
 Payload encoding/decoding failed in a custom serialization hook.
 
@@ -16,7 +16,7 @@ Payload encoding/decoding failed in a custom serialization hook.
 
 > **new AmqpSerializationError**(`message`, `options?`): `AmqpSerializationError`
 
-Defined in: [packages/events-amqp/src/errors.ts:14](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L14)
+Defined in: [packages/events-amqp/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L31)
 
 #### Parameters
 

diff --git a/en/api/@connectum/events-amqp/classes/AmqpTopologyError.md b/en/api/@connectum/events-amqp/classes/AmqpTopologyError.md
@@ -2,7 +2,7 @@
 
 # Class: AmqpTopologyError
 
-Defined in: [packages/events-amqp/src/errors.ts:55](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L55)
+Defined in: [packages/events-amqp/src/errors.ts:72](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L72)
 
 Topology declaration or verification failed: missing exchange/queue in
 `check`/`skip` mode, or a conflicting redeclare (PRECONDITION_FAILED) in
@@ -18,7 +18,7 @@ Topology declaration or verification failed: missing exchange/queue in
 
 > **new AmqpTopologyError**(`message`, `options?`): `AmqpTopologyError`
 
-Defined in: [packages/events-amqp/src/errors.ts:14](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L14)
+Defined in: [packages/events-amqp/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L31)
 
 #### Parameters
 

diff --git a/en/api/@connectum/events-amqp/classes/AmqpUnroutableError.md b/en/api/@connectum/events-amqp/classes/AmqpUnroutableError.md
@@ -2,7 +2,7 @@
 
 # Class: AmqpUnroutableError
 
-Defined in: [packages/events-amqp/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L31)
+Defined in: [packages/events-amqp/src/errors.ts:48](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L48)
 
 The broker returned a `mandatory` message as unroutable
 (`basic.return`): no queue is bound for the routing key.
@@ -17,7 +17,7 @@ The broker returned a `mandatory` message as unroutable
 
 > **new AmqpUnroutableError**(`message`, `routingKey`): `AmqpUnroutableError`
 
-Defined in: [packages/events-amqp/src/errors.ts:34](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L34)
+Defined in: [packages/events-amqp/src/errors.ts:51](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L51)
 
 #### Parameters
 
@@ -79,7 +79,7 @@ Defined in: node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/li
 
 > `readonly` **routingKey**: `string`
 
-Defined in: [packages/events-amqp/src/errors.ts:32](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L32)
+Defined in: [packages/events-amqp/src/errors.ts:49](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/errors.ts#L49)
 
 ***
 

diff --git a/en/api/@connectum/events-amqp/functions/AmqpAdapter.md b/en/api/@connectum/events-amqp/functions/AmqpAdapter.md
@@ -4,7 +4,7 @@
 
 > **AmqpAdapter**(`options`): `EventAdapter`
 
-Defined in: [packages/events-amqp/src/AmqpAdapter.ts:153](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/AmqpAdapter.ts#L153)
+Defined in: [packages/events-amqp/src/AmqpAdapter.ts:254](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/AmqpAdapter.ts#L254)
 
 Create an AMQP/RabbitMQ adapter for @connectum/events.
 

diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpAdapterOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpAdapterOptions.md
@@ -60,11 +60,47 @@ Exchange type.
 
 ***
 
+### failFastOnInitialSetupError?
+
+> `readonly` `optional` **failFastOnInitialSetupError?**: `boolean`
+
+Defined in: [packages/events-amqp/src/types.ts:149](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L149)
+
+Fail fast on a DETERMINISTIC setup/topology error on the FIRST connect,
+instead of entering amqplib's infinite recovery loop.
+
+amqplib's opt-in recovery resolves `connect()` only after its setup hook
+succeeds, and rejects only once `maxRetries` is exhausted (default
+`Infinity`). A permanent topology error on the first connect under the
+default recovery therefore HANGS `connect()` forever, with no thrown error
+and — because the lifecycle listeners attach only after that never-returning
+await — no callback. When this flag is `true` (and recovery is enabled), the
+adapter first validates topology against a throwaway non-recovering
+connection; a topology error rejects `connect()` with the typed
+`AmqpTopologyError` / `AmqpConnectionError`.
+
+Only deterministic setup/topology errors fail fast. A transient
+broker-unreachable at startup is NOT a fail-fast condition — it falls
+through to normal recovery (block-until-broker). SUBSEQUENT reconnects
+always keep infinite-recovery behavior.
+
+No-op with `recovery: false` (that path already fails fast on setup).
+Enabling this (or supplying [AmqpLifecycleCallbacks.onSetupFailed](AmqpLifecycleCallbacks.md#onsetupfailed))
+adds one extra short-lived connection at startup for the validation probe.
+
+#### Default
+
+```ts
+false
+```
+
+***
+
 ### lifecycle?
 
 > `readonly` `optional` **lifecycle?**: [`AmqpLifecycleCallbacks`](AmqpLifecycleCallbacks.md)
 
-Defined in: [packages/events-amqp/src/types.ts:117](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L117)
+Defined in: [packages/events-amqp/src/types.ts:155](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L155)
 
 Connection lifecycle callbacks. Connection errors are surfaced here —
 not just logged.
@@ -85,7 +121,7 @@ Publisher options.
 
 > `readonly` `optional` **publishTimeoutMs?**: `number`
 
-Defined in: [packages/events-amqp/src/types.ts:127](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L127)
+Defined in: [packages/events-amqp/src/types.ts:165](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L165)
 
 Per-publish broker-outcome deadline in milliseconds. A publish whose
 ack/nack/return/connection-loss outcome does not arrive in time
@@ -114,7 +150,7 @@ Default queue assertion options.
 
 > `readonly` `optional` **queueOverrides?**: `Record`\<`string`, [`AmqpQueueOverride`](AmqpQueueOverride.md)\>
 
-Defined in: [packages/events-amqp/src/types.ts:97](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L97)
+Defined in: [packages/events-amqp/src/types.ts:101](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L101)
 
 Map a consumer group name to an externally-named queue.
 
@@ -128,7 +164,7 @@ lets a subscription attach to a queue from an external contract
 
 > `readonly` `optional` **recovery?**: `boolean` \| [`AmqpRecoveryOptions`](AmqpRecoveryOptions.md)
 
-Defined in: [packages/events-amqp/src/types.ts:111](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L111)
+Defined in: [packages/events-amqp/src/types.ts:122](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L122)
 
 Automatic connection recovery (delegated to amqplib's opt-in
 recovery). Enabled by default; pass `false` to restore
@@ -139,6 +175,13 @@ topology (per `topologyMode`), and replays active subscriptions.
 In-flight publishes at the moment of a connection loss reject with
 `AmqpConnectionError`.
 
+`maxRetries` governs BOTH the initial connect and steady-state recovery
+(counter reset on success); under the default `Infinity`, `connect()`
+blocks until the broker is reachable rather than failing fast (see
+[AmqpAdapterOptions.failFastOnInitialSetupError](#failfastoninitialsetuperror) to fail fast on a
+deterministic startup misconfiguration). See [AmqpRecoveryOptions](AmqpRecoveryOptions.md)
+for the retry-budget scope and jitter/`maxDelay` overshoot.
+
 #### Default
 
 ```ts
@@ -190,12 +233,16 @@ exchange-to-exchange.
 
 > `readonly` `optional` **topologyMode?**: [`AmqpTopologyMode`](../type-aliases/AmqpTopologyMode.md)
 
-Defined in: [packages/events-amqp/src/types.ts:88](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L88)
+Defined in: [packages/events-amqp/src/types.ts:92](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L92)
 
 How topology is established:
 - `"assert"` (default) — declare idempotently (assertExchange/assertQueue/bind);
-- `"check"` — existence-only verification (checkExchange/checkQueue), fail
-  fast with AmqpTopologyError on missing objects. AMQP offers no passive
+- `"check"` — existence-only verification (checkExchange/checkQueue). A
+  missing object raises AmqpTopologyError, which fails `connect()` fast
+  ONLY with `recovery: false` or `failFastOnInitialSetupError: true`; under
+  the default recovery a first-connect check failure otherwise enters the
+  (infinite) recovery loop and is surfaced via `onSetupFailed` /
+  `onReconnecting` rather than rejecting `connect()`. AMQP offers no passive
   introspection: argument equivalence and binding presence are NOT
   verifiable in this mode (a conflicting redeclare elsewhere is
   PRECONDITION_FAILED 406);

diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpBindingDeclaration.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpBindingDeclaration.md
@@ -2,23 +2,23 @@
 
 # Interface: AmqpBindingDeclaration
 
-Defined in: [packages/events-amqp/src/types.ts:187](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L187)
+Defined in: [packages/events-amqp/src/types.ts:225](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L225)
 
 ## Properties
 
 ### arguments?
 
 > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\>
 
-Defined in: [packages/events-amqp/src/types.ts:195](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L195)
+Defined in: [packages/events-amqp/src/types.ts:233](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L233)
 
 ***
 
 ### exchange?
 
 > `readonly` `optional` **exchange?**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:191](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L191)
+Defined in: [packages/events-amqp/src/types.ts:229](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L229)
 
 Destination exchange name (exchange-to-exchange binding).
 
@@ -28,7 +28,7 @@ Destination exchange name (exchange-to-exchange binding).
 
 > `readonly` `optional` **queue?**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:189](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L189)
+Defined in: [packages/events-amqp/src/types.ts:227](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L227)
 
 Destination queue name (queue binding) — mutually exclusive with `exchange`.
 
@@ -38,14 +38,14 @@ Destination queue name (queue binding) — mutually exclusive with `exchange`.
 
 > `readonly` **routingKey**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:194](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L194)
+Defined in: [packages/events-amqp/src/types.ts:232](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L232)
 
 ***
 
 ### source
 
 > `readonly` **source**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:193](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L193)
+Defined in: [packages/events-amqp/src/types.ts:231](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L231)
 
 Source exchange.
diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpConsumerOptions.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpConsumerOptions.md
@@ -2,7 +2,7 @@
 
 # Interface: AmqpConsumerOptions
 
-Defined in: [packages/events-amqp/src/types.ts:284](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L284)
+Defined in: [packages/events-amqp/src/types.ts:364](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L364)
 
 Consumer options.
 
@@ -12,7 +12,7 @@ Consumer options.
 
 > `readonly` `optional` **exclusive?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:298](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L298)
+Defined in: [packages/events-amqp/src/types.ts:378](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L378)
 
 Whether the consumer is exclusive to this connection.
 
@@ -28,7 +28,7 @@ false
 
 > `readonly` `optional` **prefetch?**: `number`
 
-Defined in: [packages/events-amqp/src/types.ts:291](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L291)
+Defined in: [packages/events-amqp/src/types.ts:371](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L371)
 
 Prefetch count (QoS) — how many unacknowledged messages
 a consumer can have at a time.

diff --git a/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeDeclaration.md b/en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeDeclaration.md
@@ -2,15 +2,15 @@
 
 # Interface: AmqpExchangeDeclaration
 
-Defined in: [packages/events-amqp/src/types.ts:169](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L169)
+Defined in: [packages/events-amqp/src/types.ts:207](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L207)
 
 ## Properties
 
 ### arguments?
 
 > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\>
 
-Defined in: [packages/events-amqp/src/types.ts:175](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L175)
+Defined in: [packages/events-amqp/src/types.ts:213](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L213)
 
 Raw AMQP arguments passthrough.
 
@@ -20,28 +20,28 @@ Raw AMQP arguments passthrough.
 
 > `readonly` `optional` **autoDelete?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:173](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L173)
+Defined in: [packages/events-amqp/src/types.ts:211](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L211)
 
 ***
 
 ### durable?
 
 > `readonly` `optional` **durable?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:172](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L172)
+Defined in: [packages/events-amqp/src/types.ts:210](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L210)
 
 ***
 
 ### name
 
 > `readonly` **name**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:170](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L170)
+Defined in: [packages/events-amqp/src/types.ts:208](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L208)
 
 ***
 
 ### type
 
 > `readonly` **type**: `"headers"` \| `"topic"` \| `"direct"` \| `"fanout"`
 
-Defined in: [packages/events-amqp/src/types.ts:171](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L171)
+Defined in: [packages/events-amqp/src/types.ts:209](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L209)