arvo-event-handler 3.0.2 → 3.0.4

package/README.md

@@ -1,101 +1,102 @@
+# Arvo Event Handler
+
+The `arvo-event-handler` package serves as the comprehensive orchestration and event processing foundation for building sophisticated, reliable event-driven systems within the Arvo architecture. This package provides a complete toolkit of components that work seamlessly together to handle everything from simple event processing to complex distributed workflow orchestration, all while maintaining strict type safety, comprehensive observability, and robust error handling.
+
 [![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-white.svg)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 
-# Arvo
+## Installation
 
-## What is Arvo
+Install the package along with its core dependency:
 
-Arvo is an opinionated approach to building event-driven systems. It's designed as a pattern and methodology rather than a rigid framework.
+```bash
+npm install arvo-event-handler arvo-core
+```
 
-## Principal
+```bash
+yarn add arvo-event-handler arvo-core
+```
 
-The core principle of Arvo is to provide a solid foundation with enough flexibility for customization, allowing you to impose your own technical posture, including security measures, event brokerage, and telemetry. While Arvo offers a structured approach, it encourages developers to implement their own solutions if they believe they can improve upon or diverge from Arvo's principles.
+## The Event Handlers
 
-If you're looking to focus on results without getting bogged down in the nitty-gritty of event creation, handling, system state management, and telemetry, while also avoiding vendor lock-in, Arvo provides an excellent starting point. I believe, it strikes a balance between opinionated design and customization, making it an ideal choice for developers who want a head start in building event-driven systems without sacrificing flexibility.
+The Arvo event handling architecture is based on three handler patterns.
 
-Key features of Arvo include:
+### 1. Simple Event Handler
 
-- Lightweight and unopinionated core
-- Extensible architecture
-- Cloud-agnostic design
-- Built-in primitives for event-driven patterns
-- Easy integration with existing systems and tools
+This kind of event handling is provided by [`ArvoEventHandler`](src/ArvoEventHandler/README.md). This approach transforms ArvoContract definitions into stateless, pure function handlers that process individual events in isolation. Each handler binds to a specific contract, validates incoming events against schema definitions, executes business logic, and returns response events. It supports multiple contract versions for backward compatibility and enables multi-domain event broadcasting for parallel processing pipelines. This pattern is ideal for microservices, API endpoints, and any scenario where you need reliable, contract-enforced event processing without complex state management or workflow coordination.
 
-Whether you're building a small microservice or a large-scale distributed system, my hope with Arvo is to offers you some of the tools and patterns to help you succeed in the world of event-driven architecture.
+### 2. State-machine based workflow orchestration
 
-## Arvo suite
+This kind of event handling is provided by [`ArvoMachine`](src/ArvoMachine/README.md) which defines the state machine and [`ArvoOrchestrator`](src/ArvoOrchestrator/README.md) which executes it. This approach uses declarative state machine definitions to model complex business processes with multiple states, transitions, and conditional logic. ArvoMachine creates XState-compatible machines with Arvo-specific constraints and contract bindings, while ArvoOrchestrator provides the runtime environment for executing these machines with distributed state persistence, resource locking, and comprehensive lifecycle management. This pattern excels at complex workflows with parallel states, timing requirements, conditional branching, and scenarios where visual workflow modeling and deterministic state transitions are crucial for business process management.
 
-Arvo is a collection of libraries which allows you to build the event driven system in the Arvo pattern. However, if you feel you don't have to use them or you can use them as you see fit.
+### 3. Dynamic stateful event handling and orchestration
 
-| Scope          | NPM                                                               | Github                                             | Documentation                                                |
-| -------------- | ----------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------ |
-| Orchestration  | https://www.npmjs.com/package/arvo-xstate?activeTab=readme        | https://github.com/SaadAhmad123/arvo-xstate        | https://saadahmad123.github.io/arvo-xstate/index.html        |
-| Core           | https://www.npmjs.com/package/arvo-core?activeTab=readme          | https://github.com/SaadAhmad123/arvo-core          | https://saadahmad123.github.io/arvo-core/index.html          |
-| Event Handling | https://www.npmjs.com/package/arvo-event-handler?activeTab=readme | https://github.com/SaadAhmad123/arvo-event-handler | https://saadahmad123.github.io/arvo-event-handler/index.html |
+This kind of event handling is provided by [`ArvoResumable`](src/ArvoResumable/README.md). The event handling is a different approach to workflow processing and complements the state machine pattern by offering an imperative programming model where developers write handler functions that explicitly manage workflow state through context objects. Instead of defining states and transitions declaratively, you write code that examines incoming events, updates workflow context, and decides what actions to take next. This approach provides direct control over workflow logic, making it easier to debug and understand for teams familiar with traditional programming patterns, while still offering the same reliability, observability, and distributed coordination features as state machine orchestration.
 
-# Arvo - Event Handler
+## Core Infrastructure Components
 
-This package contains the event handler primitive required to enable an Arvo Event Driven System. These are light weight classes and types which take care of event listening, contract bound type inference, distributed open telemetry and much more.
+Beyond the three main handler patterns, the package includes essential infrastructure components that enable robust distributed system operation.
 
-## Documentation & Resources
+### Memory - State Persistance
 
-| Source       | Link                                                              |
-| ------------ | ----------------------------------------------------------------- |
-| Package      | https://www.npmjs.com/package/arvo-event-handler?activeTab=readme |
-| Github       | https://github.com/SaadAhmad123/arvo-event-handler                |
-| Documenation | https://saadahmad123.github.io/arvo-event-handler/index.html      |
+The [`IMachineMemory`](src/MachineMemory/README.md) interface defines how workflow state gets persisted and coordinated across distributed instances. It implements an optimistic locking strategy with "fail fast on acquire, be tolerant on release" semantics, ensuring data consistency while enabling system recovery from transient failures. 
 
-## Installation
+This package includes `SimpleMachineMemory` for development/ prototyping scenarios and provides example for implementing cloud-based production-ready distributed storage solutions.
 
-You can install the core package via `npm` or `yarn`
+### Error Handling 
 
-```bash
-npm install arvo-event-handler arvo-core
-```
+The Arvo event handling system uses a layered error handling approach that provides clear boundaries between different types of failures, enabling appropriate responses at each level.
 
-```bash
-yarn add arvo-event-handler arvo-core
-```
+**Business Logic Failures** are expected outcomes in your business processes and should be modeled as explicit events in your `ArvoContract` definitions. For example, when a user already exists during registration or a payment is declined, these represent normal business scenarios rather than system errors. By defining these as emittable events, downstream consumers can distinguish between business logic outcomes and actual system problems, enabling appropriate handling logic for each scenario.
 
-## Components
+**Transient System Errors** occur when underlying infrastructure or external services fail temporarily. Database connection timeouts, API unavailability, or network issues fall into this category. The system automatically converts uncaught exceptions into standardized system error events with the type pattern `sys.{contract.type}.error`. These events carry error details and can trigger retry mechanisms, circuit breakers, or alternative processing paths while maintaining the event-driven flow of your system.
 
-There 2 main types of event handlers in Arvo event driven system
+**Violations** represent critical failures that require immediate attention and cannot be handled through normal event processing patterns. The system defines four distinct violation types to help you identify and respond to different categories of critical issues:
 
-- [ArvoEventHandler](src/ArvoEventHandler/README.md) is designed to facilitate the handling of events as per an `ArvoContract` (see [arvo-core](https://saadahmad123.github.io/arvo-core/documents/ArvoContract.html)). It provides a robust and flexible way to create, manage, and execute event handlers for Arvo-based event driven systems.
-- [ArvoEventRouter](src/ArvoEventRouter/README.md) is designed to route ArvoEvents to appropriate ArvoEventHandlers. It provides a centralized mechanism for managing and executing multiple event handlers based on event types.
-- [MultiArvoEventHandler](src/MultiArvoEventHandler/README.md) is a flexible and powerful event handling class designed to process multiple event types across different ArvoContracts. This handler offers greater versatility compared to the more specialized `ArvoEventHandler`, as it's not bound to a specific contract or event type.
+- `ContractViolation` occurs when event data fails contract validation, indicating schema mismatches between services. This typically signals version incompatibilities or data corruption that requires developer intervention to resolve.
 
-## Getting Started
+- `ConfigViolation` happens when events are routed to handlers that cannot process them, revealing system topology or configuration problems that need infrastructure-level fixes.
 
-To start using Arvo Event Handlers in your project:
+- `ExecutionViolation` provides a mechanism for custom error handling when your business logic encounters scenarios that cannot be resolved through normal event patterns and require special intervention.
 
-- Install the package as shown in the Installation section.
-- Import the necessary components:
+- `TransactionViolation` is raised specifically by `ArvoOrchestrator` and `ArvoResumable` when state persistence operations fail. The accompanying `TransactionViolationCause` provides detailed information about what went wrong, allowing you to implement appropriate recovery strategies for distributed transaction failures.
 
-```javascript
-import {
-  createArvoEvent,
-  createArvoContract,
-  createArvoContractLibrary,
-  createArvoEventFactory,
-} from 'arvo-core';
 
-import {
-  createArvoEventHandler,
-  createMultiArvoEventHandler,
-  createArvoEventRouter,
-} from 'arvo-event-handler';
-```
+### Local Developement & Testing
 
-- Begin defining your events, contracts, and handlers using the provided classes.
+The package provides `createSimpleEventBroker` utility which creates local event buses perfect for testing, development, and single-function workflow coordination. It enables comprehensive integration testing without external message brokers while supporting the same event patterns used in production distributed systems.
 
-## License
 
-This package is available under the MIT License. For more details, refer to the [LICENSE.md](LICENSE.md) file in the project repository.
+## Architecture Principles
+
+The entire system follows consistent architectural principles that promote reliability and maintainability. All handlers implement the signature `ArvoEvent => Promise<{ events: ArvoEvent[] }>`, creating predictable event flow patterns throughout the system. Contract-first development ensures all service interactions are explicitly defined and validated, eliminating common integration issues while providing compile-time type safety.
+
+Multi-domain event broadcasting allows single handlers to create events for different processing contexts simultaneously, supporting patterns like audit trails, analytics processing, and external system integration. The comprehensive observability integration provides operational visibility through OpenTelemetry spans, structured logging, and performance metrics collection.
+
+The functional architecture enables natural horizontal scaling since handlers operate as pure functions with consistent behavior regardless of deployment location. State management through pluggable persistence interfaces supports various scaling strategies from single-instance deployments to sophisticated distributed configurations.
 
-## Change Logs
+## Documentation and Resources
 
-For a detailed list of changes and updates, please refer to the [document](CHANGELOG.md) file.
+| Component | Documentation | When to Use |
+|-----------|---------------|-------------|
+| **ArvoEventHandler** | [Simple Event Processing](src/ArvoEventHandler/README.md) | Stateless services, API endpoints, microservices, simple request-response processing |
+| **ArvoMachine** | [State Machine Workflows](src/ArvoMachine/README.md) | Complex business processes with multiple states, conditional branching, parallel execution, visual workflow modeling |
+| **ArvoOrchestrator** | [Workflow Orchestration](src/ArvoOrchestrator/README.md) | Running state machines in production, distributed workflow coordination, comprehensive lifecycle management |
+| **ArvoResumable** | [Handler-Based Workflows](src/ArvoResumable/README.md) | Dynamic workflows, imperative programming preference, rapid prototyping, teams familiar with traditional programming patterns |
+| **MachineMemory** | [State Persistence Interface](src/MachineMemory/README.md) | Custom state storage requirements, distributed locking strategies, production persistence implementations |
+
+## Package Information
+
+| Resource | Link |
+|----------|------|
+| Package | [npm package](https://www.npmjs.com/package/arvo-event-handler) |
+| Repository | [GitHub repository](https://github.com/SaadAhmad123/arvo-event-handler) |
+| Documentation | [Complete documentation](https://saadahmad123.github.io/arvo-event-handler/index.html) |
+| Core Package | [arvo-core documentation](https://saadahmad123.github.io/arvo-core/index.html) |
+
+## License
+
+This package is available under the MIT License. For more details, refer to the [LICENSE.md](LICENSE.md) file in the project repository.
 
 ### SonarCloud Metrics
 
@@ -106,8 +107,7 @@ For a detailed list of changes and updates, please refer to the [document](CHANG
 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
-[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
-[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)

package/dist/ArvoDomain.d.ts

@@ -0,0 +1,57 @@
+import type { ArvoEvent, VersionedArvoContract } from 'arvo-core';
+/**
+ * Symbolic constants for domain resolution in Arvo event emission.
+ *
+ * These can be passed into the `domain` array of an emitted ArvoEvent to indicate
+ * that the final domain should be dynamically resolved from a specific context.
+ */
+export declare const ArvoDomain: {
+    /**
+     * Resolve the domain from the emitting handler’s own contract (`handlerSelfContract.domain`).
+     *
+     * Use this when the handler’s contract defines a stable domain that should apply
+     * to all emitted events, regardless of the triggering context.
+     */
+    readonly FROM_SELF_CONTRACT: "domain.contract.self.inherit";
+    /**
+     * Resolve the domain from the contract that defines the event being emitted (`eventContract.domain`).
+     *
+     * In `ArvoResumable` and `ArvoMachine`, this is typically used when emitting service events
+     * (not the completion event). In `ArvoEventHandler`, where only the self contract exists,
+     * this resolves to the same value as `FROM_SELF_CONTRACT`.
+     *
+     * For orchestration `complete` events, this behaves identically to `FROM_SELF_CONTRACT`
+     * since the emitting contract is also the self contract.
+     */
+    readonly FROM_EVENT_CONTRACT: "domain.contract.inherit";
+    /**
+     * Resolve the domain from the triggering event’s `domain` field (`triggeringEvent.domain`).
+     *
+     * Use this when you want to preserve the domain context of the incoming event
+     * and carry it forward through event emissions.
+     */
+    readonly FROM_TRIGGERING_EVENT: "domain.event.inherit";
+};
+/**
+ * Resolves a symbolic or static domain value into a concrete domain string or `null`.
+ *
+ * Used internally in the Arvo execution model to interpret symbolic domain constants
+ * at the moment an event is emitted. Supports resolution from:
+ * - the emitting handler's own contract
+ * - the emitted event’s associated contract
+ * - the triggering event’s `domain` field
+ *
+ * @param param - Parameters for resolving the domain.
+ * @param param.domainToResolve - Either a static domain string, symbolic value, or null.
+ * @param param.handlerSelfContract - The contract of the handler currently emitting the event.
+ * @param param.eventContract - The contract of the event being emitted (optional).
+ * @param param.triggeringEvent - The triggering event that caused this emission.
+ *
+ * @returns A resolved domain string, or `null` if no valid domain is found.
+ */
+export declare const resolveEventDomain: (param: {
+    domainToResolve: string | null;
+    handlerSelfContract: VersionedArvoContract<any, any>;
+    eventContract: VersionedArvoContract<any, any> | null;
+    triggeringEvent: ArvoEvent;
+}) => string | null;

package/dist/ArvoDomain.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEventDomain = exports.ArvoDomain = void 0;
+/**
+ * Symbolic constants for domain resolution in Arvo event emission.
+ *
+ * These can be passed into the `domain` array of an emitted ArvoEvent to indicate
+ * that the final domain should be dynamically resolved from a specific context.
+ */
+exports.ArvoDomain = {
+    /**
+     * Resolve the domain from the emitting handler’s own contract (`handlerSelfContract.domain`).
+     *
+     * Use this when the handler’s contract defines a stable domain that should apply
+     * to all emitted events, regardless of the triggering context.
+     */
+    FROM_SELF_CONTRACT: 'domain.contract.self.inherit',
+    /**
+     * Resolve the domain from the contract that defines the event being emitted (`eventContract.domain`).
+     *
+     * In `ArvoResumable` and `ArvoMachine`, this is typically used when emitting service events
+     * (not the completion event). In `ArvoEventHandler`, where only the self contract exists,
+     * this resolves to the same value as `FROM_SELF_CONTRACT`.
+     *
+     * For orchestration `complete` events, this behaves identically to `FROM_SELF_CONTRACT`
+     * since the emitting contract is also the self contract.
+     */
+    FROM_EVENT_CONTRACT: 'domain.contract.inherit',
+    /**
+     * Resolve the domain from the triggering event’s `domain` field (`triggeringEvent.domain`).
+     *
+     * Use this when you want to preserve the domain context of the incoming event
+     * and carry it forward through event emissions.
+     */
+    FROM_TRIGGERING_EVENT: 'domain.event.inherit',
+};
+/**
+ * Resolves a symbolic or static domain value into a concrete domain string or `null`.
+ *
+ * Used internally in the Arvo execution model to interpret symbolic domain constants
+ * at the moment an event is emitted. Supports resolution from:
+ * - the emitting handler's own contract
+ * - the emitted event’s associated contract
+ * - the triggering event’s `domain` field
+ *
+ * @param param - Parameters for resolving the domain.
+ * @param param.domainToResolve - Either a static domain string, symbolic value, or null.
+ * @param param.handlerSelfContract - The contract of the handler currently emitting the event.
+ * @param param.eventContract - The contract of the event being emitted (optional).
+ * @param param.triggeringEvent - The triggering event that caused this emission.
+ *
+ * @returns A resolved domain string, or `null` if no valid domain is found.
+ */
+var resolveEventDomain = function (param) {
+    var _a, _b;
+    var ArvoDomainValues = Object.values(exports.ArvoDomain);
+    if (param.domainToResolve && ArvoDomainValues.includes(param.domainToResolve)) {
+        var domainToResolve = param.domainToResolve;
+        if (domainToResolve === exports.ArvoDomain.FROM_EVENT_CONTRACT) {
+            return (_b = (_a = param.eventContract) === null || _a === void 0 ? void 0 : _a.domain) !== null && _b !== void 0 ? _b : null;
+        }
+        if (domainToResolve === exports.ArvoDomain.FROM_SELF_CONTRACT) {
+            return param.handlerSelfContract.domain;
+        }
+        if (domainToResolve === exports.ArvoDomain.FROM_TRIGGERING_EVENT) {
+            return param.triggeringEvent.domain;
+        }
+    }
+    return param.domainToResolve;
+};
+exports.resolveEventDomain = resolveEventDomain;

package/dist/ArvoEventHandler/helpers.d.ts

@@ -2,55 +2,44 @@ import type { ArvoContract } from 'arvo-core';
 import ArvoEventHandler from '.';
 import type { IArvoEventHandler } from './types';
 /**
- * Create the instance of `ArvoEventHandler`
+ * Creates an instance of `ArvoEventHandler` for the specified versioned contract and handlers.
  *
- * > **Caution:** Don't use domained contracts unless it is fully intentional. Using domained
- * contracts causes implicit domain assignment which can be hard to track and confusing. For 99%
- * of the cases you dont need domained contracts
+ * This function is the recommended entry point for defining stateless, contract-driven services in Arvo.
+ * It binds a contract to its versioned handler implementations, enforces type-safe validation using Zod,
+ * and supports multi-domain event broadcasting and OpenTelemetry observability out of the box.
  *
- * See {@link ArvoEventHandler}
+ * See {@link ArvoEventHandler} for implementation details.
  *
  * @example
- * ```typescript
+ * ```ts
  * const handler = createArvoEventHandler({
  *   contract: userContract,
  *   executionunits: 1,
  *   handler: {
  *     '1.0.0': async ({ event, domain, span }) => {
- *       // Access domain context
- *       if (event.domain === 'priority.high') {
- *         // Handle high-priority processing
- *       }
- *
  *       if (domain.event !== domain.self) {
- *          logToSpan({
- *            level: 'WARN',
- *            message: 'Domain mismatch detected'
- *          }, span)
+ *         logToSpan({
+ *           level: 'WARN',
+ *           message: 'Domain mismatch detected'
+ *         }, span);
  *       }
  *
- *
- *       // Process event according to contract v1.0.0
  *       const result = await processUser(event.data);
  *
- *       // Return structured response
  *       return {
  *         type: 'evt.user.created',
  *         data: result,
- *         // Optional: override default routing
  *         to: 'com.notification.service',
- *         // Creates 2 events:
- *         // - One for 'analytics.realtime' domain (specialized processing)
- *         // - One with no domain (standard processing pipeline)
- *         domain: ['analytics.realtime', null]
  *       };
  *     },
- *     '2.0.0': async ({ event, contract, span }) => {
- *       // Process event according to contract v2.0.0
- *       // Handler must be implemented for all contract versions
+ *     '2.0.0': async ({ event, contract }) => {
+ *       // Handler logic for v2.0.0
  *     }
  *   }
  * });
  * ```
+ *
+ * @param param - Configuration object containing contract, versioned handlers, execution units, and span settings
+ * @returns A fully configured `ArvoEventHandler` instance for the given contract
  */
 export declare const createArvoEventHandler: <TContract extends ArvoContract>(param: IArvoEventHandler<TContract>) => ArvoEventHandler<TContract>;

package/dist/ArvoEventHandler/helpers.js

@@ -6,56 +6,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createArvoEventHandler = void 0;
 var _1 = __importDefault(require("."));
 /**
- * Create the instance of `ArvoEventHandler`
+ * Creates an instance of `ArvoEventHandler` for the specified versioned contract and handlers.
  *
- * > **Caution:** Don't use domained contracts unless it is fully intentional. Using domained
- * contracts causes implicit domain assignment which can be hard to track and confusing. For 99%
- * of the cases you dont need domained contracts
+ * This function is the recommended entry point for defining stateless, contract-driven services in Arvo.
+ * It binds a contract to its versioned handler implementations, enforces type-safe validation using Zod,
+ * and supports multi-domain event broadcasting and OpenTelemetry observability out of the box.
  *
- * See {@link ArvoEventHandler}
+ * See {@link ArvoEventHandler} for implementation details.
  *
  * @example
- * ```typescript
+ * ```ts
  * const handler = createArvoEventHandler({
  *   contract: userContract,
  *   executionunits: 1,
  *   handler: {
  *     '1.0.0': async ({ event, domain, span }) => {
- *       // Access domain context
- *       if (event.domain === 'priority.high') {
- *         // Handle high-priority processing
- *       }
- *
  *       if (domain.event !== domain.self) {
- *          logToSpan({
- *            level: 'WARN',
- *            message: 'Domain mismatch detected'
- *          }, span)
+ *         logToSpan({
+ *           level: 'WARN',
+ *           message: 'Domain mismatch detected'
+ *         }, span);
  *       }
  *
- *
- *       // Process event according to contract v1.0.0
  *       const result = await processUser(event.data);
  *
- *       // Return structured response
  *       return {
  *         type: 'evt.user.created',
  *         data: result,
- *         // Optional: override default routing
  *         to: 'com.notification.service',
- *         // Creates 2 events:
- *         // - One for 'analytics.realtime' domain (specialized processing)
- *         // - One with no domain (standard processing pipeline)
- *         domain: ['analytics.realtime', null]
  *       };
  *     },
- *     '2.0.0': async ({ event, contract, span }) => {
- *       // Process event according to contract v2.0.0
- *       // Handler must be implemented for all contract versions
+ *     '2.0.0': async ({ event, contract }) => {
+ *       // Handler logic for v2.0.0
  *     }
  *   }
  * });
  * ```
+ *
+ * @param param - Configuration object containing contract, versioned handlers, execution units, and span settings
+ * @returns A fully configured `ArvoEventHandler` instance for the given contract
  */
 var createArvoEventHandler = function (param) { return new _1.default(param); };
 exports.createArvoEventHandler = createArvoEventHandler;

package/dist/ArvoEventHandler/index.d.ts

@@ -4,76 +4,84 @@ import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
 import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
 import type { ArvoEventHandlerFunction, IArvoEventHandler } from './types';
 /**
- * ArvoEventHandler is the core component for processing events in the Arvo system. It enforces
- * contracts between services by ensuring that all events follow their specified formats and rules.
+ * `ArvoEventHandler` is the foundational component for building stateless,
+ * contract-bound services in the Arvo system.
  *
- * The handler is built on two fundamental patterns: Meyer's Design by Contract and Fowler's
- * Tolerant Reader. It binds to an ArvoContract that defines what events it can receive and send
- * across all versions. This versioning is strict - the handler must implement every version defined
- * in its contract, or it will fail both at compile time and runtime.
+ * It enforces strict contract validation, version-aware handler resolution,
+ * and safe, observable event emission — all while maintaining type safety,
+ * traceability, and support for multi-domain workflows.
  *
- * Following the Tolerant Reader pattern, the handler accepts any incoming event but only processes
- * those that exactly match one of its contract versions. When an event matches, it's handled by
- * the specific implementation for that version. This approach maintains compatibility while
- * ensuring precise contract adherence.
+ * ## What It Does
+ * - Ensures incoming events match the contract's `type` and `dataschema`
+ * - Resolves the correct contract version using `dataschema`
+ * - Validates input and output data via Zod schemas
+ * - Executes the version-specific handler function
+ * - Emits one or more response events based on the handler result
+ * - Supports multi-domain broadcasting via `domain[]` on the emitted events
+ * - Automatically emits system error events (`sys.*.error`) on failure
+ * - Integrates deeply with OpenTelemetry for tracing and observability
  *
- * The handler uses Zod for validation, automatically checking both incoming and outgoing events.
- * This means it not only verifies data formats but also applies default values where needed and
- * ensures all conditions are met before and after processing.
+ * ## Error Boundaries
+ * ArvoEventHandler enforces a clear separation between:
  *
- * ## Event Processing Lifecycle
+ * - **Violations** — structural, schema, or config errors that break the contract.
+ *   These are thrown and must be handled explicitly by the caller.
  *
- * 1. **Type Validation**: Ensures the incoming event type matches the handler's contract
- * 2. **Contract Resolution**: Extracts version from dataschema and resolves appropriate contract version
- * 3. **Schema Validation**: Validates event data against the contract's accepts schema
- * 4. **Handler Execution**: Invokes the version-specific handler implementation
- * 5. **Response Processing**: Validates and structures handler output into events
- * 6. **Domain Broadcasting**: Creates multiple events for multi-domain distribution if specified
- * 7. **Routing Configuration**: Applies routing logic based on handler output and event context
- * 8. **Telemetry Integration**: Records processing metrics and tracing information
+ * - **System Errors** — runtime exceptions during execution that are caught and
+ *   emitted as standardized `sys.<contract>.error` events.
  *
- * ## Error Handling Strategy
+ * ## Domain Broadcasting
+ * The handler supports multi-domain event distribution. When the handler
+ * returns an event with a `domain` array, it is broadcast to one or more
+ * routing contexts.
  *
- * The handler divides issues into two distinct categories:
+ * ### System Error Domain Control
+ * By default, system error events are broadcast into the source event’s domain,
+ * the handler’s contract domain, and the `null` domain. This fallback ensures errors
+ * are visible across all relevant contexts. Developers can override this behavior
+ * using the optional `systemErrorDomain` field to specify an explicit set of
+ * domain values, including symbolic constants from {@link ArvoDomain}.
  *
- * - **Violations** are serious contract breaches that indicate fundamental problems with how services
- *   are communicating. These errors bubble up to the calling code, allowing developers to handle
- *   these critical issues explicitly. Violations include contract mismatches, schema validation
- *   failures, and configuration errors.
+ * ### Supported Domain Values:
+ * - A **concrete domain string** like `'audit.orders'` or `'human.review'`
+ * - `null` to emit with no domain (standard internal flow)
+ * - A **symbolic reference** from {@link ArvoDomain}
  *
- * - **System Error Events** cover normal runtime errors that occur during event processing. These are
- *   typically workflow-related issues that need to be reported back to the event's source but don't
- *   indicate a broken contract. System errors are converted to structured error events and returned
- *   in the response. **Multi-domain error broadcasting** ensures error events reach all relevant
- *   processing contexts (source event domain, handler contract domain, and null domain).
+ * ### Domain Resolution Rules:
+ * - Each item in the `domain` array is resolved via {@link resolveEventDomain}
+ * - Duplicate domains are deduplicated before emitting
+ * - If `domain` is omitted entirely, Arvo defaults to `[null]`
  *
- * ## Multi-Domain Event Broadcasting
+ * ### Example:
+ * ```ts
+ * return {
+ *   type: 'evt.user.registered',
+ *   data: { ... },
+ *   domain: ['analytics', ArvoDomain.FROM_TRIGGERING_EVENT, null]
+ * };
+ * ```
+ * This would emit at most 3 copies of the event, domained to:
+ * - `'analytics'`
+ * - the domain of the incoming event
+ * - no domain (default)
  *
- * The handler supports sophisticated multi-domain event distribution through array-based domain specification:
+ * ### Domain Usage Guidance
  *
- * ### Domain Assignment Rules:
- * 1. **Array Processing**: Each element in the `domain` array creates a separate ArvoEvent
- * 2. **Undefined Resolution**: `undefined` elements resolve to: `event.domain ?? handler.contract.domain ?? null`
- * 3. **Automatic Deduplication**: Duplicate domains are removed to prevent redundant events
- * 4. **Default Behavior**: Omitted/undefined `domain` field defaults to `[null]` (single event, no domain)
+ * > **Avoid setting `contract.domain` unless fully intentional.**
+ * 99% emitted event should default to `null` (standard processing pipeline).
  *
- * ### Domain Patterns:
- * - `domain: ['domain1', 'domain2']` → Creates 2 events: one for each domain
- * - `domain: ['analytics', undefined, null]` → Creates up to 3 events:
- *   - Event with `domain: 'analytics'`
- *   - Event with `domain: event.domain ?? handler.contract.domain ?? null`
- *   - Event with `domain: null`
- * - `domain: [null]` → Single event with explicit no-domain routing
- * - `domain: undefined` (or omitted) → Single event with `domain: null`
+ * Contract-level domains enforce implicit routing for every emitted event
+ * in that handler, making the behavior harder to override and debug.
  *
- * ### Error Broadcasting:
- * System errors are automatically broadcast to all relevant processing contexts:
- * - Source event domain (`event.domain`)
- * - Handler contract domain (`handler.contract.domain`)
- * - No-domain context (`null`)
+ * Prefer:
+ * - Explicit per-event `domain` values in handler output
+ * - Using `null` or symbolic constants to control domain cleanly
  *
- * Duplicates are automatically removed, so if `event.domain === handler.contract.domain`,
- * only two error events are created instead of three.
+ * ## When to Use Domains
+ * Use domains when handling for specialized contexts:
+ * - `'human.review'` → for human-in-the-loop steps
+ * - `'analytics.workflow'` → to pipe events into observability systems
+ * - `'external.partner.sync'` → to route to external services
  */
 export default class ArvoEventHandler<TContract extends ArvoContract> extends AbstractArvoEventHandler {
     /** Contract instance that defines the event schema and validation rules */
@@ -86,6 +94,7 @@ export default class ArvoEventHandler<TContract extends ArvoContract> extends Ab
     readonly handler: ArvoEventHandlerFunction<TContract>;
     /** The source identifier for events produced by this handler */
     get source(): TContract['type'];
+    readonly systemErrorDomain?: (string | null)[];
     /**
      * The contract-defined domain for this handler, used as the default domain for emitted events.
      * Can be overridden by individual handler implementations for cross-domain workflows.