arvo-event-handler 2.3.3 → 3.0.1

package/dist/ArvoEventHandler/types.d.ts

@@ -1,14 +1,21 @@
 import type { Span, SpanOptions } from '@opentelemetry/api';
-import type { ArvoContract, ArvoEvent, ArvoSemanticVersion, CreateArvoEvent, VersionedArvoContract } from 'arvo-core';
+import type { ArvoContract, ArvoEvent, ArvoSemanticVersion, CreateArvoEvent, InferArvoEvent, VersionedArvoContract } from 'arvo-core';
 import type { z } from 'zod';
 /**
  * Represents the input for an ArvoEvent handler function.
  */
 export type ArvoEventHandlerFunctionInput<TContract extends VersionedArvoContract<any, any>> = {
     /** The ArvoEvent object. */
-    event: ArvoEvent<z.infer<TContract['accepts']['schema']>, Record<string, any>, TContract['accepts']['type']>;
+    event: InferArvoEvent<ArvoEvent<z.infer<TContract['accepts']['schema']>, Record<string, any>, TContract['accepts']['type']>>;
     /** The source field data of the handler */
     source: string;
+    /** The domain information for handling the event */
+    domain: {
+        self: string | null;
+        event: string | null;
+    };
+    /** The contract used in the processing */
+    contract: TContract;
     /** The OpenTelemetry span */
     span: Span;
 };
@@ -27,6 +34,22 @@ export type ArvoEventHandlerFunctionOutput<TContract extends VersionedArvoContra
         executionunits?: number;
         /** Optional extensions for the event. */
         __extensions?: Record<string, string | number | boolean>;
