docs(events-amqp): onLifecycle discriminated union — lifecycle section + API regen

en/api/@connectum/events-amqp/functions/AmqpAdapter.md

@@ -4,7 +4,7 @@
 
 > **AmqpAdapter**(`options`): `EventAdapter`
 
-Defined in: [packages/events-amqp/src/AmqpAdapter.ts:254](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/AmqpAdapter.ts#L254)
+Defined in: [packages/events-amqp/src/AmqpAdapter.ts:335](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/AmqpAdapter.ts#L335)
 
 Create an AMQP/RabbitMQ adapter for @connectum/events.
 

en/api/@connectum/events-amqp/index.md

@@ -59,6 +59,12 @@ Re-exports [AmqpLifecycleCallbacks](types/interfaces/AmqpLifecycleCallbacks.md)
 
 ***
 
+### AmqpLifecycleEvent
+
+Re-exports [AmqpLifecycleEvent](types/type-aliases/AmqpLifecycleEvent.md)
+
+***
+
 ### AmqpPublisherOptions
 
 Re-exports [AmqpPublisherOptions](types/interfaces/AmqpPublisherOptions.md)

en/api/@connectum/events-amqp/types/index.md

@@ -22,6 +22,7 @@ Configuration types for the AMQP/RabbitMQ adapter.
 
 ## Type Aliases
 
+- [AmqpLifecycleEvent](type-aliases/AmqpLifecycleEvent.md)
 - [AmqpTopologyMode](type-aliases/AmqpTopologyMode.md)
 
 ## Variables

en/api/@connectum/events-amqp/types/interfaces/AmqpAdapterOptions.md

@@ -64,7 +64,7 @@ Exchange type.
 
 > `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)
+Defined in: [packages/events-amqp/src/types.ts:152](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L152)
 
 Fail fast on a DETERMINISTIC setup/topology error on the FIRST connect,
 instead of entering amqplib's infinite recovery loop.
@@ -85,8 +85,11 @@ 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.
+Enabling this — or supplying [AmqpLifecycleCallbacks.onLifecycle](AmqpLifecycleCallbacks.md#onlifecycle)
+or [AmqpLifecycleCallbacks.onSetupFailed](AmqpLifecycleCallbacks.md#onsetupfailed) — adds one extra
+short-lived connection plus a topology validation pass at startup for
+the probe (recovery must be enabled; with `recovery: false` no probe
+runs and no `setup-failed` event is delivered).
 
 #### Default
 
@@ -100,7 +103,7 @@ false
 
 > `readonly` `optional` **lifecycle?**: [`AmqpLifecycleCallbacks`](AmqpLifecycleCallbacks.md)
 
-Defined in: [packages/events-amqp/src/types.ts:155](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L155)
+Defined in: [packages/events-amqp/src/types.ts:158](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L158)
 
 Connection lifecycle callbacks. Connection errors are surfaced here —
 not just logged.
@@ -121,7 +124,7 @@ Publisher options.
 
 > `readonly` `optional` **publishTimeoutMs?**: `number`
 
-Defined in: [packages/events-amqp/src/types.ts:165](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L165)
+Defined in: [packages/events-amqp/src/types.ts:168](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L168)
 
 Per-publish broker-outcome deadline in milliseconds. A publish whose
 ack/nack/return/connection-loss outcome does not arrive in time

en/api/@connectum/events-amqp/types/interfaces/AmqpBindingDeclaration.md

@@ -2,23 +2,23 @@
 
 # Interface: AmqpBindingDeclaration
 
-Defined in: [packages/events-amqp/src/types.ts:225](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L225)
+Defined in: [packages/events-amqp/src/types.ts:228](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L228)
 
 ## Properties
 
 ### arguments?
 
 > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\>
 
-Defined in: [packages/events-amqp/src/types.ts:233](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L233)
+Defined in: [packages/events-amqp/src/types.ts:236](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L236)
 
 ***
 
 ### exchange?
 
 > `readonly` `optional` **exchange?**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:229](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L229)
+Defined in: [packages/events-amqp/src/types.ts:232](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L232)
 
 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:227](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L227)
+Defined in: [packages/events-amqp/src/types.ts:230](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L230)
 
 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:232](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L232)
+Defined in: [packages/events-amqp/src/types.ts:235](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L235)
 
 ***
 
 ### source
 
 > `readonly` **source**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:231](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L231)
+Defined in: [packages/events-amqp/src/types.ts:234](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L234)
 
 Source exchange.

en/api/@connectum/events-amqp/types/interfaces/AmqpConsumerOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: AmqpConsumerOptions
 
-Defined in: [packages/events-amqp/src/types.ts:364](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L364)
+Defined in: [packages/events-amqp/src/types.ts:436](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L436)
 
 Consumer options.
 
@@ -12,7 +12,7 @@ Consumer options.
 
 > `readonly` `optional` **exclusive?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:378](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L378)
+Defined in: [packages/events-amqp/src/types.ts:450](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L450)
 
 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:371](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L371)
+Defined in: [packages/events-amqp/src/types.ts:443](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L443)
 
 Prefetch count (QoS) — how many unacknowledged messages
 a consumer can have at a time.

en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeDeclaration.md

@@ -2,15 +2,15 @@
 
 # Interface: AmqpExchangeDeclaration
 
-Defined in: [packages/events-amqp/src/types.ts:207](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L207)
+Defined in: [packages/events-amqp/src/types.ts:210](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L210)
 
 ## Properties
 
 ### arguments?
 
 > `readonly` `optional` **arguments?**: `Record`\<`string`, `unknown`\>
 
-Defined in: [packages/events-amqp/src/types.ts:213](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L213)
+Defined in: [packages/events-amqp/src/types.ts:216](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L216)
 
 Raw AMQP arguments passthrough.
 
@@ -20,28 +20,28 @@ Raw AMQP arguments passthrough.
 
 > `readonly` `optional` **autoDelete?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:211](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L211)
+Defined in: [packages/events-amqp/src/types.ts:214](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L214)
 
 ***
 
 ### durable?
 
 > `readonly` `optional` **durable?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:210](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L210)
+Defined in: [packages/events-amqp/src/types.ts:213](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L213)
 
 ***
 
 ### name
 
 > `readonly` **name**: `string`
 
-Defined in: [packages/events-amqp/src/types.ts:208](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L208)
+Defined in: [packages/events-amqp/src/types.ts:211](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L211)
 
 ***
 
 ### type
 
 > `readonly` **type**: `"headers"` \| `"topic"` \| `"direct"` \| `"fanout"`
 
-Defined in: [packages/events-amqp/src/types.ts:209](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L209)
+Defined in: [packages/events-amqp/src/types.ts:212](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L212)

en/api/@connectum/events-amqp/types/interfaces/AmqpExchangeOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: AmqpExchangeOptions
 
-Defined in: [packages/events-amqp/src/types.ts:313](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L313)
+Defined in: [packages/events-amqp/src/types.ts:385](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L385)
 
 Exchange assertion options.
 
@@ -12,7 +12,7 @@ Exchange assertion options.
 
 > `readonly` `optional` **autoDelete?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:326](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L326)
+Defined in: [packages/events-amqp/src/types.ts:398](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L398)
 
 Whether the exchange is deleted when the last queue unbinds.
 
@@ -28,7 +28,7 @@ false
 
 > `readonly` `optional` **durable?**: `boolean`
 
-Defined in: [packages/events-amqp/src/types.ts:319](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L319)
+Defined in: [packages/events-amqp/src/types.ts:391](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L391)
 
 Whether the exchange should survive broker restarts.
 

en/api/@connectum/events-amqp/types/interfaces/AmqpLifecycleCallbacks.md

@@ -2,29 +2,37 @@
 
 # Interface: AmqpLifecycleCallbacks
 
-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:331](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L331)
 
 Connection lifecycle callbacks.
 
+Prefer the single discriminated [onLifecycle](#onlifecycle) callback; the flat
+callbacks are a compatibility shim over the same event stream and are
+deprecated since 1.3.0 (removal not before 2.0).
+
 ## Properties
 
-### onConnected?
+### ~~onConnected?~~
 
 > `readonly` `optional` **onConnected?**: () => `void`
 
-Defined in: [packages/events-amqp/src/types.ts:285](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L285)
+Defined in: [packages/events-amqp/src/types.ts:351](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L351)
 
 #### Returns
 
 `void`
 
+#### Deprecated
+
+Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "connected"`). Kept until at least 2.0.
+
 ***
 
-### onDisconnected?
+### ~~onDisconnected?~~
 
 > `readonly` `optional` **onDisconnected?**: (`cause`) => `void`
 
-Defined in: [packages/events-amqp/src/types.ts:286](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L286)
+Defined in: [packages/events-amqp/src/types.ts:353](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L353)
 
 #### Parameters
 
@@ -36,13 +44,51 @@ Defined in: [packages/events-amqp/src/types.ts:286](https://github.com/Connectum
 
 `void`
 
+#### Deprecated
+
+Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "disconnected"`). Kept until at least 2.0.
+
 ***
 
-### onReconnectFailed?
+### onLifecycle?
+
+> `readonly` `optional` **onLifecycle?**: (`event`) => `void`
+
+Defined in: [packages/events-amqp/src/types.ts:349](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L349)
+
+Single discriminated-union lifecycle callback — the preferred surface.
+Receives every [AmqpLifecycleEvent](../type-aliases/AmqpLifecycleEvent.md), including `blocked`/`unblocked`,
+which have no flat-callback equivalent. Flat callbacks (if also set) are
+invoked after `onLifecycle` for the same underlying event.
+
+MUST NOT throw: dispatch runs inside the connection driver's event
+handlers, so exceptions are isolated (swallowed) to protect the
+connection — a throwing callback neither disturbs recovery nor starves
+the flat shim.
+
+Setting this (like `onSetupFailed` / `failFastOnInitialSetupError`)
+enables the startup validation probe: one extra short-lived connection
+plus a topology validation pass at `connect()` (requires recovery
+enabled), so `setup-failed { initial: true }` can be delivered for a
+deterministic misconfiguration at boot.
+
+#### Parameters
+
+##### event
+
+[`AmqpLifecycleEvent`](../type-aliases/AmqpLifecycleEvent.md)
+
+#### Returns
+
+`void`
+
+***
+
+### ~~onReconnectFailed?~~
 
 > `readonly` `optional` **onReconnectFailed?**: (`cause`) => `void`
 
-Defined in: [packages/events-amqp/src/types.ts:294](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L294)
+Defined in: [packages/events-amqp/src/types.ts:364](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L364)
 
 #### Parameters
 
@@ -54,13 +100,17 @@ Defined in: [packages/events-amqp/src/types.ts:294](https://github.com/Connectum
 
 `void`
 
+#### Deprecated
+
+Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "reconnect-failed"`). Kept until at least 2.0.
+
 ***
 
-### onReconnecting?
+### ~~onReconnecting?~~
 
 > `readonly` `optional` **onReconnecting?**: (`info`) => `void`
 
-Defined in: [packages/events-amqp/src/types.ts:293](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L293)
+Defined in: [packages/events-amqp/src/types.ts:362](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L362)
 
 A reconnect attempt has been scheduled. Fires exactly ONCE per scheduled
 retry (amqplib's `reconnect-scheduled`). A failed attempt that also emits
@@ -87,13 +137,17 @@ case is reported via [onReconnectFailed](#onreconnectfailed), not here.
 
 `void`
 
+#### Deprecated
+
+Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "reconnecting"`). Kept until at least 2.0.
+
 ***
 
-### onSetupFailed?
+### ~~onSetupFailed?~~
 
 > `readonly` `optional` **onSetupFailed?**: (`error`, `ctx`) => `void`
 
-Defined in: [packages/events-amqp/src/types.ts:307](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L307)
+Defined in: [packages/events-amqp/src/types.ts:379](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/types.ts#L379)
 
 A setup/topology failure occurred while (re)applying the declarative
 topology — on the initial connect's validation probe (`ctx.initial: true`,
@@ -103,8 +157,8 @@ topology — on the initial connect's validation probe (`ctx.initial: true`,
 This surfaces deterministic configuration drift (e.g. a missing queue in
 `check` mode, or a `PRECONDITION_FAILED` redeclare) distinctly from a mere
 broker outage, even when fail-fast is off. The initial-connect invocation
-requires a startup validation probe, which runs when either this callback or
-[AmqpAdapterOptions.failFastOnInitialSetupError](AmqpAdapterOptions.md#failfastoninitialsetuperror) is set.
+requires a startup validation probe, which runs when either this callback,
+[onLifecycle](#onlifecycle), or [AmqpAdapterOptions.failFastOnInitialSetupError](AmqpAdapterOptions.md#failfastoninitialsetuperror) is set.
 
 #### Parameters
 
@@ -125,3 +179,7 @@ requires a startup validation probe, which runs when either this callback or
 #### Returns
 
 `void`
+
+#### Deprecated
+
+Since 1.3.0 — use [onLifecycle](#onlifecycle) (`type: "setup-failed"`). Kept until at least 2.0.