docs(events-amqp): Testing section + API reference for the FakeAmqpAdapter subpath (connectum#203)

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

@@ -4,6 +4,7 @@
 
 ## Modules
 
+- [testing](testing/index.md)
 - [types](types/index.md)
 
 ## Classes

en/api/@connectum/events-amqp/testing/functions/FakeAmqpAdapter.md

@@ -0,0 +1,37 @@
+[Connectum API Reference](../../../../index.md) / [@connectum/events-amqp](../../index.md) / [testing](../index.md) / FakeAmqpAdapter
+
+# Function: FakeAmqpAdapter()
+
+> **FakeAmqpAdapter**(`options?`): [`FakeAmqpAdapterInstance`](../interfaces/FakeAmqpAdapterInstance.md)
+
+Defined in: [packages/events-amqp/src/testing.ts:192](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/testing.ts#L192)
+
+Create a programmable AMQP adapter test double.
+
+## Parameters
+
+### options?
+
+[`FakeAmqpAdapterOptions`](../interfaces/FakeAmqpAdapterOptions.md) = `{}`
+
+## Returns
+
+[`FakeAmqpAdapterInstance`](../interfaces/FakeAmqpAdapterInstance.md)
+
+## Example
+
+```typescript
+import { FakeAmqpAdapter } from '@connectum/events-amqp/testing';
+import { AmqpPublishTimeoutError } from '@connectum/events-amqp';
+
+const fake = FakeAmqpAdapter();
+const bus = createEventBus({ adapter: fake, routes: [eventRoutes] });
+await bus.start();
+
+// The state-UNKNOWN outcome, untestable against a real broker:
+fake.control.nextPublish(new AmqpPublishTimeoutError('no outcome (UNKNOWN)'));
+await assert.rejects(() => bus.publish(OrderSchema, order), AmqpPublishTimeoutError);
+
+fake.control.dropConnection();          // disconnected → reconnecting
+fake.control.completeRecovery();        // connected { reconnected: true }
+```

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

@@ -0,0 +1,58 @@
+[Connectum API Reference](../../../index.md) / [@connectum/events-amqp](../index.md) / testing
+
+# testing
+
+Programmable AMQP test double — the `@connectum/events-amqp/testing` subpath (#203).
+
+`FakeAmqpAdapter` models the REAL adapter's observable contracts without a
+broker and without importing `amqplib` at runtime:
+
+- the typed error taxonomy (`AmqpConnectionError`, `AmqpTopologyError`, …) —
+  inject outcomes per publish via [FakeAmqpControl.nextPublish](interfaces/FakeAmqpControl.md#nextpublish),
+  including `AmqpPublishTimeoutError`: the state-UNKNOWN outcome that no
+  real broker (or even Toxiproxy) reproduces deterministically;
+- the canonical lifecycle union ([AmqpLifecycleCallbacks.onLifecycle](../types/interfaces/AmqpLifecycleCallbacks.md#onlifecycle))
+  INCLUDING the deprecated flat-callback shim — events go through the real
+  adapter's dispatch, so ordering, shim payloads, and exception isolation
+  match the real adapter by construction;
+- the state machine: `connect()` on a live or recovering (or dead
+  retries-exhausted) adapter throws `already connected` like the real one;
+  a mid-recovery `subscribe()` PARKS and settles with the recovery outcome;
+  the probe-then-recover `connect()` semantics gate on `AmqpTopologyError`
+  exactly like the real probe.
+
+Deliberately NOT modeled (documented divergences):
+- timing: there is no backoff — recovery advances only via explicit
+  [FakeAmqpControl.completeRecovery](interfaces/FakeAmqpControl.md#completerecovery) / [FakeAmqpControl.exhaustRecovery](interfaces/FakeAmqpControl.md#exhaustrecovery)
+  calls, and `reconnecting.delay` is always `0`;
+- a queued topology `failSetup` at `connect()` WITHOUT fail-fast reports
+  `setup-failed { initial: true }` and then connects anyway (the real
+  adapter would keep retrying inside recovery); a NON-topology queued
+  failure at `connect()` is consumed silently and the connect proceeds
+  (the real adapter treats it as transient and blocks in recovery);
+- broker-driven settlement: handler `ack`/`nack` calls are RECORDED (see
+  the [FakeAmqpControl.deliver](interfaces/FakeAmqpControl.md#deliver) result) but do not drive redelivery —
+  re-deliver explicitly with a higher `attempt` to model it. Handler
+  rejections are swallowed exactly like the real consumer (which nacks for
+  redelivery instead of propagating);
+- the wire-level envelope: [FakeAmqpControl.published](interfaces/FakeAmqpControl.md#published) records the
+  bus-facing call as the adapter received it. Wire fidelity is the real
+  adapter's integration-tested domain. Incoming envelope headers ARE
+  handled with parity: `deliver()` honors `x-event-id`/`x-published-at`
+  and strips the internal keys from handler-visible metadata.
+
+## Interfaces
+
+- [FakeAmqpAdapterInstance](interfaces/FakeAmqpAdapterInstance.md)
+- [FakeAmqpAdapterOptions](interfaces/FakeAmqpAdapterOptions.md)
+- [FakeAmqpControl](interfaces/FakeAmqpControl.md)
+- [FakeDeliveryResult](interfaces/FakeDeliveryResult.md)
+- [FakePublishedRecord](interfaces/FakePublishedRecord.md)
+
+## Type Aliases
+
+- [FakePublishOutcome](type-aliases/FakePublishOutcome.md)
+
+## Functions
+
+- [FakeAmqpAdapter](functions/FakeAmqpAdapter.md)

en/api/@connectum/events-amqp/testing/interfaces/FakeAmqpAdapterInstance.md

@@ -0,0 +1,143 @@
+[Connectum API Reference](../../../../index.md) / [@connectum/events-amqp](../../index.md) / [testing](../index.md) / FakeAmqpAdapterInstance
+
+# Interface: FakeAmqpAdapterInstance
+
+Defined in: [packages/events-amqp/src/testing.ts:144](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/testing.ts#L144)
+
+The fake adapter: a drop-in EventAdapter plus its [FakeAmqpControl](FakeAmqpControl.md).
+
+## Extends
+
+- `EventAdapter`
+
+## Properties
+
+### control
+
+> `readonly` **control**: [`FakeAmqpControl`](FakeAmqpControl.md)
+
+Defined in: [packages/events-amqp/src/testing.ts:145](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/testing.ts#L145)
+
+***
+
+### name
+
+> `readonly` **name**: `string`
+
+Defined in: packages/events/dist/index.d.ts:105
+
+Adapter name for identification (e.g., "nats", "kafka", "redis", "memory")
+
+#### Inherited from
+
+`EventAdapter.name`
+
+## Methods
+
+### connect()
+
+> **connect**(`context?`): `Promise`\<`void`\>
+
+Defined in: packages/events/dist/index.d.ts:113
+
+Connect to the message broker.
+
+#### Parameters
+
+##### context?
+
+`AdapterContext`
+
+Optional adapter context with service-level information
+  derived from proto service descriptors. Adapters may use
+  `context.serviceName` for broker-level client identification.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Inherited from
+
+`EventAdapter.connect`
+
+***
+
+### disconnect()
+
+> **disconnect**(): `Promise`\<`void`\>
+
+Defined in: packages/events/dist/index.d.ts:115
+
+Disconnect from the message broker
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Inherited from
+
+`EventAdapter.disconnect`
+
+***
+
+### publish()
+
+> **publish**(`eventType`, `payload`, `options?`): `Promise`\<`void`\>
+
+Defined in: packages/events/dist/index.d.ts:117
+
+Publish a serialized event to a topic
+
+#### Parameters
+
+##### eventType
+
+`string`
+
+##### payload
+
+`Uint8Array`
+
+##### options?
+
+`PublishOptions`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Inherited from
+
+`EventAdapter.publish`
+
+***
+
+### subscribe()
+
+> **subscribe**(`patterns`, `handler`, `options?`): `Promise`\<`EventSubscription`\>
+
+Defined in: packages/events/dist/index.d.ts:119
+
+Subscribe to event patterns with a raw handler
+
+#### Parameters
+
+##### patterns
+
+`string`[]
+
+##### handler
+
+`RawEventHandler`
+
+##### options?
+
+`RawSubscribeOptions`
+
+#### Returns
+
+`Promise`\<`EventSubscription`\>
+
+#### Inherited from
+
+`EventAdapter.subscribe`

en/api/@connectum/events-amqp/testing/interfaces/FakeAmqpAdapterOptions.md

@@ -0,0 +1,28 @@
+[Connectum API Reference](../../../../index.md) / [@connectum/events-amqp](../../index.md) / [testing](../index.md) / FakeAmqpAdapterOptions
+
+# Interface: FakeAmqpAdapterOptions
+
+Defined in: [packages/events-amqp/src/testing.ts:53](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/testing.ts#L53)
+
+Options for [FakeAmqpAdapter](../functions/FakeAmqpAdapter.md).
+
+## Properties
+
+### failFastOnInitialSetupError?
+
+> `readonly` `optional` **failFastOnInitialSetupError?**: `boolean`
+
+Defined in: [packages/events-amqp/src/testing.ts:60](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/testing.ts#L60)
+
+Mirror of the real option: a topology `failSetup(...)` queued before
+`connect()` rejects it with the typed error instead of report-and-proceed.
+
+***
+
+### lifecycle?
+
+> `readonly` `optional` **lifecycle?**: [`AmqpLifecycleCallbacks`](../../types/interfaces/AmqpLifecycleCallbacks.md)
+
+Defined in: [packages/events-amqp/src/testing.ts:55](https://github.com/Connectum-Framework/connectum/blob/main/packages/events-amqp/src/testing.ts#L55)
+
+The same lifecycle surface as the real adapter (union + flat shim).