@lindorm/iris 0.2.0 → 0.4.0

package/README.md

@@ -1,27 +1,35 @@
 # @lindorm/iris
 
-Unified messaging library for Node.js with a single decorator-driven API across multiple brokers. Define messages once, deploy to any backend.
+Decorator-driven messaging for Node.js with a single API across multiple brokers. Define messages once, publish and subscribe against memory, RabbitMQ, Kafka, NATS, or Redis Streams.
+
+## Install
+
+```bash
+npm install @lindorm/iris
+```
+
+This package is **ESM-only** and ships native (TC39 stage 3) decorators. Use it from an ESM project (`"type": "module"`) and a TypeScript version that supports stage 3 decorators (TS 5+). The package polyfills `Symbol.metadata` for older Node versions, so no extra setup is required.
 
 ## Supported Drivers
 
-| Driver       | Peer Dependency | Use Case                            |
-| ------------ | --------------- | ----------------------------------- |
-| **Memory**   | _(none)_        | Testing, prototyping                |
-| **RabbitMQ** | `amqplib`       | Task queues, complex routing        |
-| **Kafka**    | `kafkajs`       | High-throughput event streaming     |
-| **NATS**     | `nats`          | Low-latency, cloud-native systems   |
-| **Redis**    | `ioredis`       | Lightweight streams, existing infra |
+Iris is broker-agnostic. The driver is chosen via the `IrisSource` constructor; the matching peer dependency is loaded lazily and only needs to be installed for the driver(s) you use.
 
-Install only the peer dependency for the driver(s) you use:
+| Driver   | Peer Dependency |
+| -------- | --------------- |
+| `memory` | _(none)_        |
+| `rabbit` | `amqplib` ^0.10 |
+| `kafka`  | `kafkajs` ^2.2  |
+| `nats`   | `nats` ^2.29    |
+| `redis`  | `ioredis` ^5.10 |
 
-```bash
-npm install @lindorm/iris
+`@lindorm/amphora` ^0.4 is an optional peer used for payload encryption (`@Encrypted`). `@lindorm/logger` ^0.5 is a required peer — every `IrisSource` takes an `ILogger`.
 
-# Pick one or more:
-npm install amqplib        # RabbitMQ
-npm install kafkajs        # Kafka
-npm install nats           # NATS
-npm install ioredis        # Redis Streams
+```bash
+npm install amqplib       # RabbitMQ
+npm install kafkajs       # Kafka
+npm install nats          # NATS
+npm install ioredis       # Redis Streams
+npm install @lindorm/amphora  # Encryption (optional)
 ```
 
 ## Quick Start
@@ -30,14 +38,13 @@ npm install ioredis        # Redis Streams
 
 ```typescript
 import {
-  Message,
-  Namespace,
-  Version,
   Field,
   IdentifierField,
+  Message,
+  Namespace,
   TimestampField,
+  Version,
 } from "@lindorm/iris";
-import type { IMessage } from "@lindorm/iris";
 
 @Message()
 @Namespace("orders")
@@ -50,7 +57,7 @@ class OrderPlaced {
 }
 ```
 
-### 2. Create a Source and Connect
+### 2. Create a Source
 
 ```typescript
 import { IrisSource } from "@lindorm/iris";
@@ -71,7 +78,6 @@ await source.setup();
 ```typescript
 const bus = source.messageBus(OrderPlaced);
 
-// Subscribe
 await bus.subscribe({
   topic: "OrderPlaced",
   queue: "order-service",
@@ -80,7 +86,6 @@ await bus.subscribe({
   },
 });
 
-// Publish
 const msg = bus.create({ orderId: "abc-123", total: 59.99 });
 await bus.publish(msg);
 ```
@@ -92,78 +97,13 @@ await source.drain();
 await source.disconnect();
 ```
 
-## Table of Contents
-
-- [Messaging Patterns](#messaging-patterns)
-  - [Publisher (Fire-and-Forget)](#publisher-fire-and-forget)
-  - [Message Bus (Pub/Sub + Queues)](#message-bus-pubsub--queues)
-  - [Worker Queue (Competing Consumers)](#worker-queue-competing-consumers)
-  - [RPC (Request/Response)](#rpc-requestresponse)
-  - [Stream Processor (Pipelines)](#stream-processor-pipelines)
-- [Field Types](#field-types)
-- [Decorators](#decorators)
-  - [Class-Level Decorators](#class-level-decorators)
-    - [`@Message`](#message)
-    - [`@AbstractMessage`](#abstractmessage)
-    - [`@Namespace`](#namespace)
-    - [`@Version`](#version)
-    - [`@Topic`](#topic)
-    - [`@Broadcast`](#broadcast)
-    - [`@Persistent`](#persistent)
-    - [`@Priority`](#priority)
-    - [`@Delay`](#delay)
-    - [`@Expiry`](#expiry)
-    - [`@Encrypted`](#encrypted)
-    - [`@Compressed`](#compressed)
-    - [`@Retry`](#retry)
-    - [`@DeadLetter`](#deadletter)
-  - [Field Decorators](#field-decorators)
-    - [`@Field`](#field)
-    - [`@IdentifierField`](#identifierfield)
-    - [`@CorrelationField`](#correlationfield)
-    - [`@TimestampField`](#timestampfield)
-    - [`@MandatoryField`](#mandatoryfield)
-    - [`@PersistentField`](#persistentfield)
-  - [Field Modifiers](#field-modifiers)
-    - [`@Generated`](#generated)
-    - [`@Header`](#header)
-    - [`@Enum`](#enum)
-    - [`@Min` / `@Max`](#min--max)
-    - [`@Schema`](#schema)
-    - [`@Transform`](#transform)
-  - [Lifecycle Hook Decorators](#lifecycle-hook-decorators)
-    - [`@OnCreate`](#oncreate)
-    - [`@OnHydrate`](#onhydrate)
-    - [`@OnValidate`](#onvalidate)
-    - [`@BeforePublish` / `@AfterPublish`](#beforepublish--afterpublish)
-    - [`@BeforeConsume` / `@AfterConsume`](#beforeconsume--afterconsume)
-    - [`@OnConsumeError`](#onconsumeerror)
-- [Retry and Dead Letter](#retry-and-dead-letter)
-- [Dynamic Topics](#dynamic-topics)
-- [Encryption and Compression](#encryption-and-compression)
-- [Message Subscribers](#message-subscribers)
-- [Hook Execution Order](#hook-execution-order)
-- [Consume Envelope](#consume-envelope)
-- [Message Manipulation](#message-manipulation)
-- [Publish Options](#publish-options)
-- [Zod Validation](#zod-validation)
-- [Cloning](#cloning)
-- [Driver Configuration](#driver-configuration)
-  - [Memory](#memory)
-  - [RabbitMQ](#rabbitmq)
-  - [Kafka](#kafka)
-  - [NATS](#nats)
-  - [Redis Streams](#redis-streams)
-- [Persistence (Delay and Dead Letter Stores)](#persistence-delay-and-dead-letter-stores)
-- [Connection State](#connection-state)
-- [Testing with Mocks](#testing-with-mocks)
-- [Error Classes](#error-classes)
-
 ## Messaging Patterns
 
-### Publisher (Fire-and-Forget)
+Every primitive below is created from an `IrisSource` (or a session — see [Sessions](#sessions)) and is bound to a single message class.
+
+### Publisher
 
-Write-only. No subscriptions.
+Write-only. Use when a service produces messages but never consumes them.
 
 ```typescript
 const pub = source.publisher(OrderPlaced);
@@ -171,68 +111,60 @@ const pub = source.publisher(OrderPlaced);
 const msg = pub.create({ orderId: "abc-123", total: 59.99 });
 await pub.publish(msg);
 
-// Batch publish
 await pub.publish([msg1, msg2, msg3]);
 ```
 
-### Message Bus (Pub/Sub + Queues)
+### Message Bus
 
-Publish with topic-based subscriptions. Supports broadcast and competing-consumer queues.
+Pub/sub with topic-based subscriptions. Supports broadcast and competing-consumer queues.
 
 ```typescript
 const bus = source.messageBus(OrderPlaced);
 
-// Broadcast: every subscriber receives every message
 await bus.subscribe({
   topic: "OrderPlaced",
   callback: async (msg) => {
-    /* ... */
+    /* every subscriber gets every message */
   },
 });
 
-// Queue: messages are distributed round-robin among consumers
 await bus.subscribe({
   topic: "OrderPlaced",
   queue: "order-processors",
   callback: async (msg) => {
-    /* ... */
+    /* round-robin across consumers in this queue */
   },
 });
 