+        /**
+         * The event domain configuration for multi-domain broadcasting.
+         *
+         * **Domain Broadcasting Rules:**
+         * - Each element in the array creates a separate ArvoEvent instance
+         * - `undefined` elements resolve using inheritance: `event.domain ?? contract.domain ?? null`
+         * - Duplicate domains are automatically removed to prevent redundant events
+         * - Omitting this field (or setting to `undefined`) defaults to `[null]`
+         *
+         * **Domain Broadcasting Patterns:**
+         * - `['domain1', 'domain2']` → Creates 2 events for different processing contexts
+         * - `['analytics', undefined, 'audit']` → Creates events for analytics, inherited context, and audit
+         * - `[null]` → Creates single event with no domain routing (standard processing)
+         * - `undefined` (or omitted) → Creates single event with `domain: null`
+         */
+        domain?: (string | undefined | null)[];
     };
 }[keyof TContract['emits']];
 /**

package/dist/ArvoMachine/createMachine.d.ts

@@ -0,0 +1,208 @@
+import { type ArvoOrchestratorEventTypeGen, type InferVersionedArvoContract, type VersionedArvoContract } from 'arvo-core';
+import { type ActionFunction, type MachineConfig, type MachineContext, type MetaObject, type ParameterizedObject, type SetupTypes } from 'xstate';
+import type { z } from 'zod';
+import ArvoMachine from '.';
+import type { EnqueueArvoEventActionParam, ExtractOrchestratorType, InferServiceContract, ToParameterizedObject, ToProvidedActor } from './types';
+/**
+ * Establishes the foundation for creating Arvo-compatible state machines.
+ *
+ * This function configures the core elements of an Arvo state machine, including
+ * built-in actions like `enqueueArvoEvent`, and enforces Arvo-specific constraints
+ * to ensure compatibility with the Arvo event-driven system.
+ *
+ * @param param - Configuration object for the machine setup
+ * @returns An object containing the `createMachine` function
+ * @throws {Error} If 'actors', 'delays', or reserved action names are used in the configuration
+ *
+ * @description
+ * `setupArvoMachine` is a crucial function in the Arvo ecosystem, designed to create
+ * synchronous state machine orchestrations for Arvo's event-driven architecture.
+ * It builds upon XState, providing a tailored implementation that:
+ *
+ * 1. Enforces synchronous behavior to maintain predictable state transitions
+ * 3. Implements Arvo-specific constraints and features
+ *
+ * Key features:
+ * - Synchronous execution: Ensures deterministic behavior in event-driven systems
+ * - Built-in actions: Includes `enqueueArvoEvent` for Arvo event handling
+ * - Constraint checking: Prevents usage of asynchronous features like 'actors' or 'delays'
+ *
+ * @remarks
+ * While `setupArvoMachine` is based on XState's `setup` and `createMachine` functions,
+ * it includes Arvo-specific modifications and restrictions. For a deeper understanding
+ * of the underlying XState concepts, refer to the official XState documentation:
+ * - XState setup: https://stately.ai/docs/setup
+ * - XState createMachine: https://stately.ai/docs/machines
+ *
+ * @example
+ * Here's a comprehensive example demonstrating how to use `setupArvoMachine`:
+ *
+ * ```typescript
+ * import { setupArvoMachine } from 'arvo-xstate'
+ * import { createArvoOrchestratorContract, ArvoErrorSchema, createArvoContract } from 'arvo-core'
+ * import { z } from 'zod'
+ *
+ * // Define the LLM orchestrator contract
+ * const llmContract = createArvoOrchestratorContract({
+ *   uri: `#/orchestrators/llm/`,
+ *   type: 'llm',
+ *   versions: {
+ *     '0.0.1': {
+ *       init: z.object({
+ *         request: z.string(),
+ *         llm: z.enum(['gpt-4', 'gpt-4o']),
+ *       }),
+ *       complete: z.object({
+ *         response: z.string(),
+ *       })
+ *     }
+ *   }
+ * })
+ *
+ * // Define the OpenAI service contract
+ * const openAiContract = createArvoContract({
+ *   uri: `#/services/openai`,
+ *   type: 'com.openai.completions',
+ *   versions: {
+ *     '0.0.1': {
+ *       accepts: z.object({
+ *         request: z.string()
+ *       }),
+ *       emits: {
+ *         'evt.openai.completions.success': z.object({
+ *           response: z.string(),
+ *         })
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * const machineId = 'machineV100'
+ *
+ * // Set up the Arvo machine
+ * const llmMachine = setupArvoMachine({
+ *   contracts: {
+ *     self: llmContract.version('0.0.1'),
+ *     services: {
+ *       openAiContract.version('0.0.1'),
+ *     }
+ *   },
+ *   types: {
+ *     context: {} as {
+ *       request: string,
+ *       llm: string,
+ *       response: string | null,
+ *       errors: z.infer<typeof ArvoErrorSchema>[]
+ *     },
+ *     tags: {} as 'pending' | 'success' | 'error',
+ *   },
+ *   actions: {
+ *     log: ({context, event}) => console.log({context, event})
+ *   },
+ *   guards: {
+ *     isValid: ({context, event}) => Boolean(context.request)
+ *   }
+ * }).createMachine({
+ *   id: machineId,
+ *   context: ({input}) => ({
+ *     request: input.request,
+ *     llm: input.llm,
+ *     response: null,
+ *     errors: [],
+ *   }),
+ *   initial: 'validate',
+ *   states: {
+ *     validate: {
+ *       always: [
+ *         {
+ *           guard: 'isValid',
+ *           target: 'llm',
+ *         },
+ *         {
+ *           target: 'error',
+ *         }
+ *       ]
+ *     },
+ *     llm: {
+ *       entry: [
+ *         {
+ *           type: 'log',
+ *         },
+ *         emit(({context}) => ({
+ *           type: 'com.openai.completions',
+ *           data: {
+ *             request: context.request,
+ *           },
+ *         }))
+ *       ],
+ *       on: {
+ *         'evt.openai.completions.success': {
+ *           actions: [
+ *             assign({response: ({event}) => event.response})
+ *           ],
+ *           target: 'done'
+ *         },
+ *         'sys.com.openai.completions.error': {
+ *           actions: [
+ *             assign({errors: ({context, event}) => [...context.errors, event.body]})
+ *           ],
+ *           target: 'error'
+ *         }
+ *       }
+ *     },
+ *     done: {
+ *       type: 'final'
+ *     },
+ *     error: {
+ *       type: 'final'
+ *     },
+ *   }
+ * });
+ * ```
+ *
+ * This example demonstrates:
+ * 1. Defining Arvo contracts for the orchestrator and a service
+ * 2. Setting up an Arvo machine with contracts, types, actions, and guards
+ * 3. Creating a machine with states for validation, LLM interaction, and error handling
+ * 4. Using XState features like `emit` bound with Arvo contracts for event emitting and event handling via transitions
+ */
+export declare function setupArvoMachine<TContext extends MachineContext, TSelfContract extends VersionedArvoContract<any, any>, TServiceContracts extends Record<string, VersionedArvoContract<any, any>>, TActions extends Record<string, ParameterizedObject['params'] | undefined> = {}, TGuards extends Record<string, ParameterizedObject['params'] | undefined> = {}, TTag extends string = string, TMeta extends MetaObject = MetaObject>(param: {
+    schemas?: unknown;
+    contracts: {
+        self: TSelfContract;
+        services: TServiceContracts;
+    };
+    types?: Omit<SetupTypes<TContext, InferServiceContract<TServiceContracts>['events'], {}, TTag, InferVersionedArvoContract<TSelfContract>['accepts']['data'], InferVersionedArvoContract<TSelfContract>['emits'][ReturnType<typeof ArvoOrchestratorEventTypeGen.complete<ExtractOrchestratorType<TSelfContract['accepts']['type']>>>]['data'], InferServiceContract<TServiceContracts>['emitted'], TMeta>, 'input' | 'output' | 'children' | 'emitted'>;
+    actions?: {
+        [K in keyof TActions]: ActionFunction<TContext, InferServiceContract<TServiceContracts>['events'], InferServiceContract<TServiceContracts>['events'], TActions[K], never, ToParameterizedObject<TActions>, ToParameterizedObject<TGuards>, never, InferServiceContract<TServiceContracts>['emitted']>;
+    };
+    guards?: {
+        [K in keyof TGuards]: (args: {
+            context: TContext;
+            event: InferServiceContract<TServiceContracts>['events'];
+        }, params: TGuards[K]) => boolean;
+    };
+}): {
+    createMachine: <const TConfig extends MachineConfig<TContext, InferServiceContract<TServiceContracts>["events"], ToProvidedActor<{}, {}>, ToParameterizedObject<TActions & {
+        enqueueArvoEvent: EnqueueArvoEventActionParam;
+    }>, ToParameterizedObject<TGuards>, never, TTag, InferVersionedArvoContract<TSelfContract>["accepts"], z.input<TSelfContract["emits"][ReturnType<typeof ArvoOrchestratorEventTypeGen.complete<ExtractOrchestratorType<TSelfContract["accepts"]["type"]>>>]>, InferServiceContract<TServiceContracts>["emitted"], TMeta>>(config: TConfig & {
+        id: string;
+        version?: TSelfContract["version"];
+    }) => ArvoMachine<string, TSelfContract["version"], TSelfContract, TServiceContracts, import("xstate").StateMachine<TContext, { [K in keyof TServiceContracts]: import("./types").InferEmittableEventsFromVersionedArvoContract<TServiceContracts[K]>; }[keyof TServiceContracts], {}, never, import("xstate").IsNever<TActions & {
+        enqueueArvoEvent: EnqueueArvoEventActionParam;
+    }> extends true ? never : import("xstate").Values<{ [K_1 in (keyof TActions & string) | "enqueueArvoEvent"]: {
+        type: K_1;
+        params: (TActions & {
+            enqueueArvoEvent: EnqueueArvoEventActionParam;
+        })[K_1];
+    }; }>, import("xstate").IsNever<TGuards> extends true ? never : import("xstate").Values<{ [K_2 in keyof TGuards & string]: {
+        type: K_2;
+        params: TGuards[K_2];
+    }; }>, never, {} | {
+        [x: string]: {} | any | {
+            [x: string]: {} | any | any;
+        };
+    } | {
+        [x: string]: {} | any | any;
+    }, TTag, TSelfContract["accepts"]["schema"]["_output"], { [K_3 in string & keyof TSelfContract["emits"]]: import("arvo-core").InferArvoEvent<import("arvo-core").ArvoEvent<TSelfContract["emits"][K_3]["_output"], Record<string, any>, K_3>>; }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], { [K_4 in keyof TServiceContracts]: EnqueueArvoEventActionParam<z.input<TServiceContracts[K_4]["accepts"]["schema"]>, TServiceContracts[K_4]["accepts"]["type"], Record<string, string | number | boolean | null>>; }[keyof TServiceContracts], TMeta, any>>;
+};

