arvo-event-handler 3.0.13 → 3.0.15

package/dist/ArvoOrchestrationUtils/orchestrationExecutionState.d.ts

@@ -1,7 +1,30 @@
+/**
+ * Enumeration of possible orchestration execution statuses.
+ *
+ * Determines whether an orchestration is executing normally or has encountered
+ * a terminal failure requiring error event emission.
+ */
 export declare const OrchestrationExecutionStatus: {
-    readonly FAILURE: "failure";
+    /** Orchestration is executing normally */
     readonly NORMAL: "normal";
+    /** Orchestration has failed and entered terminal error state */
+    readonly FAILURE: "failure";
 };
+/**
+ * Discriminated union representing persisted orchestration state.
+ *
+ * The execution status discriminates between normal execution state (containing
+ * full orchestration data) and failure state (containing minimal error context).
+ *
+ * **Normal state**: Contains complete orchestration data including machine state,
+ * event history, and all custom fields from type parameter T.
+ *
+ * **Failure state**: Contains only essential error information (error object, subject)
+ * with partial custom fields. Once in failure state, the orchestration ignores
+ * subsequent events and does not execute further.
+ *
+ * @template T - Custom state fields specific to the orchestration type
+ */
 export type OrchestrationExecutionMemoryRecord<T extends Record<string, unknown>> = (T & {
     executionStatus: typeof OrchestrationExecutionStatus.NORMAL;
 }) | (Partial<T> & {

package/dist/ArvoOrchestrationUtils/orchestrationExecutionState.js

@@ -1,7 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrchestrationExecutionStatus = void 0;
+/**
+ * Enumeration of possible orchestration execution statuses.
+ *
+ * Determines whether an orchestration is executing normally or has encountered
+ * a terminal failure requiring error event emission.
+ */
 exports.OrchestrationExecutionStatus = {
-    FAILURE: 'failure',
+    /** Orchestration is executing normally */
     NORMAL: 'normal',
+    /** Orchestration has failed and entered terminal error state */
+    FAILURE: 'failure',
 };

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/acquireLockWithValidation.d.ts

@@ -3,6 +3,10 @@ import { type ArvoEvent } from 'arvo-core';
 import type { SyncEventResource } from '../../SyncEventResource';
 import type { AcquiredLockStatusType } from '../../SyncEventResource/types';
 /**
- * Handles lock acquisition with proper error handling
+ * Acquires an exclusive lock for event processing with validation.
+ *
+ * Attempts to obtain a lock on the event's subject to ensure exclusive access during
+ * processing. Throws if lock cannot be acquired, preventing concurrent modifications.
+ * @throws {TransactionViolation} When lock cannot be acquired
  */
 export declare const acquireLockWithValidation: (syncEventResource: SyncEventResource<Record<string, any>>, event: ArvoEvent, span: Span) => Promise<AcquiredLockStatusType>;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/acquireLockWithValidation.js

@@ -40,7 +40,11 @@ exports.acquireLockWithValidation = void 0;
 var arvo_core_1 = require("arvo-core");
 var error_1 = require("../error");
 /**
- * Handles lock acquisition with proper error handling
+ * Acquires an exclusive lock for event processing with validation.
+ *
+ * Attempts to obtain a lock on the event's subject to ensure exclusive access during
+ * processing. Throws if lock cannot be acquired, preventing concurrent modifications.
+ * @throws {TransactionViolation} When lock cannot be acquired
  */
 var acquireLockWithValidation = function (syncEventResource, event, span) { return __awaiter(void 0, void 0, void 0, function () {
     var acquiredLock;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/index.d.ts

@@ -5,38 +5,77 @@ import type { SyncEventResource } from '../../SyncEventResource';
 import type { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions } from '../../types';
 import type { OrchestrationExecutionMemoryRecord } from '../orchestrationExecutionState';
 import type { ArvoOrchestrationHandlerType } from '../types';
+/**
+ * Configuration context for orchestration execution.
+ * Contains all resources and settings needed for the execution lifecycle.
+ */
 export type OrchestrationExecutionContext<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = {
+    /** Event triggering the orchestration */
     event: ArvoEvent;
+    /** OpenTelemetry configuration for tracing */
     opentelemetry: ArvoEventHandlerOpenTelemetryOptions;
+    /** Source identifier for the orchestrator */
     source: string;
+    /** Resource manager for state and lock operations */
     syncEventResource: SyncEventResource<TState>;
+    /** Maximum execution units per cycle */
     executionunits: number;
+    /** Optional domains for system error routing */
     systemErrorDomain?: (string | null)[];
+    /** Self contract defining orchestrator interface */
     selfContract: VersionedArvoContract<ArvoOrchestratorContract, ArvoSemanticVersion>;
+    /** Domain for event routing */
     domain: string | null;
+    /** Type of orchestration handler */
     _handlerType: ArvoOrchestrationHandlerType;
+    /** OpenTelemetry span configuration */
     spanOptions: ArvoEventHandlerOtelSpanOptions & {
         spanName: NonNullable<ArvoEventHandlerOtelSpanOptions['spanName']>;
     };
 };
+/**
+ * Core execution function signature for orchestration logic.
+ * Receives prepared context and returns emitted events with new state.
+ */
 export type CoreExecutionFn<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = (params: {
+    /** OpenTelemetry span for tracing */
     span: any;
+    /** Current OpenTelemetry headers */
     otelHeaders: OpenTelemetryHeaders;
+    /** Parent orchestration subject if nested */
     orchestrationParentSubject: string | null;
+    /** ID of the initialization event */
     initEventId: string;
+    /** Parsed event subject content */
     parsedEventSubject: ArvoOrchestrationSubjectContent;
+    /** Current persisted state or null for new orchestrations */
     state: TState | null;
+    /** Type of handler executing */
     _handlerType: ArvoOrchestrationHandlerType;
 }) => Promise<{
+    /** Events to emit from this execution */
     emittables: ArvoEvent[];
+    /** New state to persist */
     newState: TState;
 }>;
+/**
+ * Helper to log and return execution results.
+ * @returns The same result after logging
+ */
 export declare const returnEventsWithLogging: (param: Awaited<ReturnType<IArvoEventHandler["execute"]>>, span: Span) => Awaited<ReturnType<IArvoEventHandler["execute"]>>;
 /**
- * Wraps orchestration execution with common infrastructure:
- * - OpenTelemetry span management
- * - Lock acquisition and release
- * - State management
- * - Error handling and system error generation
+ * Wraps orchestration execution with infrastructure concerns.
+ *
+ * Provides a complete execution wrapper that handles:
+ * - OpenTelemetry span creation and management
+ * - Event subject validation and parsing
+ * - Lock acquisition for concurrent safety
+ * - State retrieval and persistence
+ * - Error handling with system error event generation
+ * - Lock release in all scenarios
+ *
+ * This wrapper ensures consistent behavior across all orchestration handlers
+ * while allowing custom core logic via the execution function parameter.
+ * @returns Emitted events from successful execution or error handling
  */
 export declare const executeWithOrchestrationWrapper: <TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>>({ event, opentelemetry, spanOptions, source, syncEventResource, executionunits, systemErrorDomain, selfContract, domain, _handlerType, }: OrchestrationExecutionContext<TState>, coreExecutionFn: CoreExecutionFn<TState>) => Promise<Awaited<ReturnType<IArvoEventHandler["execute"]>>>;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/index.js

@@ -54,6 +54,10 @@ var utils_1 = require("../../utils");
 var handlerErrors_1 = require("../handlerErrors");
 var acquireLockWithValidation_1 = require("./acquireLockWithValidation");
 var validateAndParseSubject_1 = require("./validateAndParseSubject");
+/**
+ * Helper to log and return execution results.
+ * @returns The same result after logging
+ */
 var returnEventsWithLogging = function (param, span) {
     var _a, _b;
     (0, arvo_core_1.logToSpan)({
@@ -64,11 +68,19 @@ var returnEventsWithLogging = function (param, span) {
 };
 exports.returnEventsWithLogging = returnEventsWithLogging;
 /**
- * Wraps orchestration execution with common infrastructure:
- * - OpenTelemetry span management
- * - Lock acquisition and release
- * - State management
- * - Error handling and system error generation
+ * Wraps orchestration execution with infrastructure concerns.
+ *
+ * Provides a complete execution wrapper that handles:
+ * - OpenTelemetry span creation and management
+ * - Event subject validation and parsing
+ * - Lock acquisition for concurrent safety
+ * - State retrieval and persistence
+ * - Error handling with system error event generation
+ * - Lock release in all scenarios
+ *
+ * This wrapper ensures consistent behavior across all orchestration handlers
+ * while allowing custom core logic via the execution function parameter.
+ * @returns Emitted events from successful execution or error handling
  */
 var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return __awaiter(void 0, [_a, coreExecutionFn_1], void 0, function (_b, coreExecutionFn) {
     var otelConfig;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/validateAndParseSubject.d.ts

@@ -2,6 +2,11 @@ import type { Span } from '@opentelemetry/api';
 import { type ArvoEvent, type ArvoOrchestrationSubjectContent } from 'arvo-core';
 import type { SyncEventResource } from '../../SyncEventResource';
 /**
- * Validates and parses orchestration subject
+ * Validates and parses an orchestration event's subject.
+ *
+ * Ensures the event subject is valid and matches the expected orchestrator source.
+ * Returns null if validation fails, allowing graceful handling of mismatched events.
+ *
+ * @returns Parsed subject content or null if validation fails
  */
 export declare const validateAndParseSubject: (event: ArvoEvent, expectedSource: string, syncEventResource: SyncEventResource<any>, span: Span, handlerType: "orchestrator" | "resumable") => ArvoOrchestrationSubjectContent | null;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/validateAndParseSubject.js

@@ -3,7 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateAndParseSubject = void 0;
 var arvo_core_1 = require("arvo-core");
 /**
- * Validates and parses orchestration subject
+ * Validates and parses an orchestration event's subject.
+ *
+ * Ensures the event subject is valid and matches the expected orchestrator source.
+ * Returns null if validation fails, allowing graceful handling of mismatched events.
+ *
+ * @returns Parsed subject content or null if validation fails
  */
 var validateAndParseSubject = function (event, expectedSource, syncEventResource, span, handlerType) {
     var _a;

package/dist/ArvoOrchestrationUtils/servicesValidation.d.ts

@@ -1,13 +1,11 @@
 import type { ArvoContract, VersionedArvoContract } from 'arvo-core';
 import { type ArvoOrchestrationHandlerType } from './types';
 /**
- * Validates that all service contracts in a collection have unique URIs.
+ * Validates that all service contracts have unique URIs.
  *
- * Iterates through the provided contracts and checks if any URI appears more than once.
- * Multiple versions of the same contract (with the same URI) are not allowed.
- *
- * @param contracts - A record mapping contract keys to their respective ArvoContract objects
- * @returns An object with a boolean result indicating if all contracts are unique, and the error keys if not
+ * Ensures no duplicate contract URIs exist in the service collection.
+ * Multiple versions of the same contract (same URI) are not permitted as
+ * they create ambiguity in event routing and contract resolution.
  */
 export declare const areServiceContractsUnique: (contracts: Record<string, ArvoContract | VersionedArvoContract<any, any>>) => {
     result: false;
@@ -16,6 +14,16 @@ export declare const areServiceContractsUnique: (contracts: Record<string, ArvoC
 } | {
     result: true;
 };
+/**
+ * Validates service contracts for orchestration handlers.
+ *
+ * Performs two critical validations:
+ * 1. Ensures all service contracts have unique URIs (no duplicate contracts)
+ * 2. Prevents circular dependencies (self contract not registered as service)
+ *
+ * These validations prevent configuration errors that would cause runtime
+ * failures or infinite execution loops in orchestration workflows.
+ */
 export declare const servicesValidation: (contracts: {
     self: ArvoContract | VersionedArvoContract<any, any>;
     services: Record<string, VersionedArvoContract<any, any>>;

package/dist/ArvoOrchestrationUtils/servicesValidation.js

@@ -16,13 +16,11 @@ var uuid_1 = require("uuid");
 var errors_1 = require("../errors");
 var types_1 = require("./types");
 /**
- * Validates that all service contracts in a collection have unique URIs.
+ * Validates that all service contracts have unique URIs.
  *
- * Iterates through the provided contracts and checks if any URI appears more than once.
- * Multiple versions of the same contract (with the same URI) are not allowed.
- *
- * @param contracts - A record mapping contract keys to their respective ArvoContract objects
- * @returns An object with a boolean result indicating if all contracts are unique, and the error keys if not
+ * Ensures no duplicate contract URIs exist in the service collection.
+ * Multiple versions of the same contract (same URI) are not permitted as
+ * they create ambiguity in event routing and contract resolution.
  */
 var areServiceContractsUnique = function (contracts) {
     var uriToKeyMap = {};
@@ -42,6 +40,16 @@ var areServiceContractsUnique = function (contracts) {
     };
 };
 exports.areServiceContractsUnique = areServiceContractsUnique;
+/**
+ * Validates service contracts for orchestration handlers.
+ *
+ * Performs two critical validations:
+ * 1. Ensures all service contracts have unique URIs (no duplicate contracts)
+ * 2. Prevents circular dependencies (self contract not registered as service)
+ *
+ * These validations prevent configuration errors that would cause runtime
+ * failures or infinite execution loops in orchestration workflows.
+ */
 var servicesValidation = function (contracts, _handlerType) {
     var _a;
     var __areServiceContractsUnique = (0, exports.areServiceContractsUnique)(contracts.services);

package/dist/ArvoOrchestrator/factory.d.ts

@@ -2,28 +2,31 @@ import { ArvoOrchestrator } from '.';
 import type { CreateArvoOrchestratorParam } from './types';
 /**
  * Creates a new Arvo orchestrator instance with default components.
- * For custom components, use ArvoOrchestrator constructor directly.
  *
- * @param config - Orchestrator configuration
- * @param config.memory - State persistence interface for storing machine states
- * @param config.executionunits - Cost units for execution tracking
- * @param config.machines - Array of state machines to manage. Their resource locking flags determine orchestrator's locking behavior
- * @param config.systemErrorDomain - An optional array of system error domain overrides
- * @returns Configured ArvoOrchestrator instance with default registry and execution engine
+ * Factory function that constructs an orchestrator with standard execution engine
+ * and registry implementations. Validates that all machines share the same source
+ * identifier and have unique versions.
  *
- * @remarks
- * The orchestrator's resource locking is enabled if any machine requires it. Locking is needed when:
- * - Machine contains parallel states where multiple states can be active simultaneously
- * - Race conditions need to be prevented in concurrent processing
- * - State consistency must be maintained across distributed executions
+ * @param params - Configuration parameters for the orchestrator
+ * @returns Configured ArvoOrchestrator instance ready for event handling
+ *
+ * @throws {Error} When no machines are provided
+ * @throws {ConfigViolation} When machines have different source identifiers
+ * @throws {ConfigViolation} When machines have duplicate versions
  *
  * @example
  * ```typescript
  * const orchestrator = createArvoOrchestrator({
- *   memory: new SimpleMachineMemory() // or, any other IMachineMemory implementation,
+ *   memory: new SimpleMachineMemory(),
  *   executionunits: 1,
- *   machines: [machineA, machineB]
+ *   machines: [userOnboardingMachine, paymentMachine]
  * });
+ *
+ * // Process events
+ * const result = await orchestrator.execute(event);
  * ```
+ *
+ * @see {@link setupArvoMachine} for creating machine definitions
+ * @see {@link ArvoOrchestrator} for direct instantiation with custom components
  */
-export declare const createArvoOrchestrator: ({ executionunits, memory, machines, systemErrorDomain, spanOptions, }: CreateArvoOrchestratorParam) => ArvoOrchestrator;
+export declare const createArvoOrchestrator: ({ executionunits, memory, machines, systemErrorDomain, spanOptions, requiresResourceLocking: _locking, }: CreateArvoOrchestratorParam) => ArvoOrchestrator;

package/dist/ArvoOrchestrator/factory.js

@@ -16,37 +16,40 @@ var MachineRegistry_1 = require("../MachineRegistry");
 var errors_1 = require("../errors");
 /**
  * Creates a new Arvo orchestrator instance with default components.
- * For custom components, use ArvoOrchestrator constructor directly.
  *
- * @param config - Orchestrator configuration
- * @param config.memory - State persistence interface for storing machine states
- * @param config.executionunits - Cost units for execution tracking
- * @param config.machines - Array of state machines to manage. Their resource locking flags determine orchestrator's locking behavior
- * @param config.systemErrorDomain - An optional array of system error domain overrides
- * @returns Configured ArvoOrchestrator instance with default registry and execution engine
+ * Factory function that constructs an orchestrator with standard execution engine
+ * and registry implementations. Validates that all machines share the same source
+ * identifier and have unique versions.
  *
- * @remarks
- * The orchestrator's resource locking is enabled if any machine requires it. Locking is needed when:
- * - Machine contains parallel states where multiple states can be active simultaneously
- * - Race conditions need to be prevented in concurrent processing
- * - State consistency must be maintained across distributed executions
+ * @param params - Configuration parameters for the orchestrator
+ * @returns Configured ArvoOrchestrator instance ready for event handling
+ *
+ * @throws {Error} When no machines are provided
+ * @throws {ConfigViolation} When machines have different source identifiers
+ * @throws {ConfigViolation} When machines have duplicate versions
  *
  * @example
  * ```typescript
  * const orchestrator = createArvoOrchestrator({
- *   memory: new SimpleMachineMemory() // or, any other IMachineMemory implementation,
+ *   memory: new SimpleMachineMemory(),
  *   executionunits: 1,
- *   machines: [machineA, machineB]
+ *   machines: [userOnboardingMachine, paymentMachine]
  * });
+ *
+ * // Process events
+ * const result = await orchestrator.execute(event);
  * ```
+ *
+ * @see {@link setupArvoMachine} for creating machine definitions
+ * @see {@link ArvoOrchestrator} for direct instantiation with custom components
  */
 var createArvoOrchestrator = function (_a) {
-    var executionunits = _a.executionunits, memory = _a.memory, machines = _a.machines, systemErrorDomain = _a.systemErrorDomain, spanOptions = _a.spanOptions;
+    var executionunits = _a.executionunits, memory = _a.memory, machines = _a.machines, systemErrorDomain = _a.systemErrorDomain, spanOptions = _a.spanOptions, _locking = _a.requiresResourceLocking;
     if (!(machines === null || machines === void 0 ? void 0 : machines.length)) {
         throw new Error('At least one machine must be provided');
     }
     var registry = new (MachineRegistry_1.MachineRegistry.bind.apply(MachineRegistry_1.MachineRegistry, __spreadArray([void 0], machines, false)))();
-    var requiresResourceLocking = machines.some(function (machine) { return machine.requiresResourceLocking; });
+    var requiresResourceLocking = _locking !== null && _locking !== void 0 ? _locking : machines.some(function (machine) { return machine.requiresResourceLocking; });
     var representativeMachine = registry.machines[0];
     var lastSeenVersions = [];
     for (var _i = 0, _b = registry.machines; _i < _b.length; _i++) {

package/dist/ArvoOrchestrator/index.d.ts

@@ -1,49 +1,81 @@
-import { type ArvoContractRecord, type ArvoEvent } from 'arvo-core';
+import { type ArvoEvent } from 'arvo-core';
 import type IArvoEventHandler from '../IArvoEventHandler';
 import type { IMachineExectionEngine } from '../MachineExecutionEngine/interface';
 import type { IMachineMemory } from '../MachineMemory/interface';
 import type { IMachineRegistry } from '../MachineRegistry/interface';
 import { SyncEventResource } from '../SyncEventResource';
-import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+import type { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions } from '../types';
 import type { ArvoOrchestratorParam, MachineMemoryRecord } from './types';
 /**
  * Orchestrates state machine execution and lifecycle management.
- * Handles machine resolution, state management, event processing and error handling.
+ *
+ * Coordinates machine resolution, state persistence, event processing, and error handling
+ * for Arvo's event-driven orchestration workflows. Manages the complete lifecycle from
+ * event receipt through machine execution to emitting result events.
  */
 export declare class ArvoOrchestrator implements IArvoEventHandler {
+    /** Computational cost metric associated with event handling operations */
     readonly executionunits: number;
+    /** Registry containing available state machines */
     readonly registry: IMachineRegistry;
+    /** Engine responsible for executing state machine logic */
     readonly executionEngine: IMachineExectionEngine;
+    /** Resource manager for state synchronization and memory access */
     readonly syncEventResource: SyncEventResource<MachineMemoryRecord>;
+    /** Optional domains for routing system error events */
     readonly systemErrorDomain?: (string | null)[];
-    private readonly spanOptions;
+    /** OpenTelemetry span configuration for observability */
+    readonly spanOptions: ArvoEventHandlerOtelSpanOptions;
+    /** Source identifier from the first registered machine */
     get source(): any;
+    /** Whether this orchestrator requires resource locking for concurrent safety */
     get requiresResourceLocking(): boolean;
+    /** Memory interface for state persistence and retrieval */
     get memory(): IMachineMemory<MachineMemoryRecord>;
+    /** The contract-defined domain for the handler */
     get domain(): string | null;
-    /**
-     * Creates a new orchestrator instance
-     * @param params - Configuration parameters
-     * @throws Error if machines in registry have different sources
-     */
     constructor({ executionunits, memory, registry, executionEngine, requiresResourceLocking, systemErrorDomain, spanOptions, }: ArvoOrchestratorParam);
     /**
-     * Core orchestration method that executes state machines in response to events.
+     * Executes state machine orchestration for an incoming event.
+     *
+     * Performs the complete orchestration workflow: resolves the appropriate machine,
+     * validates input, executes the machine logic, processes emitted events, and persists
+     * the new state. Handles both new orchestrations and continuation of existing ones.
+     *
+     * For violation errors (transaction, execution, contract, config), the error is thrown
+     * to enable retry mechanisms. For non-violation errors, system error events are emitted
+     * to the workflow initiator, and the orchestration enters a terminal failure state.
      *
-     * @param event - Event triggering the execution
-     * @param opentelemetry - OpenTelemetry configuration
-     * @returns Object containing domained events
+     * @param event - The incoming event triggering orchestration
+     * @param opentelemetry - Optional OpenTelemetry configuration for tracing
+     * @returns Object containing emitted events from the orchestration or system errors
      *
-     * @throws {TransactionViolation} Lock/state operations failed
-     * @throws {ExecutionViolation} Invalid event structure/flow
-     * @throws {ContractViolation} Schema/contract mismatch
-     * @throws {ConfigViolation} Missing/invalid machine version
+     * @throws {TransactionViolation} When lock acquisition or state operations fail (retriable)
+     * @throws {ContractViolation} When event data doesn't match contract schema (retriable)
+     * @throws {ConfigViolation} When machine resolution fails or version is missing (retriable)
+     * @throws {ExecutionViolation} When workflow execution encounters critical errors defined by the handler developer
      */
     execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<{
         events: ArvoEvent[];
     }>;
     /**
-     * Gets the error schema for this orchestrator
+     * Provides access to the system error event schema configuration.
      */
-    get systemErrorSchema(): ArvoContractRecord;
+    get systemErrorSchema(): {
+        type: any;
+        schema: import("zod").ZodObject<{
+            errorName: import("zod").ZodString;
+            errorMessage: import("zod").ZodString;
+            errorStack: import("zod").ZodNullable<import("zod").ZodString>;
+        }, "strip", import("zod").ZodTypeAny, {
+            errorName: string;
+            errorMessage: string;
+            errorStack: string | null;
+        }, {
+            errorName: string;
+            errorMessage: string;
+            errorStack: string | null;
+        }>;
+        domain: (string | null)[] | undefined;
+    };
 }

package/dist/ArvoOrchestrator/index.js

@@ -56,19 +56,18 @@ var SyncEventResource_1 = require("../SyncEventResource");
 var errors_1 = require("../errors");
 /**
  * Orchestrates state machine execution and lifecycle management.
- * Handles machine resolution, state management, event processing and error handling.
+ *
+ * Coordinates machine resolution, state persistence, event processing, and error handling
+ * for Arvo's event-driven orchestration workflows. Manages the complete lifecycle from
+ * event receipt through machine execution to emitting result events.
  */
 var ArvoOrchestrator = /** @class */ (function () {
-    /**
-     * Creates a new orchestrator instance
-     * @param params - Configuration parameters
-     * @throws Error if machines in registry have different sources
-     */
     function ArvoOrchestrator(_a) {
         var _b;
         var executionunits = _a.executionunits, memory = _a.memory, registry = _a.registry, executionEngine = _a.executionEngine, requiresResourceLocking = _a.requiresResourceLocking, systemErrorDomain = _a.systemErrorDomain, spanOptions = _a.spanOptions;
         var _c, _d, _e, _f, _g, _h, _j;
-        this.systemErrorDomain = [];
+        /** Optional domains for routing system error events */
+        this.systemErrorDomain = undefined;
         this.executionunits = executionunits;
         this.registry = registry;
         this.executionEngine = executionEngine;
@@ -77,6 +76,7 @@ var ArvoOrchestrator = /** @class */ (function () {
         this.spanOptions = __assign(__assign({ kind: api_1.SpanKind.PRODUCER }, spanOptions), { attributes: __assign(__assign((_b = {}, _b[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = arvo_core_1.ArvoExecutionSpanKind.ORCHESTRATOR, _b[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = arvo_core_1.OpenInferenceSpanKind.CHAIN, _b), ((_c = spanOptions === null || spanOptions === void 0 ? void 0 : spanOptions.attributes) !== null && _c !== void 0 ? _c : {})), { 'arvo.handler.source': this.source, 'arvo.contract.uri': (_j = (_h = (_g = (_f = (_e = (_d = this === null || this === void 0 ? void 0 : this.registry) === null || _d === void 0 ? void 0 : _d.machines) === null || _e === void 0 ? void 0 : _e[0]) === null || _f === void 0 ? void 0 : _f.contracts) === null || _g === void 0 ? void 0 : _g.self) === null || _h === void 0 ? void 0 : _h.uri) !== null && _j !== void 0 ? _j : 'N/A' }) });
     }
     Object.defineProperty(ArvoOrchestrator.prototype, "source", {
+        /** Source identifier from the first registered machine */
         get: function () {
             return this.registry.machines[0].source;
         },
@@ -84,6 +84,7 @@ var ArvoOrchestrator = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoOrchestrator.prototype, "requiresResourceLocking", {
+        /** Whether this orchestrator requires resource locking for concurrent safety */
         get: function () {
             return this.syncEventResource.requiresResourceLocking;
         },
@@ -91,6 +92,7 @@ var ArvoOrchestrator = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoOrchestrator.prototype, "memory", {
+        /** Memory interface for state persistence and retrieval */
         get: function () {
             return this.syncEventResource.memory;
         },
@@ -98,6 +100,7 @@ var ArvoOrchestrator = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoOrchestrator.prototype, "domain", {
+        /** The contract-defined domain for the handler */
         get: function () {
             return this.registry.machines[0].contracts.self.domain;
         },
@@ -105,16 +108,24 @@ var ArvoOrchestrator = /** @class */ (function () {
         configurable: true
     });
     /**
-     * Core orchestration method that executes state machines in response to events.
+     * Executes state machine orchestration for an incoming event.
+     *
+     * Performs the complete orchestration workflow: resolves the appropriate machine,
+     * validates input, executes the machine logic, processes emitted events, and persists
+     * the new state. Handles both new orchestrations and continuation of existing ones.
+     *
+     * For violation errors (transaction, execution, contract, config), the error is thrown
+     * to enable retry mechanisms. For non-violation errors, system error events are emitted
+     * to the workflow initiator, and the orchestration enters a terminal failure state.
      *
-     * @param event - Event triggering the execution
-     * @param opentelemetry - OpenTelemetry configuration
-     * @returns Object containing domained events
+     * @param event - The incoming event triggering orchestration
+     * @param opentelemetry - Optional OpenTelemetry configuration for tracing
+     * @returns Object containing emitted events from the orchestration or system errors
      *
-     * @throws {TransactionViolation} Lock/state operations failed
-     * @throws {ExecutionViolation} Invalid event structure/flow
-     * @throws {ContractViolation} Schema/contract mismatch
-     * @throws {ConfigViolation} Missing/invalid machine version
+     * @throws {TransactionViolation} When lock acquisition or state operations fail (retriable)
+     * @throws {ContractViolation} When event data doesn't match contract schema (retriable)
+     * @throws {ConfigViolation} When machine resolution fails or version is missing (retriable)
+     * @throws {ExecutionViolation} When workflow execution encounters critical errors defined by the handler developer
      */
     ArvoOrchestrator.prototype.execute = function (event, opentelemetry) {
         return __awaiter(this, void 0, void 0, function () {
@@ -152,7 +163,7 @@ var ArvoOrchestrator = /** @class */ (function () {
                                     level: 'INFO',
                                     message: "Input validation started for event ".concat(event.type, " on machine ").concat(machine.source),
                                 }, span);
-                                inputValidation = machine.validateInput(event);
+                                inputValidation = machine.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 machine');
                                 }
@@ -212,12 +223,13 @@ var ArvoOrchestrator = /** @class */ (function () {
     };
     Object.defineProperty(ArvoOrchestrator.prototype, "systemErrorSchema", {
         /**
-         * Gets the error schema for this orchestrator
+         * Provides access to the system error event schema configuration.
          */
         get: function () {
             return {
                 type: this.registry.machines[0].contracts.self.systemError.type,
                 schema: arvo_core_1.ArvoErrorSchema,
+                domain: this.systemErrorDomain,
             };
         },
         enumerable: false,