-// Multiple subscriptions at once
 await bus.subscribe([
   { topic: "OrderPlaced", queue: "analytics", callback: handleAnalytics },
   { topic: "OrderPlaced", queue: "notifications", callback: handleNotify },
 ]);
 
-// Unsubscribe
 await bus.unsubscribe({ topic: "OrderPlaced", queue: "analytics" });
 await bus.unsubscribeAll();
 ```
 
-### Worker Queue (Competing Consumers)
+### Worker Queue
 
-Specialised for job distribution where each message is processed by exactly one consumer.
+Specialised competing-consumer queue where every message is processed by exactly one consumer.
 
 ```typescript
 const queue = source.workerQueue(OrderPlaced);
 
-// Register competing consumers
 await queue.consume("process-orders", async (msg, envelope) => {
   console.log(`Processing order ${msg.orderId} (attempt ${envelope.attempt})`);
 });
 
-// Publish work
 await queue.publish(queue.create({ orderId: "abc-123", total: 59.99 }));
 
-// Clean up
 await queue.unconsume("process-orders");
 await queue.unconsumeAll();
 ```
 
-### RPC (Request/Response)
+### RPC
 
-Synchronous request/response over the message broker.
+Request/response over the broker.
 
 ```typescript
 @Message()
@@ -249,7 +181,6 @@ class PriceResponse {
 const client = source.rpcClient(GetPrice, PriceResponse);
 const server = source.rpcServer(GetPrice, PriceResponse);
 
-// Server: register handler
 await server.serve(async (req) => {
   const res = new PriceResponse();
   res.price = await lookupPrice(req.sku);
@@ -257,38 +188,21 @@ await server.serve(async (req) => {
   return res;
 });
 
-// Client: send request
 const req = new GetPrice();
 req.sku = "WIDGET-42";
 
 const res = await client.request(req);
-console.log(`${res.price} ${res.currency}`); // 29.99 USD
-
-// With timeout
-const res2 = await client.request(req, { timeout: 5000 });
+const resWithTimeout = await client.request(req, { timeout: 5000 });
 
-// Clean up
 await client.close();
 await server.unserveAll();
 ```
 
-### Stream Processor (Pipelines)
+### Stream Processor
 
-Declarative stream processing with an immutable builder pattern.
+Declarative pipelines built with an immutable builder. The pipeline is started, paused, resumed, and stopped explicitly.
 
 ```typescript
-@Message()
-class RawEvent {
-  @Field("string") type!: string;
-  @Field("float") value!: number;
-}
-
-@Message()
-class AggregatedEvent {
-  @Field("float") sum!: number;
-  @Field("integer") count!: number;
-}
-
 const pipeline = source
   .stream()
   .from(RawEvent)
@@ -302,22 +216,23 @@ const pipeline = source
   .to(AggregatedEvent);
 
 await pipeline.start();
-// pipeline.isRunning() === true
-
+pipeline.isRunning(); // true
 await pipeline.pause();
 await pipeline.resume();
 await pipeline.stop();
 ```
 
+The builder also exposes `flatMap((msg) => Array<T>)` and `batch(size, { timeout? })` between `from(...)` and `to(...)`.
+
 ## Field Types
 
-The `@Field()` decorator accepts the following type identifiers:
+`@Field()` accepts the following type identifiers:
 
 | Category       | Types                            |
 | -------------- | -------------------------------- |
 | Boolean        | `boolean`                        |
 | Integer        | `integer`, `bigint`              |
-| Floating Point | `float`                          |
+| Floating point | `float`                          |
 | String         | `string`, `email`, `url`, `uuid` |
 | Enum           | `enum`                           |
 | Date/Time      | `date`                           |
@@ -325,7 +240,7 @@ The `@Field()` decorator accepts the following type identifiers:
 
 ```typescript
 @Message()
-class FullExample {
+class Example {
   @IdentifierField() id!: string;
   @CorrelationField() correlationId!: string;
   @TimestampField() createdAt!: Date;
@@ -341,24 +256,22 @@ class FullExample {
   @Field("array") tags!: Array<string>;
   @Field("object") metadata!: Record<string, unknown>;
 
-  @Field("string", { nullable: true }) description!: string | null;
-  @Field("string", { optional: true }) nickname?: string;
-  @Field("integer", { default: 0 }) retryCount!: number;
-  @Field("string", { default: () => "generated" }) code!: string;
+  @Nullable() @Field("string") description!: string | null;
+  @Optional() @Field("string") nickname?: string;
+  @Default(0) @Field("integer") retryCount!: number;
+  @Default(() => "generated") @Field("string") code!: string;
 }
 ```
 
 ## Decorators
 
-All decorators use the TC39 (stage 3) decorator specification. Class decorators receive `ClassDecoratorContext`, field decorators receive `ClassFieldDecoratorContext`. Metadata flows through the `Symbol.metadata` prototype chain, so abstract base class decorators are inherited by concrete subclasses.
+All decorators use the TC39 stage 3 specification. Class decorators receive `ClassDecoratorContext`, field decorators receive `ClassFieldDecoratorContext`. Metadata flows through the `Symbol.metadata` prototype chain, so abstract base classes propagate fields and hooks to concrete subclasses automatically.
 
 ### Class-Level Decorators
 
-These decorators are applied to classes and configure message-wide behavior.
-
 #### `@Message`
 
-Marks a class as a concrete message type registered in the global message registry. Every message class must have exactly one of `@Message` or `@AbstractMessage`.
+Marks a class as a concrete message and registers it in the global message registry. Every message must have exactly one of `@Message` or `@AbstractMessage`.
 
 ```typescript
 @Message()
@@ -366,17 +279,17 @@ class OrderPlaced {
   /* ... */
 }
 
-@Message({ name: "order-placed" }) // custom message name
-class OrderPlaced {
+@Message({ name: "order-placed" })
+class OrderPlaced_v1 {
   /* ... */
 }
 ```
 
-**Options:** `{ name?: string }` — Override the message name. Defaults to the class name with any trailing version suffix (`_v1`, `_V2`) stripped. Must not conflict with other registered message names.
+**Options:** `{ name?: string }` — overrides the registered name. Defaults to the class name with any trailing `_v1`/`_V2` suffix stripped. Names must be unique across the registry.
 
 #### `@AbstractMessage`
 
-Marks a class as an abstract message base. It is **not** registered in the global message registry. Fields, hooks, and metadata are inherited by `@Message()` subclasses via the `Symbol.metadata` prototype chain.
+Marks a class as an abstract base. The class is **not** registered. Fields, hooks, and metadata are inherited by `@Message` subclasses through the metadata prototype chain.
 
 ```typescript
 @AbstractMessage()
@@ -392,11 +305,9 @@ class OrderPlaced extends BaseEvent {
 }
 ```
 
-Cannot be combined with `@Message` on the same class.
-
 #### `@Namespace`
 
-Places the message in a named namespace for logical grouping and routing.
+Places the message in a named namespace for routing and grouping.
 
 ```typescript
 @Namespace("orders")
@@ -406,11 +317,11 @@ class OrderPlaced {
 }
 ```
 
-**Argument:** `string` — must be non-empty. Throws `IrisMetadataError` if empty or whitespace-only.
+**Argument:** `string` — non-empty, non-whitespace. Throws `IrisMetadataError` otherwise.
 
 #### `@Version`
 
-Sets the message schema version. Useful for evolving message formats while maintaining backward compatibility.
+Sets the message schema version.
 
 ```typescript
 @Version(1)
@@ -420,14 +331,14 @@ class OrderPlaced {
 }
 ```
 
-**Argument:** `number` — must be a positive integer (>= 1). Throws `IrisMetadataError` otherwise.
+**Argument:** `number` — positive integer (>= 1). Throws `IrisMetadataError` otherwise.
 
 #### `@Topic`
 
-Provides a dynamic topic resolution callback. Instead of using the message class name as the topic, the callback computes the topic from the message content at publish time.
+Provides a callback that resolves the routing topic dynamically from the message instance instead of using the class name.
 
 ```typescript
-@Topic((msg: any) => `events.${msg.region}.${msg.type}`)
+@Topic((msg: RegionalEvent) => `events.${msg.region}.${msg.type}`)
 @Message()
 class RegionalEvent {
   @Field("string") region!: string;
@@ -435,128 +346,118 @@ class RegionalEvent {
 }
 ```
 
-**Argument:** `(message: any) => string` — receives the message instance, returns the routing topic string.
+**Argument:** `(message: any) => string`.
 
 #### `@Broadcast`
 
-Marks a message for broadcast delivery. When published, the message is delivered to **all** subscribers rather than being distributed round-robin to one consumer per queue.
+Marks a message for broadcast delivery. Every subscriber receives every message rather than competing for it.
 
 ```typescript
 @Broadcast()
 @Message()
 class SystemNotification {
-  @Field("string") text!: string;
+  /* ... */
 }
 ```
 
-No arguments.
-
 #### `@Persistent`
 
-Marks a message as persistent/durable. Persistent messages survive broker restarts (where supported by the driver).
+Marks a message as durable. Persistent messages survive broker restarts where the underlying driver supports it.
 
 ```typescript
 @Persistent()
 @Message()
 class PaymentCharge {
-  @Field("string") chargeId!: string;
+  /* ... */
 }
 ```
 
-No arguments.
-
 #### `@Priority`
 
-Sets the default priority for a message type. Higher priority messages are delivered before lower priority ones (where supported by the driver).
+Default priority for a message type. Higher priority messages are delivered first where supported.
 
 ```typescript
 @Priority(8)
 @Message()
 class UrgentAlert {
-  @Field("string") text!: string;
+  /* ... */
 }
 ```
 
-**Argument:** `number` — integer between 0 and 10 inclusive. Throws `IrisMetadataError` if out of range or not an integer.
+**Argument:** `number` — integer in `[0, 10]`. Throws `IrisMetadataError` otherwise.
 
 #### `@Delay`
 
-Sets a default delivery delay. The message is held for the specified duration before being delivered to consumers.
+Default delivery delay in milliseconds. Messages are held until the delay elapses. Can be overridden per publish via `PublishOptions.delay`.
 
 ```typescript
-@Delay(5000) // 5 seconds
+@Delay(5000)
 @Message()
 class ScheduledReminder {
-  @Field("string") text!: string;
+  /* ... */
 }
 ```
 
-**Argument:** `number` — non-negative integer in milliseconds. Throws `IrisMetadataError` if negative or not an integer.
-
-Can be overridden per-publish via `PublishOptions.delay`.
+**Argument:** `number` — non-negative integer.
 
 #### `@Expiry`
 
-Sets a default message TTL (time-to-live). Messages that are not consumed within this window are discarded.
+Default TTL in milliseconds. Unconsumed messages are discarded after this window. Can be overridden per publish via `PublishOptions.expiry`.
 
 ```typescript
-@Expiry(60000) // 1 minute
+@Expiry(60000)
 @Message()
 class TemporaryOffer {
-  @Field("float") discount!: number;
+  /* ... */
 }
 ```
 
-**Argument:** `number` — non-negative integer in milliseconds. Throws `IrisMetadataError` if negative or not an integer.
-
-Can be overridden per-publish via `PublishOptions.expiry`.
+**Argument:** `number` — non-negative integer.
 
 #### `@Encrypted`
 
-Enables payload encryption via `@lindorm/amphora`. The entire message payload is encrypted before publishing and decrypted on consume. Requires an `IAmphora` instance configured on `IrisSource`.
+Encrypts the payload via `@lindorm/amphora` before publishing and decrypts on consume. Requires `amphora` on `IrisSource`.
 
 ```typescript
-@Encrypted() // encrypt with any available key
+@Encrypted()
 @Message()
 class SensitivePayload {
   @Field("string") ssn!: string;
 }
 
-@Encrypted({ purpose: "pii" }) // filter keys by purpose
+@Encrypted({ purpose: "pii" })
 @Message()
 class MedicalRecord {
-  @Field("json") data!: Record<string, unknown>;
+  @Field("object") data!: Record<string, unknown>;
 }
 ```
 
-**Argument:** `AmphoraPredicate` (optional, defaults to `{}`) — a predicate object to filter which encryption key to use from the key store. Supports fields like `algorithm`, `encryption`, `purpose`, `type`, `ownerId`, and standard predicate operators (`$eq`, `$in`, `$neq`, etc.).
+**Argument:** `AmphoraPredicate` (defaults to `{}`) — predicate object that selects which key from the amphora key store is used (e.g. `algorithm`, `encryption`, `purpose`, `type`, `ownerId`, plus the standard `$eq`, `$in`, `$neq` operators).
 
 #### `@Compressed`
 
-Enables payload compression before publishing and decompression on consume.
+Compresses the payload before publishing.
 
 ```typescript
 @Compressed() // gzip (default)
-@Compressed("brotli") // brotli compression
+@Compressed("brotli") // brotli
 @Message()
 class LargePayload {
   @Field("object") data!: Record<string, unknown>;
 }
 ```
 
-**Argument:** `"gzip" | "deflate" | "brotli"` (optional, defaults to `"gzip"`).
-
-When combined with `@Encrypted`, compression is applied first, then encryption.
+**Argument:** `"gzip" | "deflate" | "brotli"` (defaults to `"gzip"`). When combined with `@Encrypted`, compression runs first.
 
 #### `@Retry`
 
-Configures automatic retry behavior when a consume callback throws. Failed messages are retried with configurable backoff strategies.
+Configures retry behavior when a consume callback throws.
 
 ```typescript
-@Retry() // defaults: 3 retries, constant 1s delay
+@Retry()
 @Message()
 class ProcessOrder {
-  @Field("string") orderId!: string;
+  /* ... */
 }
 
 @Retry({
@@ -569,253 +470,147 @@ class ProcessOrder {
 })
 @Message()
 class PaymentCharge {
-  @Field("string") chargeId!: string;
+  /* ... */
 }
 ```
 
 **Options:**
 
-| Field        | Type                                          | Default      | Description                               |
-| ------------ | --------------------------------------------- | ------------ | ----------------------------------------- |
-| `maxRetries` | `number`                                      | `3`          | Maximum number of retry attempts          |
-| `strategy`   | `"constant"` \| `"linear"` \| `"exponential"` | `"constant"` | Backoff strategy                          |
-| `delay`      | `number`                                      | `1000`       | Initial delay in milliseconds             |
-| `delayMax`   | `number`                                      | `30000`      | Maximum delay cap in milliseconds         |
-| `multiplier` | `number`                                      | `2`          | Multiplier for exponential backoff        |
-| `jitter`     | `boolean`                                     | `false`      | Add randomness to prevent thundering herd |
-
-**Retry strategies:**
-
-| Strategy        | Delay pattern (base=1000, multiplier=2)     |
-| --------------- | ------------------------------------------- |
-| `"constant"`    | 1000, 1000, 1000, ...                       |
-| `"linear"`      | 1000, 2000, 3000, ...                       |
-| `"exponential"` | 1000, 2000, 4000, 8000, ... (capped at max) |
+| Field        | Type                                          | Default      | Description                            |
+| ------------ | --------------------------------------------- | ------------ | -------------------------------------- |
+| `maxRetries` | `number`                                      | `3`          | Maximum number of retry attempts       |
+| `strategy`   | `"constant"` \| `"linear"` \| `"exponential"` | `"constant"` | Backoff strategy                       |
+| `delay`      | `number`                                      | `1000`       | Initial delay in milliseconds          |
+| `delayMax`   | `number`                                      | `30000`      | Maximum delay cap in milliseconds      |
+| `multiplier` | `number`                                      | `2`          | Multiplier used by exponential backoff |
+| `jitter`     | `boolean`                                     | `false`      | Add randomness to spread retry storms  |
+
+| Strategy        | Delay sequence (`delay=1000`, `multiplier=2`)        |
+| --------------- | ---------------------------------------------------- |
+| `"constant"`    | `1000, 1000, 1000, ...`                              |
+| `"linear"`      | `1000, 2000, 3000, ...`                              |
+| `"exponential"` | `1000, 2000, 4000, 8000, ...` (capped at `delayMax`) |
 
 #### `@DeadLetter`
 
-Routes messages that have exhausted all retry attempts to the dead letter store. Requires `@Retry` and a dead letter store configured via `IrisSource.persistence.deadLetter`.
+Routes messages that exhaust all retries to the configured dead letter store. Requires `@Retry` and `IrisSource.persistence.deadLetter`.
 
 ```typescript
 @Retry({ maxRetries: 3 })
 @DeadLetter()
 @Message()
 class PaymentCharge {
-  @Field("string") chargeId!: string;
+  /* ... */
 }
 ```
 
-No arguments.
-
----
-
 ### Field Decorators
 
-These decorators are applied to class properties and declare message fields. Each field decorator creates a complete field definition with its type, default value, and nullability.
+Each field decorator declares one message field with its type, default, and nullability. Combine with the modifier decorators below.
 
 #### `@Field`
 
-The foundational field decorator. Declares a message field with an explicit type.
+Declares a field with an explicit type from the [Field Types](#field-types) table.
 
 ```typescript
-@Field("string")
-name!: string;
-
-@Field("integer")
-count!: number;
-
-@Field("float")
-price!: number;
-
-@Field("boolean")
-active!: boolean;
-
-@Field("date")
-expiresAt!: Date;
-
-@Field("uuid")
-referenceId!: string;
-
-@Field("email")
-contactEmail!: string;
-
-@Field("url")
-callbackUrl!: string;
-
-@Field("array")
-tags!: Array<string>;
-
-@Field("object")
-metadata!: Record<string, unknown>;
+@Field("string") name!: string;
+@Field("integer") count!: number;
+@Field("date") expiresAt!: Date;
+@Field("array") tags!: Array<string>;
+@Field("object") metadata!: Record<string, unknown>;
 ```
 
-**Arguments:** `(type: MetaFieldType, options?: FieldDecoratorOptions)`.
-
-**Options:**
-
-| Field       | Type                             | Default | Description                               |
-| ----------- | -------------------------------- | ------- | ----------------------------------------- |
-| `nullable`  | `boolean`                        | `false` | Allow `null` values                       |
-| `optional`  | `boolean`                        | `false` | Field may be omitted                      |
-| `default`   | `value \| (() => value) \| null` | `null`  | Default value applied on create           |
-| `transform` | `MetaTransform \| null`          | `null`  | Inline serialisation/deserialisation pair |
-
-```typescript
-@Field("string", { nullable: true })
-description!: string | null;
-
-@Field("string", { optional: true })
-nickname?: string;
-
-@Field("integer", { default: 0 })
-retryCount!: number;
-
-@Field("string", { default: () => "generated" })
-code!: string;
-
-@Field("float", {
-  transform: {
-    to: (value: number) => Math.round(value * 100),
-    from: (raw: number) => raw / 100,
-  },
-})
-price!: number;
-```
+**Argument:** `MetaFieldType` (re-exported as `IrisFieldType`).
 
 #### `@IdentifierField`
 
-Shorthand for a UUID primary identifier field. Auto-generates a UUID v4 on message creation.
+Auto-generated UUID v4 primary identifier. Equivalent to `@Default(() => randomUUID()) @Field("uuid")`. Non-nullable, non-optional.
 
 ```typescript
-@IdentifierField()
-id!: string;
+@IdentifierField() id!: string;
 ```
 
-Equivalent to `@Field("uuid", { default: () => randomUUID() })`. Non-nullable, non-optional.
-
-No arguments.
-
 #### `@CorrelationField`
 
-Shorthand for a UUID correlation tracking field. Auto-generates a UUID v4 on message creation. Used to trace related messages across publish/consume chains.
+Auto-generated UUID v4 used to trace related messages across publish/consume chains. Equivalent to `@Default(() => randomUUID()) @Field("uuid")`. Non-nullable, non-optional.
 
 ```typescript
-@CorrelationField()
-correlationId!: string;
+@CorrelationField() correlationId!: string;
 ```
 
-Equivalent to `@Field("uuid", { default: () => randomUUID() })`. Non-nullable, non-optional.
-
-No arguments.
-
 #### `@TimestampField`
 
-Shorthand for a timestamp field. Auto-generates the current `Date` on message creation.
+Auto-generated `Date` set on creation. Equivalent to `@Default(() => new Date()) @Field("date")`. Non-nullable, non-optional.
 
 ```typescript
-@TimestampField()
-createdAt!: Date;
+@TimestampField() createdAt!: Date;
 ```
 
-Equivalent to `@Field("date", { default: () => new Date() })`. Non-nullable, non-optional.
-
-No arguments.
-
 #### `@MandatoryField`
 
-Shorthand for a boolean flag that defaults to `false`. Commonly used for acknowledgement or processing flags.
+Boolean flag that defaults to `false`. Equivalent to `@Default(false) @Field("boolean")`.
 
 ```typescript
-@MandatoryField()
-requiresApproval!: boolean;
+@MandatoryField() requiresApproval!: boolean;
 ```
 
-Equivalent to `@Field("boolean", { default: false })`. Non-nullable, non-optional.
-
-No arguments.
-
 #### `@PersistentField`
 
-Shorthand for a boolean persistence flag that defaults to `false`. Commonly used to mark whether a message should be durably stored.
+Boolean persistence flag that defaults to `false`. Equivalent to `@Default(false) @Field("boolean")`.
 
 ```typescript
-@PersistentField()
-shouldPersist!: boolean;
+@PersistentField() shouldPersist!: boolean;
 ```
 
-Equivalent to `@Field("boolean", { default: false })`. Non-nullable, non-optional.
-
-No arguments.
-
----
-
 ### Field Modifiers
 
-These decorators modify the behavior of a field declared with `@Field` or one of the shorthand field decorators. Stack them on the same property. Modifier decorators must appear alongside a field decorator on the same property.
+Stack these on top of a field decorator to refine its behavior.
 
-#### `@Generated`
-
-Marks a field for automatic value generation on message creation.
+#### `@Nullable` / `@Optional`
 
 ```typescript
-@Generated("uuid")                   // UUID v4
-@Field("uuid")
-traceId!: string;
-
-@Generated("date")                   // current timestamp
-@Field("date")
-processedAt!: Date;
-
-@Generated("string")                 // random string (default length)
-@Field("string")
-token!: string;
-
-@Generated("string", { length: 12 }) // random string with custom length
-@Field("string")
-shortCode!: string;
+@Nullable() @Field("string") description!: string | null;
+@Optional() @Field("string") nickname?: string;
+```
 
-@Generated("integer", { min: 1, max: 1000 })
-@Field("integer")
-sequenceNumber!: number;
+#### `@Default`
 
-@Generated("float", { min: 0.0, max: 1.0 })
-@Field("float")
-weight!: number;
+```typescript
+@Default(0) @Field("integer") retryCount!: number;
+@Default(() => "generated") @Field("string") code!: string;
 ```
 
-**Arguments:** `(strategy: MetaGeneratedStrategy, options?: GeneratedDecoratorOptions)`.
+**Argument:** `MetaFieldDefault` (re-exported as `IrisFieldDefault`) — a primitive value, an array/record of primitives, or a no-arg function returning one.
 
-**Strategies:**
+#### `@Generated`
+
+Marks a field for automatic value generation when an instance is created.
 
-| Strategy    | Description                              |
-| ----------- | ---------------------------------------- |
-| `"uuid"`    | Generate UUID v4                         |
-| `"date"`    | Current timestamp                        |
-| `"string"`  | Random string with configurable `length` |
-| `"integer"` | Random integer in `[min, max]` range     |
-| `"float"`   | Random float in `[min, max]` range       |
+```typescript
+@Generated("uuid") @Field("uuid") traceId!: string;
+@Generated("date") @Field("date") processedAt!: Date;
+@Generated("string") @Field("string") token!: string;
+@Generated("string", { length: 12 }) @Field("string") shortCode!: string;
+@Generated("integer", { min: 1, max: 1000 }) @Field("integer") sequence!: number;
+@Generated("float", { min: 0, max: 1 }) @Field("float") weight!: number;
+```
 
-**Options:** `{ length?: number, min?: number, max?: number }` — all optional, all default to `null`.
+**Strategies:** `"uuid" | "date" | "string" | "integer" | "float"` (re-exported as `IrisGeneratedStrategy`). **Options:** `{ length?, min?, max? }`.
 
 #### `@Header`
 
-Promotes a field value to a message header. Headers are transported as key-value metadata alongside the payload, accessible without deserialising the full message body.
+Promotes a field to a transport header so it is accessible without deserialising the body.
 
 ```typescript
-@Header()              // header name = property name ("source")
-@Field("string")
-source!: string;
-
-@Header("x-trace-id") // explicit header name
-@Field("uuid")
-traceId!: string;
+@Header() @Field("string") source!: string;
+@Header("x-trace-id") @Field("uuid") traceId!: string;
 ```
 
-**Argument:** `string?` — custom header name. Defaults to the property name. Throws `IrisMetadataError` if the resolved name is empty or whitespace-only.
+**Argument:** `string?` — header name, defaults to the property name. Throws `IrisMetadataError` if it resolves to an empty string.
 
 #### `@Enum`
 
-Restricts a field to a fixed set of allowed values. Pass a TypeScript enum or a plain `Record<string, string | number>`. Enforced during Zod validation.
+Restricts the field to the values of a TypeScript enum or `Record<string, string | number>`. Enforced during validation.
 
 ```typescript
 enum OrderStatus {
@@ -824,56 +619,34 @@ enum OrderStatus {
   Delivered = "delivered",
 }
 
-@Enum(OrderStatus)
-@Field("enum")
-status!: OrderStatus;
+@Enum(OrderStatus) @Field("enum") status!: OrderStatus;
 ```
 
-**Argument:** `Record<string, string | number>` — the enum object or value map.
-
 #### `@Min` / `@Max`
 
-Set minimum/maximum bounds for numeric fields or minimum/maximum length for string fields. Enforced during Zod validation.
+Numeric bounds for number fields, length bounds for string fields.
 
 ```typescript
-@Min(0)
-@Max(100)
-@Field("integer")
-score!: number;
-
-@Min(1)
-@Max(255)
-@Field("string")
-name!: string;
+@Min(0) @Max(100) @Field("integer") score!: number;
+@Min(1) @Max(255) @Field("string") name!: string;
 ```
 
-**Argument:** `number`.
-
 #### `@Schema`
 
-Attaches a Zod schema for fine-grained field validation. The schema is evaluated during message validation.
+Attaches a Zod schema for fine-grained validation.
 
 ```typescript
 import { z } from "zod";
 
-@Schema(z.string().email())
-@Field("email")
-email!: string;
-
-@Schema(z.number().int().min(13).max(150))
-@Field("integer")
-age!: number;
-
-@Schema(z.string().regex(/^[A-Z]{2,3}$/))
-@Field("string")
-countryCode!: string;
+@Schema(z.string().email()) @Field("email") email!: string;
+@Schema(z.number().int().min(13).max(150)) @Field("integer") age!: number;
 ```
 
-**Argument:** `z.ZodType` — any Zod schema.
+**Argument:** `z.ZodType`.
 
 #### `@Transform`
 
-Applies a bidirectional transform to a field value. `to` runs during serialisation (message -> transport), `from` runs during deserialisation (transport -> message).
+Bidirectional transform between the in-memory field value and its serialised form. `to` runs on serialise, `from` runs on hydrate.
 
 ```typescript
 @Transform({
@@ -882,259 +655,90 @@ Applies a bidirectional transform to a field value. `to` runs during serialisati
 })
 @Field("string")
 tags!: string[];
-
-@Transform<Date, number>({
-  to: (date) => date.getTime(),
-  from: (ms) => new Date(ms),
-})
-@Field("bigint")
-timestamp!: Date;
 ```
 
-**Options:** `{ to: (value: TFrom) => TTo, from: (raw: TTo) => TFrom }`.
-
-This is a standalone decorator that uses a separate staging path. For inline transforms, use the `transform` option on `@Field` instead.
-
----
+**Options:** `{ to: (value) => unknown, from: (raw) => unknown }` (the type is re-exported as `IrisTransformFn`).
 
 ### Lifecycle Hook Decorators
 
-Lifecycle hooks are **class decorators** that register callbacks at specific points in the message lifecycle. All hooks receive `(message, context?)` as arguments, where `context` is the source's context value.
-
-Hooks may be async (`void | Promise<void>`) unless otherwise noted.
+Hooks are class decorators. Each hook receives `(message, meta)` where `meta: IrisHookMeta` carries `{ correlationId, actor, timestamp }`. Hooks may be sync or async.
 
-#### `@OnCreate`
-
-Fires when a message instance is created via `create()`. Useful for setting computed defaults or derived fields.
+| Decorator         | Fires                                                                              |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| `@OnCreate`       | When a message is constructed via `create()`                                       |
+| `@OnHydrate`      | After raw transport data is rehydrated, before delivery to a consume callback      |
+| `@OnValidate`     | During validation, after the built-in Zod check — throw to reject                  |
+| `@BeforePublish`  | Before the transport publishes                                                     |
+| `@AfterPublish`   | After the transport confirms publication                                           |
+| `@BeforeConsume`  | After deserialisation, before the consume callback                                 |
+| `@AfterConsume`   | After the consume callback completes successfully                                  |
+| `@OnConsumeError` | When the consume callback throws — receives `(error, message, meta)` (error first) |
 
 ```typescript
 @OnCreate((msg) => {
   msg.slug = msg.name.toLowerCase().replace(/\s+/g, "-");
 })
-@Message()
-class OrderPlaced {
-  @Field("string") name!: string;
-  @Field("string") slug!: string;
-}
-```
-
-**Argument:** `(message: M, context?: C) => void | Promise<void>`.
-
-#### `@OnHydrate`
-
-Fires when a message is rehydrated from raw transport data, after all fields are populated but before the message is returned to the consume callback.
-
-```typescript
-@OnHydrate((msg) => {
-  msg.displayName = `${msg.firstName} ${msg.lastName}`;
-})
-@Message()
-class UserEvent {
-  @Field("string") firstName!: string;
-  @Field("string") lastName!: string;
-  @Field("string") displayName!: string;
-}
-```
-
-**Argument:** `(message: M, context?: C) => void | Promise<void>`.
-
-#### `@OnValidate`
-
-Fires during message validation, after the built-in Zod schema check. Throw to reject the message.
-
-```typescript
 @OnValidate((msg) => {
-  if (msg.startDate >= msg.endDate) {
-    throw new Error("startDate must be before endDate");
-  }
+  if (msg.startDate >= msg.endDate) throw new Error("startDate must be before endDate");
 })
-@Message()
-class BookingRequest {
-  @Field("date") startDate!: Date;
-  @Field("date") endDate!: Date;
-}
-```
-
-**Argument:** `(message: M, context?: C) => void | Promise<void>`.
-
-#### `@BeforePublish` / `@AfterPublish`
-
-Fire around publish operations. `@BeforePublish` runs before the message is handed to the transport. `@AfterPublish` runs after the transport confirms delivery.
-
-```typescript
 @BeforePublish(async (msg) => {
   await validateExternalId(msg.externalId);
 })
 @AfterPublish(async (msg) => {
   metrics.increment("messages.published");
 })
-@Message()
-class OrderPlaced {
-  @Field("string") externalId!: string;
-}
-```
-
-**Argument:** `(message: M, context?: C) => void | Promise<void>`.
-
-#### `@BeforeConsume` / `@AfterConsume`
-
-Fire around consume callback execution. `@BeforeConsume` runs after deserialisation but before the consume callback. `@AfterConsume` runs after the callback completes successfully.
-
-```typescript
-@BeforeConsume(async (msg, ctx) => {
+@BeforeConsume(async (msg) => {
   audit.log("consuming", msg);
 })
 @AfterConsume(async (msg) => {
   metrics.increment("messages.consumed");
 })
-@Message()
-class OrderPlaced {
-  /* ... */
-}
-```
-
-**Argument:** `(message: M, context?: C) => void | Promise<void>`.
-
-#### `@OnConsumeError`
-
-Fires when a consume callback throws an error. Receives the error as the **first** argument, followed by the message and context.
-
-```typescript
 @OnConsumeError(async (error, msg) => {
   errorTracker.capture(error, { messageId: msg.id });
 })
 @Message()
-class PaymentCharge {
-  @IdentifierField() id!: string;
-  @Field("string") chargeId!: string;
-}
-```
-
-**Argument:** `(error: Error, message: M, context?: C) => void | Promise<void>`.
-
-Note the different signature: `error` is the first parameter, unlike all other hooks where the message comes first.
-
----
-
-### Hook Execution Order
-
-| Phase      | Hooks (in order)                                                                                        |
-| ---------- | ------------------------------------------------------------------------------------------------------- |
-| Creation   | `@OnCreate`                                                                                             |
-| Validation | `@OnValidate`                                                                                           |
-| Publish    | `@BeforePublish` -> subscriber.beforePublish -> transport -> `@AfterPublish` -> subscriber.afterPublish |
-| Consume    | `@BeforeConsume` -> subscriber.beforeConsume -> callback -> `@AfterConsume` -> subscriber.afterConsume  |
-| Hydration  | `@OnHydrate`                                                                                            |
-| Error      | `@OnConsumeError` -> subscriber.onConsumeError (replaces AfterConsume steps)                            |
-
-Full publish + consume lifecycle:
-
-```
-1. @BeforePublish hook
-2. subscriber.beforePublish
-3. (transport publishes)
-4. (transport delivers to consumer)
-5. @BeforeConsume hook
-6. subscriber.beforeConsume
-7. callback executes
-8. @AfterConsume hook
-9. subscriber.afterConsume
-10. @AfterPublish hook
-11. subscriber.afterPublish
-```
-
-On error at step 7, steps 8-11 are replaced by `@OnConsumeError` and `subscriber.onConsumeError`.
-
-## Retry and Dead Letter
-
-Configure automatic retry with backoff strategies and dead letter routing for permanently failed messages.
-
-```typescript
-@Retry({
-  maxRetries: 5,
-  strategy: "exponential", // "constant" | "linear" | "exponential"
-  delay: 1000, // initial delay in ms
-  delayMax: 30000, // maximum delay cap
-  multiplier: 2, // exponential multiplier
-  jitter: true, // add randomness to prevent thundering herd
-})
-@DeadLetter()
-@Message()
-class PaymentCharge {
-  @Field("string") chargeId!: string;
-  @Field("float") amount!: number;
-}
-```
-
-## Dynamic Topics
-
-Route messages to different topics based on their content:
-
-```typescript
-@Topic((msg: any) => `events.${msg.region}.${msg.type}`)
-@Message()
-class RegionalEvent {
-  @Field("string") region!: string;
-  @Field("string") type!: string;
-  @Field("object") data!: Record<string, unknown>;
+class BookingRequest {
+  /* ... */
 }
-
-const bus = source.messageBus(RegionalEvent);
-const msg = bus.create({ region: "eu-west", type: "signup", data: {} });
-await bus.publish(msg); // Published to "events.eu-west.signup"
 ```
 
-## Encryption and Compression
-
-```typescript
-import { Encrypted, Compressed } from "@lindorm/iris";
-
-@Encrypted() // Encrypt payload via amphora
-@Compressed("brotli") // Then compress ("gzip" | "deflate" | "brotli")
-@Message()
-class SensitivePayload {
-  @Field("string") ssn!: string;
-  @Field("string") name!: string;
-}
+## Hook Execution Order
 
-// Source must be configured with an amphora instance
-const source = new IrisSource({
-  driver: "rabbit",
-  url: "amqp://localhost",
-  logger: myLogger,
-  amphora: myAmphora,
-  messages: [SensitivePayload],
-});
-```
+| Phase      | Order                                                                                                       |
+| ---------- | ----------------------------------------------------------------------------------------------------------- |
+| Creation   | `@OnCreate`                                                                                                 |
+| Validation | `@OnValidate`                                                                                               |
+| Hydration  | `@OnHydrate`                                                                                                |
+| Publish    | `@BeforePublish` -> `subscriber.beforePublish` -> transport -> `@AfterPublish` -> `subscriber.afterPublish` |
+| Consume    | `@BeforeConsume` -> `subscriber.beforeConsume` -> callback -> `@AfterConsume` -> `subscriber.afterConsume`  |
+| Error      | `@OnConsumeError` -> `subscriber.onConsumeError` (replaces the after-consume steps)                         |
 
-## Message Subscribers
+## Subscribers
 
-Observe message lifecycle events across all messages in a source:
+Observe message lifecycle events across every message in a source.
 
 ```typescript
 import type { IMessageSubscriber } from "@lindorm/iris";
 
-const auditSubscriber: IMessageSubscriber = {
+const audit: IMessageSubscriber = {
   beforePublish: async (msg) => {
-    audit.log("publishing", msg);
+    auditLog.log("publishing", msg);
   },
   afterConsume: async (msg) => {
-    audit.log("consumed", msg);
+    auditLog.log("consumed", msg);
   },
-  onConsumeError: async (error, msg) => {
-    audit.log("consume-failed", { error: error.message, msg });
+  onConsumeError: async (err, msg) => {
+    auditLog.log("consume-failed", { error: err.message, msg });
   },
 };
 
-source.addSubscriber(auditSubscriber);
-
-// Remove later
-source.removeSubscriber(auditSubscriber);
+source.addSubscriber(audit);
+source.removeSubscriber(audit);
 ```
 
 ## Consume Envelope
 
-Every subscribe/consume callback receives the message and an envelope with routing metadata:
+Every subscribe/consume callback receives the message and a `ConsumeEnvelope`:
 
 ```typescript
 import type { ConsumeEnvelope } from "@lindorm/iris";
@@ -1142,128 +746,94 @@ import type { ConsumeEnvelope } from "@lindorm/iris";
 await bus.subscribe({
   topic: "OrderPlaced",
   callback: async (msg: OrderPlaced, envelope: ConsumeEnvelope) => {
-    console.log(envelope.topic); // "OrderPlaced"
-    console.log(envelope.messageName); // "OrderPlaced"
-    console.log(envelope.namespace); // "orders" | null
-    console.log(envelope.version); // 1
-    console.log(envelope.headers); // Record<string, string>
-    console.log(envelope.attempt); // 1 (increments on retry)
-    console.log(envelope.correlationId); // string | null
-    console.log(envelope.timestamp); // Unix timestamp
+    envelope.topic; // string
+    envelope.messageName; // string
+    envelope.namespace; // string | null
+    envelope.version; // number
+    envelope.headers; // Record<string, string>
+    envelope.attempt; // number (1 on first delivery, increments on retry)
+    envelope.correlationId; // string | null
+    envelope.timestamp; // number (unix ms)
   },
 });
 ```
 
 ## Message Manipulation
 
-Every publisher, message bus, and worker queue provides utilities for working with message instances:
+Every publisher, message bus, and worker queue exposes the same instance utilities:
 
 ```typescript
 const bus = source.messageBus(OrderPlaced);
 
-// Create: new instance with auto-generated fields and defaults
 const msg = bus.create({ orderId: "abc-123", total: 59.99 });
-
-// Hydrate: reconstruct from raw data (no auto-generation)
-const hydrated = bus.hydrate({ orderId: "abc-123", total: 59.99, id: "existing-uuid" });
-
-// Copy: deep clone with a fresh identifier
-const copied = bus.copy(msg);
-// copied.orderId === msg.orderId, but copied.id !== msg.id
-
-// Validate: throws IrisValidationError if invalid
-bus.validate(msg);
+const hydrated = bus.hydrate({ id: "...", orderId: "abc-123", total: 59.99, createdAt: ... });
+const copied = bus.copy(msg); // deep clone with a fresh identifier value
+bus.validate(msg);            // throws IrisValidationError when invalid
 ```
 
+`create()` runs default value generation and `@OnCreate` hooks. `hydrate()` reconstructs from raw transport data without regenerating defaults and runs `@OnHydrate` hooks.
+
 ## Publish Options
 
-Override message-level defaults per publish call:
+Per-publish overrides for `publish(message, options)`:
 
 ```typescript
 await bus.publish(msg, {
-  delay: 5000, // delay delivery by 5 seconds
-  priority: 8, // override @Priority
-  expiry: 60000, // override @Expiry (TTL in ms)
+  delay: 5000, // ms — overrides @Delay
+  priority: 8, // 0..10 — overrides @Priority
+  expiry: 60000, // ms — overrides @Expiry
   key: "partition-key", // routing/partition key
   headers: { "x-source": "api" }, // additional headers
 });
 ```
 
-## Zod Validation
+## Sessions
 
-Use `@Schema()` with Zod for fine-grained field validation:
-
-```typescript
-import { z } from "zod";
-import { Schema, Field, Message } from "@lindorm/iris";
-
-@Message()
-class UserCreated {
-  @Schema(z.string().email())
-  @Field("email")
-  email!: string;
-
-  @Schema(z.number().int().min(13).max(150))
-  @Field("integer")
-  age!: number;
-
-  @Schema(z.string().regex(/^[A-Z]{2,3}$/))
-  @Field("string")
-  countryCode!: string;
-}
-```
-
-## Cloning
-
-Create independent source instances that share the underlying driver connection:
+`source.session()` returns a lightweight `IIrisSession` that shares the underlying driver connection but carries its own logger, `IrisHookMeta`, and a snapshot of the source's subscribers at the time of cloning. This is the idiomatic way to scope correlation IDs and per-request loggers without tearing down the connection.
 
 ```typescript
 const source = new IrisSource({
   driver: "rabbit",
   url: "amqp://localhost",
-  logger: mainLogger,
+  logger: appLogger,
   messages: [OrderPlaced],
 });
 
 await source.connect();
 await source.setup();
 
-// Clone shares the connection but has its own logger and subscriber registry
-const scoped = source.clone({ logger: requestLogger, context: { requestId: "abc" } });
+const scoped = source.session({
+  logger: requestLogger,
+  meta: { correlationId: "abc-123", actor: "user:42", timestamp: new Date() },
+});
 
 const pub = scoped.publisher(OrderPlaced);
-await pub.publish(pub.create({ orderId: "abc-123", total: 59.99 }));
+await pub.publish(pub.create({ orderId: "abc", total: 10 }));
 ```
 
+A session exposes the same `messageBus`, `publisher`, `workerQueue`, `stream`, `rpcClient`, `rpcServer`, `hasMessage`, `ping`, and `driver` surface as the source.
+
 ## Driver Configuration
 
 ### Memory
 
 ```typescript
-const source = new IrisSource({
-  driver: "memory",
-  logger,
-  messages: [OrderPlaced],
-});
+new IrisSource({ driver: "memory", logger, messages: [OrderPlaced] });
 ```
 
 ### RabbitMQ
 
 ```typescript
-const source = new IrisSource({
+new IrisSource({
   driver: "rabbit",
   url: "amqp://localhost",
   logger,
   messages: [OrderPlaced],
-  exchange: "my-exchange", // optional
-  prefetch: 10, // optional
+  exchange: "my-exchange",
+  prefetch: 10,
   connection: {
-    // optional
     heartbeat: 60,
-    socketOptions: {
-      timeout: 30000,
-      keepAlive: true,
-    },
+    socketOptions: { timeout: 30000, keepAlive: true },
   },
 });
 ```
@@ -1271,30 +841,22 @@ const source = new IrisSource({
 ### Kafka
 
 ```typescript
-const source = new IrisSource({
+new IrisSource({
   driver: "kafka",
   brokers: ["localhost:9092"],
   logger,
   messages: [OrderPlaced],
-  prefix: "my-app", // optional topic prefix
-  prefetch: 100, // optional
-  acks: -1, // optional: -1 (all), 0 (none), 1 (leader)
-  sessionTimeoutMs: 30000, // optional
+  prefix: "my-app",
+  prefetch: 100,
+  acks: -1, // -1 = all, 0 = none, 1 = leader
+  sessionTimeoutMs: 30000,
   connection: {
-    // optional
     clientId: "my-service",
     ssl: true,
-    sasl: {
-      mechanism: "scram-sha-256",
-      username: "user",
-      password: "pass",
-    },
+    sasl: { mechanism: "scram-sha-256", username: "user", password: "pass" },
     connectionTimeout: 10000,
     requestTimeout: 30000,
-    retry: {
-      retries: 5,
-      initialRetryTime: 300,
-    },
+    retry: { retries: 5, initialRetryTime: 300 },
   },
 });
 ```
@@ -1302,15 +864,14 @@ const source = new IrisSource({
 ### NATS
 
 ```typescript
-const source = new IrisSource({
+new IrisSource({
   driver: "nats",
   servers: "nats://localhost:4222", // string or Array<string>
   logger,
   messages: [OrderPlaced],
-  prefix: "my-app", // optional
-  prefetch: 50, // optional
+  prefix: "my-app",
+  prefetch: 50,
   connection: {
-    // optional
     user: "nats-user",
     pass: "nats-pass",
     tls: true,
@@ -1326,17 +887,16 @@ const source = new IrisSource({
 ### Redis Streams
 
 ```typescript
-const source = new IrisSource({
+new IrisSource({
   driver: "redis",
   url: "redis://localhost:6379",
   logger,
   messages: [OrderPlaced],
-  prefix: "my-app", // optional
-  prefetch: 50, // optional
-  blockMs: 5000, // optional: XREAD block time
-  maxStreamLength: 10000, // optional: MAXLEN cap per stream
+  prefix: "my-app",
+  prefetch: 50,
+  blockMs: 5000, // XREAD block time
+  maxStreamLength: 10000, // MAXLEN cap per stream
   connection: {
-    // optional
     host: "redis.internal",
     port: 6379,
     password: "secret",
@@ -1352,87 +912,83 @@ const source = new IrisSource({
 
 ## Persistence (Delay and Dead Letter Stores)
 
-Configure where delayed messages and dead letter entries are stored:
+Configure where delayed deliveries and dead-lettered envelopes are kept. These are used by drivers that don't already provide native primitives for them.
 
 ```typescript
-const source = new IrisSource({
-  driver: "rabbit",
-  url: "amqp://localhost",
+new IrisSource({
+  driver: "kafka",
+  brokers: ["localhost:9092"],
   logger,
   messages: [OrderPlaced],
   persistence: {
-    // Delay store: holds messages until their scheduled delivery time
-    delay: { type: "memory" },
-    // or: { type: "redis", url: "redis://localhost:6379" },
-    // or: { type: "custom", store: myDelayStore },
+    delay: { type: "memory", pollIntervalMs: 250 },
+    // delay: { type: "redis", url: "redis://localhost:6379", pollIntervalMs: 250 },
+    // delay: { type: "custom", store: myDelayStore },
 
-    // Dead letter store: holds messages that exhausted all retries
     deadLetter: { type: "memory" },
-    // or: { type: "redis", url: "redis://localhost:6379" },
-    // or: { type: "custom", store: myDeadLetterStore },
+    // deadLetter: { type: "redis", url: "redis://localhost:6379" },
+    // deadLetter: { type: "custom", store: myDeadLetterStore },
   },
 });
 ```
 
 ### Custom Stores
 
-Implement `IDelayStore` and/or `IDeadLetterStore` for custom persistence:
+Implement `IDelayStore` and/or `IDeadLetterStore` for bespoke persistence:
 
 ```typescript
 import type {
-  IDelayStore,
-  IDeadLetterStore,
-  DelayedEntry,
   DeadLetterEntry,
+  DeadLetterFilterOptions,
+  DeadLetterListOptions,
+  DelayedEntry,
+  IDeadLetterStore,
+  IDelayStore,
 } from "@lindorm/iris";
 
 class MyDelayStore implements IDelayStore {
-  async schedule(entry: DelayedEntry): Promise<void> {
+  schedule = async (entry: DelayedEntry): Promise<void> => {
     /* ... */
-  }
-  async poll(now: number): Promise<Array<DelayedEntry>> {
+  };
+  poll = async (now: number): Promise<Array<DelayedEntry>> => {
     /* ... */
-  }
-  async cancel(id: string): Promise<boolean> {
+  };
+  cancel = async (id: string): Promise<boolean> => {
     /* ... */
-  }
-  async size(): Promise<number> {
+  };
+  size = async (): Promise<number> => {
     /* ... */
-  }
-  async clear(): Promise<void> {
+  };
+  clear = async (): Promise<void> => {
     /* ... */
-  }
-  async close(): Promise<void> {
+  };
+  close = async (): Promise<void> => {
     /* ... */
-  }
+  };
 }
 
 class MyDeadLetterStore implements IDeadLetterStore {
-  async add(entry: DeadLetterEntry): Promise<void> {
+  add = async (entry: DeadLetterEntry): Promise<void> => {
     /* ... */
-  }
-  async list(options?: {
-    topic?: string;
-    limit?: number;
-    offset?: number;
-  }): Promise<Array<DeadLetterEntry>> {
+  };
+  list = async (options?: DeadLetterListOptions): Promise<Array<DeadLetterEntry>> => {
     /* ... */
-  }
-  async get(id: string): Promise<DeadLetterEntry | null> {
+  };
+  get = async (id: string): Promise<DeadLetterEntry | null> => {
     /* ... */
-  }
-  async remove(id: string): Promise<boolean> {
+  };
+  remove = async (id: string): Promise<boolean> => {
     /* ... */
-  }
-  async purge(options?: { topic?: string }): Promise<number> {
+  };
+  purge = async (options?: DeadLetterFilterOptions): Promise<number> => {
     /* ... */
-  }
-  async count(options?: { topic?: string }): Promise<number> {
+  };
+  count = async (options?: DeadLetterFilterOptions): Promise<number> => {
     /* ... */
-  }
-  async close(): Promise<void> {
+  };
+  close = async (): Promise<void> => {
     /* ... */
-  }
+  };
 }
 ```
 
@@ -1442,129 +998,106 @@ class MyDeadLetterStore implements IDeadLetterStore {
 const state = source.getConnectionState();
 // "disconnected" | "connecting" | "connected" | "reconnecting" | "draining"
 
-source.onConnectionStateChange((state) => {
-  console.log(`Connection state: ${state}`);
+source.on("connection:state", (next) => {
+  console.log(`connection state -> ${next}`);
 });
 
-// Health check
+source.once("connection:state", (next) => {
+  /* ... */
+});
+source.off("connection:state", listener);
+
 const healthy = await source.ping();
 ```
 
 ## Testing with Mocks
 
-All mocks are available via the `@lindorm/iris/mocks` subpath:
+Iris ships per-runtime mock factories. Pick the import path that matches your test runner:
 
 ```typescript
+// Jest
 import {
   createMockIrisSource,
-  createMockPublisher,
+  createMockIrisSession,
   createMockMessageBus,
+  createMockPublisher,
+  createMockRpcClient,
   createMockWorkerQueue,
+} from "@lindorm/iris/mocks/jest";
+
+// Vitest
+import {
+  createMockIrisSource,
+  createMockIrisSession,
+  createMockMessageBus,
+  createMockPublisher,
   createMockRpcClient,
-} from "@lindorm/iris/mocks";
+  createMockWorkerQueue,
+} from "@lindorm/iris/mocks/vitest";
 ```
 
-### Mock Source
-
 ```typescript
 const source = createMockIrisSource();
 
-// All methods are jest.fn() mocks
-expect(source.connect).not.toHaveBeenCalled();
-
 await source.connect();
 expect(source.connect).toHaveBeenCalledTimes(1);
 
-// Factory methods return mocks by default
 const bus = source.messageBus(OrderPlaced);
 const pub = source.publisher(OrderPlaced);
 const queue = source.workerQueue(OrderPlaced);
 const rpc = source.rpcClient(GetPrice, PriceResponse);
 ```
 
-### Mock Publisher
+The bus, publisher, and worker-queue mocks expose a `published` array and a `clearPublished()` helper. The RPC client mock takes an optional response factory and exposes `requests` plus `clearRequests()`.
 
 ```typescript
 const pub = createMockPublisher<OrderPlaced>();
-
-const msg = pub.create({ orderId: "abc", total: 10 });
-await pub.publish(msg);
-
-// Inspect published messages
+await pub.publish(pub.create({ orderId: "abc", total: 10 }));
 expect(pub.published).toHaveLength(1);
-
-// Reset
 pub.clearPublished();
-expect(pub.published).toHaveLength(0);
-```
-
-### Mock Message Bus
-
-```typescript
-const bus = createMockMessageBus<OrderPlaced>();
-
-await bus.publish(bus.create({ orderId: "abc", total: 10 }));
-
-expect(bus.published).toHaveLength(1);
-expect(bus.subscribe).not.toHaveBeenCalled();
-
-bus.clearPublished();
-```
-
-### Mock Worker Queue
-
-```typescript
-const queue = createMockWorkerQueue<OrderPlaced>();
-
-await queue.publish(queue.create({ orderId: "abc", total: 10 }));
-
-expect(queue.published).toHaveLength(1);
-expect(queue.consume).not.toHaveBeenCalled();
-
-queue.clearPublished();
-```
-
-### Mock RPC Client
 
-```typescript
-// Provide a response factory
 const client = createMockRpcClient<GetPrice, PriceResponse>((req) => {
   const res = new PriceResponse();
   res.price = 42.0;
   res.currency = "USD";
   return res;
 });
+const res = await client.request(new GetPrice());
+expect(client.requests).toHaveLength(1);
+client.clearRequests();
+```
 
-const req = new GetPrice();
-req.sku = "WIDGET-42";
+## CLI
 
-const res = await client.request(req);
-expect(res.price).toBe(42.0);
-expect(client.requests).toHaveLength(1);
+The package ships an `iris` binary for scaffolding:
 
-client.clearRequests();
+```bash
+npx iris init --driver rabbit --directory ./src/iris
+npx iris generate message OrderPlaced --directory ./src/iris/messages
 ```
 
+`iris init` (alias `i`) writes a `source.ts` plus an empty `messages/` directory. `iris generate message` (alias `g m`) writes a single PascalCase-named message file. Both commands accept `--dry-run`.
+
 ## Error Classes
 
-All errors extend `IrisError`, which extends `LindormError`:
-
-| Error Class              | When                                      |
-| ------------------------ | ----------------------------------------- |
-| `IrisError`              | Base class for all iris errors            |
-| `IrisDriverError`        | Driver connection or operation failure    |
-| `IrisMetadataError`      | Invalid decorator configuration           |
-| `IrisNotSupportedError`  | Unsupported feature for the active driver |
-| `IrisPublishError`       | Message publishing failure                |
-| `IrisScannerError`       | Message class scanning failure            |
-| `IrisSerializationError` | Serialisation or deserialisation failure  |
-| `IrisSourceError`        | Source setup or configuration error       |
-| `IrisTimeoutError`       | Operation exceeded timeout                |
-| `IrisTransportError`     | Transport layer failure                   |
-| `IrisValidationError`    | Message validation failure                |
+Every error extends `IrisError`, which extends `LindormError` from `@lindorm/errors`.
+
+| Error                    | Raised when                                      |
+| ------------------------ | ------------------------------------------------ |
+| `IrisError`              | Base class — extend for custom errors            |
+| `IrisDriverError`        | Driver connection or operation failed            |
+| `IrisMetadataError`      | A decorator was used with an invalid value       |
+| `IrisNotSupportedError`  | The active driver does not support the operation |
+| `IrisPublishError`       | Publishing a message failed                      |
+| `IrisScannerError`       | Auto-scanning message classes from disk failed   |
+| `IrisSerializationError` | (De)serialisation of an envelope failed          |
+| `IrisSourceError`        | Source configuration or lifecycle error          |
+| `IrisTimeoutError`       | An operation exceeded its timeout                |
+| `IrisTransportError`     | Transport-layer failure                          |
+| `IrisValidationError`    | A message failed validation                      |
 
 ```typescript
-import { IrisTimeoutError, IrisValidationError } from "@lindorm/iris";
+import { IrisTimeoutError } from "@lindorm/iris";
 
 try {
   await client.request(req, { timeout: 1000 });
@@ -1575,110 +1108,6 @@ try {
 }
 ```
 
-## Full Example
-
-```typescript
-import {
-  IrisSource,
-  Message,
-  Namespace,
-  Version,
-  Field,
-  IdentifierField,
-  TimestampField,
-  Retry,
-  DeadLetter,
-} from "@lindorm/iris";
-import type { IMessage, IMessageSubscriber } from "@lindorm/iris";
-
-// --- Define messages ---
-
-@Message()
-@Namespace("payments")
-@Version(1)
-@Retry({ maxRetries: 3, strategy: "exponential", delay: 1000 })
-@DeadLetter()
-class ChargeRequested {
-  @IdentifierField() id!: string;
-  @TimestampField() createdAt!: Date;
-  @Field("string") paymentId!: string;
-  @Field("float") amount!: number;
-  @Field("string") currency!: string;
-}
-
-@Message()
-@Namespace("payments")
-@Version(1)
-class ChargeCompleted {
-  @IdentifierField() id!: string;
-  @TimestampField() completedAt!: Date;
-  @Field("string") paymentId!: string;
-  @Field("boolean") success!: boolean;
-}
-
-// --- Set up source ---
-
-const source = new IrisSource({
-  driver: "kafka",
-  brokers: ["kafka-1:9092", "kafka-2:9092"],
-  logger: appLogger,
-  messages: [ChargeRequested, ChargeCompleted],
-  persistence: {
-    deadLetter: { type: "redis", url: "redis://localhost:6379" },
-  },
-});
-
-await source.connect();
-await source.setup();
-
-// --- Observe lifecycle ---
-
-const metricsSubscriber: IMessageSubscriber = {
-  afterPublish: async (msg) => metrics.increment("messages.published"),
-  afterConsume: async (msg) => metrics.increment("messages.consumed"),
-  onConsumeError: async (err) => metrics.increment("messages.errors"),
-};
-
-source.addSubscriber(metricsSubscriber);
-
-// --- Worker: process charges ---
-
-const queue = source.workerQueue(ChargeRequested);
-const completedPub = source.publisher(ChargeCompleted);
-
-await queue.consume("payment-workers", async (msg, envelope) => {
-  const result = await paymentGateway.charge(msg.paymentId, msg.amount, msg.currency);
-
-  const completed = completedPub.create({
-    paymentId: msg.paymentId,
-    success: result.ok,
-  });
-
-  await completedPub.publish(completed);
-});
-
-// --- Notify on completion ---
-
-const completedBus = source.messageBus(ChargeCompleted);
-
-await completedBus.subscribe({
-  topic: "ChargeCompleted",
-  queue: "notification-service",
-  callback: async (msg) => {
-    if (msg.success) {
-      await emailService.sendReceipt(msg.paymentId);
-    }
-  },
-});
-
-// --- Shutdown ---
-
-process.on("SIGTERM", async () => {
-  await source.drain();
-  await source.disconnect();
-});
-```
-
 ## License
 
 AGPL-3.0-or-later