package/dist/ArvoMachine/createMachine.js

@@ -0,0 +1,283 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+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));
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupArvoMachine = setupArvoMachine;
+var arvo_core_1 = require("arvo-core");
+var xstate_1 = require("xstate");
+var _1 = __importDefault(require("."));
+var object_1 = require("../utils/object");
+var utils_1 = require("./utils");
+var uuid_1 = require("uuid");
+/**
+ * Establishes the foundation for creating Arvo-compatible state machines.
+ *
+ * This function configures the core elements of an Arvo state machine, including
+ * built-in actions like `enqueueArvoEvent`, and enforces Arvo-specific constraints
+ * to ensure compatibility with the Arvo event-driven system.
+ *
+ * @param param - Configuration object for the machine setup
+ * @returns An object containing the `createMachine` function
+ * @throws {Error} If 'actors', 'delays', or reserved action names are used in the configuration
+ *
+ * @description
+ * `setupArvoMachine` is a crucial function in the Arvo ecosystem, designed to create
+ * synchronous state machine orchestrations for Arvo's event-driven architecture.
+ * It builds upon XState, providing a tailored implementation that:
+ *
+ * 1. Enforces synchronous behavior to maintain predictable state transitions
+ * 3. Implements Arvo-specific constraints and features
+ *
+ * Key features:
+ * - Synchronous execution: Ensures deterministic behavior in event-driven systems
+ * - Built-in actions: Includes `enqueueArvoEvent` for Arvo event handling
+ * - Constraint checking: Prevents usage of asynchronous features like 'actors' or 'delays'
+ *
+ * @remarks
+ * While `setupArvoMachine` is based on XState's `setup` and `createMachine` functions,
+ * it includes Arvo-specific modifications and restrictions. For a deeper understanding
+ * of the underlying XState concepts, refer to the official XState documentation:
+ * - XState setup: https://stately.ai/docs/setup
+ * - XState createMachine: https://stately.ai/docs/machines
+ *
+ * @example
+ * Here's a comprehensive example demonstrating how to use `setupArvoMachine`:
+ *
+ * ```typescript
+ * import { setupArvoMachine } from 'arvo-xstate'
+ * import { createArvoOrchestratorContract, ArvoErrorSchema, createArvoContract } from 'arvo-core'
+ * import { z } from 'zod'
+ *
+ * // Define the LLM orchestrator contract
+ * const llmContract = createArvoOrchestratorContract({
+ *   uri: `#/orchestrators/llm/`,
+ *   type: 'llm',
+ *   versions: {
+ *     '0.0.1': {
+ *       init: z.object({
+ *         request: z.string(),
+ *         llm: z.enum(['gpt-4', 'gpt-4o']),
+ *       }),
+ *       complete: z.object({
+ *         response: z.string(),
+ *       })
+ *     }
+ *   }
+ * })
+ *
+ * // Define the OpenAI service contract
+ * const openAiContract = createArvoContract({
+ *   uri: `#/services/openai`,
+ *   type: 'com.openai.completions',
+ *   versions: {
+ *     '0.0.1': {
+ *       accepts: z.object({
+ *         request: z.string()
+ *       }),
+ *       emits: {
+ *         'evt.openai.completions.success': z.object({
+ *           response: z.string(),
+ *         })
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * const machineId = 'machineV100'
+ *
+ * // Set up the Arvo machine
+ * const llmMachine = setupArvoMachine({
+ *   contracts: {
+ *     self: llmContract.version('0.0.1'),
+ *     services: {
+ *       openAiContract.version('0.0.1'),
+ *     }
+ *   },
+ *   types: {
+ *     context: {} as {
+ *       request: string,
+ *       llm: string,
+ *       response: string | null,
+ *       errors: z.infer<typeof ArvoErrorSchema>[]
+ *     },
+ *     tags: {} as 'pending' | 'success' | 'error',
+ *   },
+ *   actions: {
+ *     log: ({context, event}) => console.log({context, event})
+ *   },
+ *   guards: {
+ *     isValid: ({context, event}) => Boolean(context.request)
+ *   }
+ * }).createMachine({
+ *   id: machineId,
+ *   context: ({input}) => ({
+ *     request: input.request,
+ *     llm: input.llm,
+ *     response: null,
+ *     errors: [],
+ *   }),
+ *   initial: 'validate',
+ *   states: {
+ *     validate: {
+ *       always: [
+ *         {
+ *           guard: 'isValid',
+ *           target: 'llm',
+ *         },
+ *         {
+ *           target: 'error',
+ *         }
+ *       ]
+ *     },
+ *     llm: {
+ *       entry: [
+ *         {
+ *           type: 'log',
+ *         },
+ *         emit(({context}) => ({
+ *           type: 'com.openai.completions',
+ *           data: {
+ *             request: context.request,
+ *           },
+ *         }))
+ *       ],
+ *       on: {
+ *         'evt.openai.completions.success': {
+ *           actions: [
+ *             assign({response: ({event}) => event.response})
+ *           ],
+ *           target: 'done'
+ *         },
+ *         'sys.com.openai.completions.error': {
+ *           actions: [
+ *             assign({errors: ({context, event}) => [...context.errors, event.body]})
+ *           ],
+ *           target: 'error'
+ *         }
+ *       }
+ *     },
+ *     done: {
+ *       type: 'final'
+ *     },
+ *     error: {
+ *       type: 'final'
+ *     },
+ *   }
+ * });
+ * ```
+ *
+ * This example demonstrates:
+ * 1. Defining Arvo contracts for the orchestrator and a service
+ * 2. Setting up an Arvo machine with contracts, types, actions, and guards
+ * 3. Creating a machine with states for validation, LLM interaction, and error handling
+ * 4. Using XState features like `emit` bound with Arvo contracts for event emitting and event handling via transitions
+ */
+function setupArvoMachine(param) {
+    var _a;
+    var _b, _c;
+    var createConfigErrorMessage = function (type) {
+        return (0, arvo_core_1.cleanString)("\n      Configuration Error: '".concat(type, "' not supported in Arvo machines\n      \n      Arvo machines do not support XState ").concat(type === 'actor' ? 'actors' : 'delay transitions', " as they introduce asynchronous behavior.\n      \n      To fix:\n      1. Remove the '").concat(type, "' configuration\n      2. Use Arvo's event-driven patterns instead for asynchronous operations\n    "));
+    };
+    if (param.actors) {
+        throw new Error(createConfigErrorMessage('actor'));
+    }
+    if (param.delays) {
+        throw new Error(createConfigErrorMessage('delays'));
+    }
+    if ((_b = param.actions) === null || _b === void 0 ? void 0 : _b.enqueueArvoEvent) {
+        throw new Error((0, arvo_core_1.cleanString)("\n        Configuration Error: Reserved action name 'enqueueArvoEvent'\n        \n        'enqueueArvoEvent' is an internal Arvo system action and cannot be overridden.\n        \n        To fix: Use a different name for your action, such as:\n        - 'queueCustomEvent'\n        - 'scheduleEvent'\n        - 'dispatchEvent'\n      "));
+    }
+    var __areServiceContractsUnique = (0, utils_1.areServiceContractsUnique)(param.contracts.services);
+    if (!__areServiceContractsUnique.result) {
+        throw new Error("The service contracts must have unique URIs. Multiple versions of the same contract are not allow. The contracts '".concat(__areServiceContractsUnique.keys[0], "' and '").concat(__areServiceContractsUnique.keys[1], "' have the same URI '").concat(__areServiceContractsUnique.contractUri, "'"));
+    }
+    var __checkIfSelfIsAService = (0, utils_1.areServiceContractsUnique)(__assign(__assign({}, param.contracts.services), (_a = {}, _a[(0, uuid_1.v4)()] = param.contracts.self, _a)));
+    if (!__checkIfSelfIsAService.result) {
+        throw new Error("Circular dependency detected: Machine with URI '".concat(param.contracts.self.uri, "' is registered as service '").concat(__checkIfSelfIsAService.keys[1], "'. Self-referential services create execution loops and are prohibited."));
+    }
+    var combinedActions = __assign(__assign({}, ((_c = param.actions) !== null && _c !== void 0 ? _c : {})), { enqueueArvoEvent: (0, xstate_1.assign)(function (_a, param) {
+            var _b, _c, _d, _e, _f;
+            var context = _a.context;
+            return (__assign(__assign({}, (context !== null && context !== void 0 ? context : {})), { arvo$$: __assign(__assign({}, ((_b = context === null || context === void 0 ? void 0 : context.arvo$$) !== null && _b !== void 0 ? _b : {})), { volatile$$: __assign(__assign({}, ((_d = (_c = context === null || context === void 0 ? void 0 : context.arvo$$) === null || _c === void 0 ? void 0 : _c.volatile$$) !== null && _d !== void 0 ? _d : {})), { eventQueue$$: __spreadArray(__spreadArray([], (((_f = (_e = context === null || context === void 0 ? void 0 : context.arvo$$) === null || _e === void 0 ? void 0 : _e.volatile$$) === null || _f === void 0 ? void 0 : _f.eventQueue$$) || []), true), [param], false) }) }) }));
+        }) });
+    // Call the original setup function with modified parameters
+    var systemSetup = (0, xstate_1.setup)({
+        schemas: param.schemas,
+        types: param.types,
+        guards: param.guards,
+        actions: combinedActions,
+    });
+    /**
+     * Creates an Arvo-compatible XState machine.
+     *
+     * @param config - The configuration object for the machine
+     * @returns An ArvoMachine instance
+     *
+     * @throws Error if 'invoke' or 'after' configurations are used
+     *
+     * @remarks
+     * This function creates a state machine based on the provided configuration.
+     * It performs additional checks to ensure the machine adheres to Arvo's constraints,
+     * such as disallowing 'invoke' and 'after' configurations which could introduce
+     * asynchronous behavior.
+     * ```
+     */
+    var createMachine = function (config) {
+        var _a, _b;
+        var machineVersion = (_a = config.version) !== null && _a !== void 0 ? _a : param.contracts.self.version;
+        if (machineVersion !== param.contracts.self.version) {
+            throw new Error("Version mismatch: Machine version must be '".concat(param.contracts.self.version, "' or undefined, received '").concat(config.version, "'"));
+        }
+        var createConfigErrorMessage = function (type, path) {
+            var location = path.join(' > ');
+            if (type === 'invoke') {
+                return (0, arvo_core_1.cleanString)("\n          Configuration Error: 'invoke' not supported\n          \n          Location: ".concat(location, "\n          \n          Arvo machines do not support XState invocations as they introduce asynchronous behavior.\n          \n          To fix: Replace 'invoke' with Arvo event-driven patterns for asynchronous operations\n        "));
+            }
+            if (type === 'after') {
+                return (0, arvo_core_1.cleanString)("\n          Configuration Error: 'after' not supported\n          \n          Location: ".concat(location, "\n          \n          Arvo machines do not support delayed transitions as they introduce asynchronous behavior.\n          \n          To fix: Replace 'after' with Arvo event-driven patterns for time-based operations\n        "));
+            }
+            if (type === 'enqueueArvoEvent') {
+                return (0, arvo_core_1.cleanString)("\n          Configuration Error: Reserved action name 'enqueueArvoEvent'\n          \n          Location: ".concat(location, "\n          \n          'enqueueArvoEvent' is an internal Arvo system action and cannot be used in machine configurations.\n          \n          To fix: Use a different name for your action\n        "));
+            }
+        };
+        for (var _i = 0, _c = (0, object_1.getAllPaths)((_b = config.states) !== null && _b !== void 0 ? _b : {}); _i < _c.length; _i++) {
+            var item = _c[_i];
+            if (item.path.includes('invoke')) {
+                throw new Error(createConfigErrorMessage('invoke', item.path));
+            }
+            if (item.path.includes('after')) {
+                throw new Error(createConfigErrorMessage('after', item.path));
+            }
+            if (item.path.includes('enqueueArvoEvent')) {
+                throw new Error(createConfigErrorMessage('enqueueArvoEvent', item.path));
+            }
+        }
+        var machine = systemSetup.createMachine(__assign({}, config));
+        var hasParallelStates = (0, utils_1.detectParallelStates)(machine.config);
+        var hasMultipleNonSystemErrorEvents = Object.values(param.contracts.services).some(function (item) { return Object.keys(item.emits).length > 1; });
+        var requiresLocking = hasParallelStates || hasMultipleNonSystemErrorEvents;
+        return new _1.default(config.id, machineVersion, param.contracts, machine, requiresLocking);
+    };
+    return { createMachine: createMachine };
+}

