arvo-event-handler 3.0.14 → 3.0.16

package/dist/ArvoResumable/index.js

@@ -46,59 +46,31 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArvoResumable = void 0;
 var api_1 = require("@opentelemetry/api");
 var arvo_core_1 = require("arvo-core");
 var createEmitableEvent_1 = require("../ArvoOrchestrationUtils/createEmitableEvent");
+var inputValidation_1 = require("../ArvoOrchestrationUtils/inputValidation");
 var orchestrationExecutionWrapper_1 = require("../ArvoOrchestrationUtils/orchestrationExecutionWrapper");
 var index_1 = require("../SyncEventResource/index");
 var errors_1 = require("../errors");
 /**
- * ArvoResumable - A stateful orchestration handler for managing distributed workflows
- *
- * ArvoResumable provides a handler-based approach to workflow orchestration that prioritizes
- * explicit control and simplicity over declarative abstractions. It excels at straightforward
- * request-response patterns and linear workflows while maintaining full type safety and
- * contract validation throughout the execution lifecycle.
- *
- * This class addresses fundamental issues in event-driven architecture including:
- * - Contract management with runtime validation and type safety
- * - Graduated complexity allowing simple workflows to remain simple
- * - Unified event handling across initialization and service responses
- * - Explicit state management without hidden abstractions
- *
- * Key capabilities:
- * - Handler-based workflow orchestration with explicit state control
- * - Contract-driven event validation with runtime schema enforcement
- * - Distributed resource locking for transaction safety
- * - Comprehensive OpenTelemetry integration for observability
- * - Automatic error handling with system error event generation
- * - Support for orchestrator chaining and nested workflow patterns
- * - Domain-based event routing and organization
+ * ArvoResumable complements {@link ArvoOrchestrator} by providing imperative
+ * handler functions for orchestration logic instead of declarative state machines.
+ * While ArvoOrchestrator excels at complex static workflows with deterministic
+ * branching, ArvoResumable handles dynamic orchestrations where branching logic
+ * depends on runtime context and event data.
  *
- * Unlike state machine approaches, ArvoResumable uses imperative handler functions
- * that provide direct control over workflow logic. This makes debugging easier and
- * reduces the learning curve for teams familiar with traditional programming patterns.
- *
- * @see {@link createArvoResumable} Factory function for creating instances
- * @see {@link ArvoResumableHandler} Handler interface documentation
- * @see {@link ArvoResumableState} State structure documentation
+ * Use this for dynamic orchestrations with context-dependent branching
+ * or when preferring imperative programming patterns over state machines.
  */
 var ArvoResumable = /** @class */ (function () {
     function ArvoResumable(param) {
         var _a;
         var _b, _c, _d;
-        this.systemErrorDomain = [];
+        /** Optional domains for routing system error events */
+        this.systemErrorDomain = undefined;
         this.executionunits = param.executionunits;
         this.source = param.contracts.self.type;
         this.syncEventResource = new index_1.SyncEventResource(param.memory, (_b = param.requiresResourceLocking) !== null && _b !== void 0 ? _b : true);
@@ -108,6 +80,7 @@ var ArvoResumable = /** @class */ (function () {
         this.spanOptions = __assign(__assign({ kind: api_1.SpanKind.PRODUCER }, param.spanOptions), { attributes: __assign(__assign((_a = {}, _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = arvo_core_1.ArvoExecutionSpanKind.RESUMABLE, _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = arvo_core_1.OpenInferenceSpanKind.CHAIN, _a), ((_d = (_c = param.spanOptions) === null || _c === void 0 ? void 0 : _c.attributes) !== null && _d !== void 0 ? _d : {})), { 'arvo.handler.source': this.source, 'arvo.contract.uri': this.contracts.self.uri }) });
     }
     Object.defineProperty(ArvoResumable.prototype, "requiresResourceLocking", {
+        /** Whether this resumable requires resource locking for concurrent safety */
         get: function () {
             return this.syncEventResource.requiresResourceLocking;
         },
@@ -115,6 +88,7 @@ var ArvoResumable = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoResumable.prototype, "memory", {
+        /** Memory interface for state persistence and retrieval */
         get: function () {
             return this.syncEventResource.memory;
         },
@@ -122,72 +96,48 @@ var ArvoResumable = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoResumable.prototype, "domain", {
+        /** The contract-defined domain for the handler */
         get: function () {
             return this.contracts.self.domain;
         },
         enumerable: false,
         configurable: true
     });
+    /**
+     * Validates incoming event against self or service contracts.
+     *
+     * Resolves the appropriate contract (self for initialization, service for responses),
+     * validates schema compatibility, and ensures event data matches contract requirements.
+     *
+     * See {@link validateInputEvent} for more infromation
+     */
     ArvoResumable.prototype.validateInput = function (event, span) {
-        var _a;
-        var resolvedContract = null;
-        var contractType;
-        var parsedEventDataSchema = arvo_core_1.EventDataschemaUtil.parse(event);
-        if (!parsedEventDataSchema) {
-            throw new errors_1.ExecutionViolation("Event dataschema resolution failed: Unable to parse dataschema='".concat(event.dataschema, "' for event(id='").concat(event.id, "', type='").concat(event.type, "'). This makes the event opaque and does not allow contract resolution"));
-        }
-        if (event.type === this.contracts.self.type) {
-            contractType = 'self';
-            resolvedContract = this.contracts.self.version(parsedEventDataSchema.version);
-        }
-        else {
-            contractType = 'service';
-            for (var _i = 0, _b = Object.values(this.contracts.services); _i < _b.length; _i++) {
-                var contract = _b[_i];
-                if (resolvedContract)
-                    break;
-                for (var _c = 0, _d = __spreadArray(__spreadArray([], contract.emitList, true), [contract.systemError], false); _c < _d.length; _c++) {
-                    var emitType = _d[_c];
-                    if (resolvedContract)
-                        break;
-                    if (event.type === emitType.type) {
-                        resolvedContract = contract;
-                    }
-                }
-            }
-        }
-        if (!resolvedContract) {
-            throw new errors_1.ConfigViolation("Contract resolution failed: No matching contract found for event (id='".concat(event.id, "', type='").concat(event.type, "')"));
-        }
-        (0, arvo_core_1.logToSpan)({
-            level: 'INFO',
-            message: "Dataschema resolved: ".concat(event.dataschema, " matches contract(uri='").concat(resolvedContract.uri, "', version='").concat(resolvedContract.version, "')"),
-        }, span);
-        if (parsedEventDataSchema.uri !== resolvedContract.uri) {
-            throw new Error("Contract URI mismatch: ".concat(contractType, " Contract(uri='").concat(resolvedContract.uri, "', type='").concat(resolvedContract.accepts.type, "') does not match Event(dataschema='").concat(event.dataschema, "', type='").concat(event.type, "')"));
-        }
-        if (!(0, arvo_core_1.isWildCardArvoSematicVersion)(parsedEventDataSchema.version) &&
-            parsedEventDataSchema.version !== resolvedContract.version) {
-            throw new Error("Contract version mismatch: ".concat(contractType, " Contract(version='").concat(resolvedContract.version, "', type='").concat(resolvedContract.accepts.type, "', uri=").concat(resolvedContract.uri, ") does not match Event(dataschema='").concat(event.dataschema, "', type='").concat(event.type, "')"));
-        }
-        var validationSchema = contractType === 'self'
-            ? resolvedContract.accepts.schema
-            : ((_a = resolvedContract.emits[event.type]) !== null && _a !== void 0 ? _a : resolvedContract.systemError.schema);
-        validationSchema.parse(event.data);
-        return { contractType: contractType };
+        return (0, inputValidation_1.validateInputEvent)({
+            event: event,
+            selfContract: this.contracts.self,
+            serviceContracts: this.contracts.services,
+            span: span,
+        });
     };
     /**
-     * Executes the orchestration workflow for an incoming event
+     * Executes the workflow handler for an incoming event.
      *
-     * @param event - The triggering event to process
-     * @param opentelemetry - OpenTelemetry configuration for trace inheritance
+     * Processes initialization events or service responses through the versioned handler,
+     * manages state persistence, tracks expected events, and generates output events.
+     * Workflows in 'done' status ignore subsequent events without processing.
      *
-     * @returns Object containing domained events
+     * For violation errors (transaction, config, contract), the error is thrown to enable
+     * retry mechanisms. For non-violation errors, system error events are emitted to the
+     * workflow initiator, and the workflow enters a terminal failure state.
+     *
+     * @param event - The incoming event triggering handler execution
+     * @param opentelemetry - Optional OpenTelemetry configuration for tracing
+     * @returns Object containing emitted events from the handler or system errors
      *
      * @throws {TransactionViolation} When distributed lock acquisition fails
      * @throws {ConfigViolation} When handler resolution or contract validation fails
      * @throws {ContractViolation} When event schema validation fails
-     * @throws {ExecutionViolation} When workflow execution encounters critical errors
+     * @throws {ExecutionViolation} When workflow execution encounters critical errors defined by the handler developer
      */
     ArvoResumable.prototype.execute = function (event, opentelemetry) {
         return __awaiter(this, void 0, void 0, function () {
@@ -209,7 +159,7 @@ var ArvoResumable = /** @class */ (function () {
                             selfContract: this.contracts.self.version('latest'),
                             domain: this.domain,
                         }, function (_a) { return __awaiter(_this, [_a], void 0, function (_b) {
-                            var contractType, eventTypeToExpectedEvent, _i, _c, _d, _, eventList, _e, eventList_1, _evt, handler, versionedSelfContract, executionResult, rawEvents, emittables, eventTrackingState, newState;
+                            var inputValidation, contractType, eventTypeToExpectedEvent, _i, _c, _d, _, eventList, _e, eventList_1, _evt, handler, versionedSelfContract, executionResult, rawEvents, emittables, eventTrackingState, newState;
                             var _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
                             var span = _b.span, otelHeaders = _b.otelHeaders, orchestrationParentSubject = _b.orchestrationParentSubject, initEventId = _b.initEventId, parsedEventSubject = _b.parsedEventSubject, state = _b.state;
                             return __generator(this, function (_v) {
@@ -226,7 +176,14 @@ var ArvoResumable = /** @class */ (function () {
                                             level: 'INFO',
                                             message: "Input validation started for event ".concat(event.type),
                                         });
-                                        contractType = this.validateInput(event, span).contractType;
+                                        inputValidation = this.validateInput(event, span);
+                                        if (inputValidation.type === 'CONTRACT_UNRESOLVED') {
+                                            throw new errors_1.ConfigViolation('Contract validation failed - Event does not match any registered contract schemas in the resumable');
+                                        }
+                                        if (inputValidation.type === 'INVALID_DATA' || inputValidation.type === 'INVALID') {
+                                            throw new errors_1.ContractViolation("Input validation failed - Event data does not meet contract requirements: ".concat(inputValidation.error.message));
+                                        }
+                                        contractType = inputValidation.contractType;
                                         if ((state === null || state === void 0 ? void 0 : state.status) === 'done') {
                                             (0, arvo_core_1.logToSpan)({
                                                 level: 'INFO',
@@ -328,7 +285,7 @@ var ArvoResumable = /** @class */ (function () {
     };
     Object.defineProperty(ArvoResumable.prototype, "systemErrorSchema", {
         get: function () {
-            return this.contracts.self.systemError;
+            return __assign(__assign({}, this.contracts.self.systemError), { domain: this.systemErrorDomain });
         },
         enumerable: false,
         configurable: true

package/dist/ArvoResumable/types.d.ts

@@ -1,7 +1,12 @@
 import type { Span } from '@opentelemetry/api';
-import type { ArvoContract, ArvoEvent, ArvoSemanticVersion, CreateArvoEvent, InferArvoEvent, InferVersionedArvoContract, VersionedArvoContract } from 'arvo-core';
+import type { ArvoContract, ArvoEvent, ArvoOrchestratorContract, ArvoSemanticVersion, CreateArvoEvent, InferArvoEvent, InferVersionedArvoContract, VersionedArvoContract } from 'arvo-core';
 import type { EnqueueArvoEventActionParam } from '../ArvoMachine/types';
 import type { OrchestrationExecutionMemoryRecord } from '../ArvoOrchestrationUtils/orchestrationExecutionState';
+import type { IMachineMemory } from '../MachineMemory/interface';
+import type { ArvoEventHandlerOtelSpanOptions } from '../types';
+/**
+ * Extracts all possible event types (including system errors) from service contracts.
+ */
 type ExtractServiceEventTypes<TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = {
     [K in keyof TServiceContract]: {
         [L in keyof InferVersionedArvoContract<TServiceContract[K]>['emits']]: {
@@ -13,142 +18,242 @@ type ExtractServiceEventTypes<TServiceContract extends Record<string, VersionedA
         event: InferVersionedArvoContract<TServiceContract[K]>['systemError'];
     };
 }[keyof TServiceContract];
+/**
+ * Union of all service event type strings.
+ */
 type AllServiceEventTypes<TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = ExtractServiceEventTypes<TServiceContract>['type'];
+/**
+ * Maps event type strings to their corresponding event schemas.
+ */
 type ServiceEventTypeMap<TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = {
     [T in ExtractServiceEventTypes<TServiceContract> as T['type']]: T['event'];
 };
+/**
+ * Handler function signature for processing events in ArvoResumable workflows.
+ *
+ * Handlers are invoked for each incoming event (initialization or service response)
+ * and must be deterministic and idempotent to ensure reliable execution across retries.
+ */
 type Handler<TState extends ArvoResumableState<Record<string, any>>, TSelfContract extends VersionedArvoContract<any, any>, TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = (param: {
+    /** OpenTelemetry span for distributed tracing and observability */
     span: Span;
+    /**
+     * Complete workflow metadata including subject, parent info, and event history.
+     * Null for new workflow initialization.
+     */
     metadata: Omit<TState, 'state$$'> | null;
+    /**
+     * Map of collected service response events grouped by event type.
+     * Enables type-safe access to accumulated responses from external services.
+     * Events are collected based on matching parent IDs with emitted service calls.
+     */
     collectedEvents: Partial<{
         [K in AllServiceEventTypes<TServiceContract>]: ServiceEventTypeMap<TServiceContract>[K][];
     }>;
+    /** Domain information for routing events */
     domain: {
+        /** Domain from the triggering event */
         event: string | null;
+        /** Domain from the resumable's self contract */
         self: string | null;
     };
+    /**
+     * Current workflow state persisted from previous execution.
+     * Null for new workflows or when no state has been saved yet.
+     */
     context: TState['state$$'] | null;
+    /**
+     * Initialization event data for workflow start.
+     * Only present when handler is processing the initialization event that starts the workflow.
+     * Null for service response events.
+     */
     input: InferVersionedArvoContract<TSelfContract>['accepts'] | null;
+    /**
+     * Service response event data.
+     * Only present when handler is processing a response from an external service.
+     * Null for initialization events.
+     */
     service: {
         [K in keyof TServiceContract]: {
             [L in keyof InferVersionedArvoContract<TServiceContract[K]>['emits']]: InferVersionedArvoContract<TServiceContract[K]>['emits'][L];
         }[keyof InferVersionedArvoContract<TServiceContract[K]>['emits']] | InferVersionedArvoContract<TServiceContract[K]>['systemError'];
     }[keyof TServiceContract] | null;
+    /** Contract definitions available to the handler */
     contracts: {
+        /** The resumable's self contract for validation */
         self: TSelfContract;
+        /** Service contracts for emitting compliant events to external systems */
         services: TServiceContract;
     };
 }) => Promise<{
+    /** Updated workflow state to persist for next invocation */
     context?: TState['state$$'];
+    /**
+     * Workflow completion data.
+     * Returning this signals workflow completion and emits the final output event.
+     * The workflow status becomes 'done' and no further events are processed.
+     */
     output?: {
         [L in keyof InferVersionedArvoContract<TSelfContract>['emits']]: EnqueueArvoEventActionParam<InferVersionedArvoContract<TSelfContract>['emits'][L]['data'], InferVersionedArvoContract<TSelfContract>['emits'][L]['type']>['data'];
     }[keyof InferVersionedArvoContract<TSelfContract>['emits']] & {
         __id?: CreateArvoEvent<Record<string, unknown>, string>['id'];
     };
+    /**
+     * Service call events to emit.
+     * Each event triggers an external service and awaits its response in future invocations.
+     * Responses are collected in `collectedEvents` based on parent ID matching.
+     */
     services?: Array<{
         [K in keyof TServiceContract]: EnqueueArvoEventActionParam<InferVersionedArvoContract<TServiceContract[K]>['accepts']['data'], InferVersionedArvoContract<TServiceContract[K]>['accepts']['type']>;
     }[keyof TServiceContract]>;
 } | void>;
 /**
- * The versioned orchestration handlers in ArvoResumable workflows
- *
- * It maps each version of an orchestrator contract to its corresponding handler function.
- * Each handler receives workflow context (state, events, contracts) and returns execution results
- * that can update state, complete the workflow, or invoke external services.
- *
- * The handler is called for each event that matches the orchestrator's contract, whether it's
- * an initialization event or a service response. The handler must be deterministic and
- * idempotent to ensure reliable workflow execution across potential retries.
- *
- * @param param - Handler execution context
- * @param param.span - OpenTelemetry span for distributed tracing
- * @param param.metadata - Complete workflow metadata (null for new workflows)
- * @param param.collectedEvents - Type-safe map of event types to their corresponding typed event arrays,
- *                                enabling strongly-typed access with full IntelliSense support.
- * @param param.context - Current workflow state (null for new workflows)
- * @param param.init - Initialization event data (only present for workflow start events)
- * @param param.service - Service response event data (only present for service callbacks)
- * @param param.contracts - Available contracts for type validation and event creation
- * @param param.contracts.self - The orchestrator's own versioned contract
- * @param param.contracts.services - External service contracts for invocation
+ * Versioned handler map for ArvoResumable workflows.
  *
- * @returns Promise resolving to execution result or void
- * @returns result.context - Updated workflow state to persist
- * @returns result.complete - Workflow completion event to emit (ends the workflow)
- * @returns result.services - Array of service invocation events to emit
+ * Maps contract versions to their corresponding handler implementations.
+ * Each version can have different business logic while maintaining backward compatibility.
  *
- * @remarks
- * - Each version key must match a valid semantic version in the self contract
- * - Handlers should be pure functions without side effects beyond the returned actions
- * - State updates are atomic - either all changes persist or none do
- * - Only one of `init` or `service` will be non-null for any given invocation
- * - Returning void or an empty object indicates no state changes or events to emit
- * - Service events are supposed to queued for execution and may trigger callback events
- * - Completion events terminate the workflow and route to the parent orchestrator
+ * Handlers are invoked for initialization events and service responses matching the
+ * resumable's contract. They must be deterministic and idempotent to ensure reliable
+ * workflow execution across retries and failures.
  */
 export type ArvoResumableHandler<TState extends ArvoResumableState<Record<string, any>>, TSelfContract extends ArvoContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = {
     [V in ArvoSemanticVersion & keyof TSelfContract['versions']]: Handler<TState, VersionedArvoContract<TSelfContract, V>, TServiceContract>;
 };
+/**
+ * State structure persisted in memory for ArvoResumable workflows.
+ *
+ * Extends base orchestration state with resumable-specific fields including
+ * event collection, workflow status tracking, and custom state management.
+ */
 export type ArvoResumableState<T extends Record<string, any>> = OrchestrationExecutionMemoryRecord<{
     /**
-     * Current execution status of the orchestration workflow
-     *
-     * This field tracks the lifecycle state of the workflow instance to determine
-     * whether it can accept new events and continue processing or has reached
-     * its terminal state.
+     * Current workflow status.
      *
-     * @remarks
-     * - **active**: The workflow is running and can accept events for processing.
-     *   It may be waiting for service responses, processing initialization events,
-     *   or handling intermediate workflow steps. The orchestrator will continue
-     *   to route events to active workflows.
-     *
-     * - **done**: The workflow has completed its execution lifecycle. This status
-     *   is set when the handler returns a `complete` event, indicating the workflow
-     *   has finished successfully. Done workflows will not process additional events
-     *   and their state is preserved for audit/debugging purposes.
+     * Determines whether the workflow can process additional events:
+     * - `'active'`: Workflow is running and accepts new events for processing
+     * - `'done'`: Workflow has completed (handler returned `output`). No further events are processed.
      */
     status: 'active' | 'done';
-    /** Unique identifier for the machine instance */
+    /**
+     * Unique identifier for the workflow instance.
+     * Serves as the key for state persistence in the memory store.
+     */
     subject: string;
     /**
-     * Reference to the parent orchestration's subject when orchestrations are nested or chained.
-     * This enables hierarchical orchestration patterns where one orchestration can spawn
-     * sub-orchestrations. When the current orchestration completes, its completion event
-     * is routed back to this parent subject rather than staying within the current context.
+     * Parent orchestration subject for nested workflows.
+     *
+     * Enables hierarchical orchestration where one workflow spawns sub-workflows.
+     * Completion events route back to this parent subject.
      *
-     * - For root orchestrations: null
-     * - For nested orchestrations: contains the subject of the parent orchestration
-     * - Extracted from the `parentSubject$$` field in initialization events
+     * - Root workflows: `null`
+     * - Nested workflows: parent's subject identifier
+     * - Source: `parentSubject$$` in initialization events
      */
     parentSubject: string | null;
     /**
-     * The unique identifier of the event that originally initiated this entire orchestration workflow.
-     * This serves as the root identifier for tracking the complete execution chain from start to finish.
+     * ID of the event that initiated this workflow.
      *
-     * - For new orchestrations: set to the current event's ID
-     * - For resumed orchestrations: retrieved from the stored state
-     * - Used as the `parentid` for completion events to create a direct lineage back to the workflow's origin
+     * Root identifier for tracing the complete execution chain.
+     * Used as `parentid` for completion events to maintain lineage.
      *
-     * This enables tracing the entire execution path and ensures completion events reference
-     * the original triggering event rather than just the immediate previous step.
+     * - New workflows: current event's ID
+     * - Resumed workflows: retrieved from stored state
      */
     initEventId: string;
+    /**
+     * Event history for the current invocation.
+     * Transient collection tracking events consumed, produced, and expected.
+     */
     events: {
-        /** The event consumed by the machine in the last session */
+        /** Event consumed in the last handler invocation */
         consumed: InferArvoEvent<ArvoEvent> | null;
-        /**
-         * The domained events produced by the machine in the last session
-         */
+        /** Events produced (with domain resolution) in the last invocation */
         produced: InferArvoEvent<ArvoEvent>[];
         /**
-         * The events expected by the resumable. These events are collected on each execution
-         * as long as the event parent id and the expected key matches. The expected key is the
-         * event.id of the produced event.
+         * Service response events awaiting collection.
+         *
+         * Keyed by the emitted event's ID (parent ID of responses).
+         * Responses are collected when their `parentid` matches a produced event's `id`.
+         * Collected events are passed to the handler via `collectedEvents` parameter.
          */
         expected: Record<string, InferArvoEvent<ArvoEvent>[]> | null;
     };
-    /** The state used by the resumable */
+    /**
+     * Custom workflow state managed by the handler.
+     * Accessible via the `context` parameter in handlers and persisted between invocations.
+     */
     state$$: T | null;
 }>;
+/**
+ * Configuration parameters for creating an ArvoResumable instance.
+ *
+ * Defines all required components for a resumable workflow orchestrator including
+ * contracts, handlers, memory, and execution settings.
+ */
+export type ArvoResumableParam<TMemory extends Record<string, any>, TSelfContract extends ArvoOrchestratorContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = {
+    /**
+     * Contract definitions for the resumable's event interface.
+     * Defines accepted events, emitted events, and service integrations.
+     */
+    contracts: {
+        /**
+         * Self contract defining initialization input and completion output structures.
+         */
+        self: TSelfContract;
+        /**
+         * Service contracts defining external service interfaces.
+         * Enables type-safe event emission and response handling for external systems.
+         */
+        services: TServiceContract;
+    };
+    /** Computational cost metric for workflow operations */
+    executionunits: number;
+    /** Memory interface for state persistence and retrieval */
+    memory: IMachineMemory<ArvoResumableState<TMemory>>;
+    /** Whether to enforce resource locking for concurrent execution safety */
+    requiresResourceLocking: boolean;
+    /**
+     * Versioned handler map for processing workflow events.
+     * Each contract version maps to its corresponding handler implementation.
+     */
+    handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>;
+    /** Optional domains for system error event routing */
+    systemErrorDomain?: (string | null)[];
+    /** OpenTelemetry span configuration for distributed tracing */
+    spanOptions?: ArvoEventHandlerOtelSpanOptions;
+};
+/**
+ * Configuration parameters for creating an ArvoResumable instance.
+ */
+export type CreateArvoResumableParam<TMemory extends Record<string, any>, TSelfContract extends ArvoOrchestratorContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>> = Record<string, VersionedArvoContract<any, any>>> = {
+    /** Optional type hints for TypeScript inference (not used at runtime) */
+    types?: {
+        context?: Partial<TMemory>;
+    };
+    /** Contract definitions for event interface validation */
+    contracts: {
+        /** Self contract defining initialization and completion events */
+        self: TSelfContract;
+        /** Service contracts for external system integrations */
+        services: TServiceContract;
+    };
+    /** Memory interface for state persistence */
+    memory: IMachineMemory<Record<string, any>>;
+    /** Versioned handler map for processing events */
+    handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>;
+    /**
+     * Computational cost metric for operations.
+     */
+    executionunits?: number;
+    /**
+     * Whether to enforce resource locking for concurrent safety.
+     * @default true if multiple service contracts, false otherwise
+     */
+    requiresResourceLocking?: boolean;
+    /** Optional domains for system error event routing */
+    systemErrorDomain?: (string | null)[];
+    /** OpenTelemetry span configuration for distributed tracing */
+    spanOptions?: ArvoEventHandlerOtelSpanOptions;
+};
 export {};

package/dist/IArvoEventHandler/index.d.ts

@@ -1,36 +1,50 @@
 import type { ArvoContractRecord, ArvoEvent } from 'arvo-core';
 import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
 /**
- * The interface for Arvo event handlers.
+ * Interface for Arvo event handlers.
  *
- * This class defines the basic structure for all Arvo event handlers.
- * It provides an abstract method for executing events, which must be
- * implemented by any concrete subclass.
+ * Defines the contract for all event handlers in the Arvo system, including
+ * orchestrators, resumable handlers, and custom handlers. Each handler must
+ * implement event execution logic and provide system error schema configuration.
  */
 export default interface IArvoEventHandler {
     /**
-     * Unique identifier for the event handler source system
+     * Unique identifier for the event handler's source system.
+     * Used for event routing and tracing throughout the system.
      */
     source: string;
     /**
-     * Executes the event handling logic for a given Arvo event.
+     * Executes the event handling logic for an incoming Arvo event.
      *
-     * @param event - The Arvo event to be processed.
-     * @param opentelemetry - Configuration for OpenTelemetry integration
+     * Processes the event according to the handler's business logic and returns
+     * resulting events to be emitted. The handler may emit multiple events as
+     * outcomes of processing a single input event.
      *
-     * @returns A promise that resolves to an array of resulting Arvo events.
-     * These events represent the outcome of processing the input event.
+     * For violation errors (transaction, execution, contract, config), implementations
+     * typically throw the error to enable retry mechanisms. For non-violation errors,
+     * implementations typically emit system error events to the workflow initiator.
+     *
+     * @param event - The Arvo event to be processed
+     * @param opentelemetry - Optional configuration for distributed tracing integration
+     * @returns Promise resolving to an object containing emitted events
+     *
+     * @throws {ViolationError} When retriable errors occur (lock failures, validation errors, etc.)
      */
     execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<{
         events: ArvoEvent[];
     }>;
     /**
-     * Provides the schema for system error events.
+     * Schema configuration for system error events.
      *
-     * @returns An object containing the error event type and schema.
+     * Defines the structure and routing for error events emitted when unexpected
+     * errors occur during event handling. System errors are sent to the workflow
+     * initiator to signal terminal failures that cannot be automatically recovered.
      *
-     * This defines the structure for system error events that may be emitted
-     * when an unexpected error occurs during event handling.
+     * @property type - The error event type identifier
+     * @property schema - Zod schema defining the error event data structure
+     * @property domain - Optional domains for error event routing and distribution
      */
-    systemErrorSchema: ArvoContractRecord;
+    systemErrorSchema: ArvoContractRecord & {
+        domain?: (string | null)[];
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "3.0.14",
+  "version": "3.0.16",
   "description": "Type-safe event handler system with versioning, telemetry, and contract validation for distributed Arvo event-driven architectures, featuring routing and multi-handler support.",
   "main": "dist/index.js",
   "scripts": {
@@ -46,7 +46,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^1.30.1",
-    "arvo-core": "^3.0.14",
+    "arvo-core": "^3.0.16",
     "uuid": "^11.1.0",
     "xstate": "^5.23.0",
     "zod": "^3.25.74",