package/dist/ArvoMachine/index.d.ts

@@ -0,0 +1,93 @@
+import { type ArvoContract, type ArvoEvent, type ArvoOrchestratorContract, type ArvoSemanticVersion, type VersionedArvoContract } from 'arvo-core';
+import type { AnyActorLogic } from 'xstate';
+import type { z } from 'zod';
+/**
+ * Represents an ArvoMachine object that can be consumed by an Arvo orchestrator.
+ * ArvoMachine encapsulates the logic and metadata required for an Arvo-compatible
+ * state machine. It combines XState's actor logic with Arvo-specific contracts
+ * and versioning information.
+ *
+ * @remarks
+ * It is strongly recommended to use `setupArvoMachine(...).createMachine(...)`
+ * instead of creating this object directly. The setup function provides additional
+ * type safety and validation that helps prevent runtime errors.
+ */
+export default class ArvoMachine<TId extends string, TVersion extends ArvoSemanticVersion, TSelfContract extends VersionedArvoContract<ArvoOrchestratorContract, TVersion>, TServiceContract extends Record<string, VersionedArvoContract<ArvoContract, ArvoSemanticVersion>>, TLogic extends AnyActorLogic> {
+    readonly id: TId;
+    readonly version: TVersion;
+    readonly contracts: {
+        self: TSelfContract;
+        services: TServiceContract;
+    };
+    readonly logic: TLogic;
+    readonly requiresResourceLocking: boolean;
+    /**
+     * Creates a new ArvoMachine instance.
+     *
+     * @param id - A unique identifier for the machine. This ID must be unique within
+     *            the scope of an orchestrator and is used for routing and logging.
+     *
+     * @param version - The semantic version of the machine. Must follow semver format
+     *                and match the version specified in the contract.
+     *
+     * @param contracts - Configuration object containing contract definitions
+     * @param contracts.self - The contract defining this machine's interface and capabilities
+     * @param contracts.services - Record of contracts for services this machine can interact with
+     *
+     * @param logic - The XState actor logic that defines the machine's behavior,
+     *               including states, transitions, and actions.
+     * @param [requiresResourceLocking] - Optional flag indicating if the machine needs distributed locks.
+     *                                    False when machine has no parallel states and executes sequentially.
+     *                                    Defaults to true.
+     *
+     * @throws {Error} When contracts are invalid or incompatible with the specified version
+     */
+    constructor(id: TId, version: TVersion, contracts: {
+        self: TSelfContract;
+        services: TServiceContract;
+    }, logic: TLogic, requiresResourceLocking?: boolean);
+    /**
+     * Gets the event type that this machine accepts, as defined in its contract.
+     */
+    get source(): TSelfContract['accepts']['type'];
+    /**
+     * Validates an event against the machine's contracts and data schemas.
+     * Performs validation for both self-contract events and service contract events.
+     *
+     * @param event - The event to validate
+     * @returns A validation result object:
+     *   - "VALID" - Event is valid and can be processed
+     *   - "CONTRACT_UNRESOLVED" - No matching contract found for the event
+     *   - "INVALID" - Event dataschema conflict with contract
+     *   - "INVALID_DATA" - Event data conflicts with contract
+     *
+     * @example
+     * ```typescript
+     * const result = machine.validateInput(event);
+     *  if (result.type === "VALID") {
+     *   // Process the event
+     * } else if (result.type === "INVALID") {
+     *   console.error(result.error);
+     * } else {
+     *   // Handle unresolved contract
+     * }
+     * ```
+     *
+     * @remarks
+     * The validation process includes:
+     * - Finding a matching contract (self or service)
+     * - Validating dataschema URI and version if present
+     * - Validating event data against the contract schema
+     */
+    validateInput(event: ArvoEvent): {
+        type: 'VALID';
+    } | {
+        type: 'CONTRACT_UNRESOLVED';
+    } | {
+        type: 'INVALID';
+        error: Error;
+    } | {
+        type: 'INVALID_DATA';
+        error: z.ZodError;
+    };
+}