arvo-event-handler 3.0.6 → 3.0.8

package/dist/ArvoOrchestrationUtils/handlerErrors.js

@@ -0,0 +1,184 @@
+"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 __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleOrchestrationErrors = exports.createSystemErrorEvents = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+var ArvoDomain_1 = require("../ArvoDomain");
+var errors_1 = require("../errors");
+var utils_1 = require("../utils");
+/**
+ * Creates system error events
+ */
+var createSystemErrorEvents = function (_a) {
+    var _b, _c, _d, _e;
+    var error = _a.error, event = _a.event, otelHeaders = _a.otelHeaders, orchestrationParentSubject = _a.orchestrationParentSubject, initEventId = _a.initEventId, selfContract = _a.selfContract, systemErrorDomain = _a.systemErrorDomain, executionunits = _a.executionunits, source = _a.source, domain = _a.domain;
+    // In case of none transaction errors like errors from
+    // the machine or the event creation etc, the are workflow
+    // error and shuold be handled by the workflow. Then are
+    // called system error and must be sent
+    // to the initiator. In as good of a format as possible
+    var parsedEventSubject = null;
+    try {
+        parsedEventSubject = arvo_core_1.ArvoOrchestrationSubject.parse(event.subject);
+    }
+    catch (e) {
+        (0, arvo_core_1.logToSpan)({
+            level: 'WARNING',
+            message: "Unable to parse event subject: ".concat(e.message),
+        });
+    }
+    var domainSets = new Set(systemErrorDomain
+        ? systemErrorDomain.map(function (item) {
+            return (0, ArvoDomain_1.resolveEventDomain)({
+                domainToResolve: item,
+                handlerSelfContract: selfContract,
+                eventContract: selfContract,
+                triggeringEvent: event,
+            });
+        })
+        : [event.domain, domain, null]);
+    var result = [];
+    for (var _i = 0, _f = Array.from(domainSets); _i < _f.length; _i++) {
+        var _dom = _f[_i];
+        result.push((0, arvo_core_1.createArvoOrchestratorEventFactory)(selfContract).systemError({
+            source: source,
+            // If the initiator of the workflow exist then match the
+            // subject so that it can incorporate it in its state. If
+            // parent does not exist then this is the root workflow so
+            // use its own subject
+            subject: orchestrationParentSubject !== null && orchestrationParentSubject !== void 0 ? orchestrationParentSubject : event.subject,
+            // The system error must always go back to
+            // the source which initiated it
+            to: (_b = parsedEventSubject === null || parsedEventSubject === void 0 ? void 0 : parsedEventSubject.execution.initiator) !== null && _b !== void 0 ? _b : event.source,
+            error: error,
+            traceparent: (_c = otelHeaders.traceparent) !== null && _c !== void 0 ? _c : undefined,
+            tracestate: (_d = otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined,
+            accesscontrol: (_e = event.accesscontrol) !== null && _e !== void 0 ? _e : undefined,
+            executionunits: executionunits,
+            // If there is initEventID then use that.
+            // Otherwise, use event id. If the error is in init event
+            // then it will be the same as initEventId. Otherwise,
+            // we still would know what cause this error
+            parentid: initEventId !== null && initEventId !== void 0 ? initEventId : event.id,
+            domain: _dom,
+        }));
+    }
+    return result;
+};
+exports.createSystemErrorEvents = createSystemErrorEvents;
+var handleOrchestrationErrors = function (_handlerType, param, span) { return __awaiter(void 0, void 0, void 0, function () {
+    var handlerType, error, errorEvents, _i, _a, _b, errEvtIdx, errEvt, _c, _d, _e, key, value;
+    return __generator(this, function (_f) {
+        switch (_f.label) {
+            case 0:
+                handlerType = {
+                    orchestrator: 'ArvoOrchestrator',
+                    resumable: 'ArvoResumable',
+                }[_handlerType];
+                error = (0, utils_1.isError)(param.error)
+                    ? param.error
+                    : new errors_1.ExecutionViolation("Non-Error object thrown during machine execution: ".concat(typeof param.error, ". This indicates a serious implementation flaw."));
+                (0, arvo_core_1.exceptionToSpan)(error, span);
+                span.setStatus({
+                    code: api_1.SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                // Don't persist state on a violation
+                //
+                // A violation means that there is something
+                // wrong in the state persitance or it is a
+                // error which will be handled outside the
+                // Arvo mechanism. So, it makes sense that it
+                // does not impact the state. The violations
+                // can be used to trigger retries as well
+                if ((0, arvo_core_1.isViolationError)(error)) {
+                    (0, arvo_core_1.logToSpan)({
+                        level: 'CRITICAL',
+                        message: "".concat(handlerType || 'Arvo orchestration handler', " violation error: ").concat(error.message),
+                    });
+                    return [2 /*return*/, {
+                            errorToThrow: error,
+                            events: null,
+                        }];
+                }
+                return [4 /*yield*/, param.syncEventResource
+                        .persistState(param.event, {
+                        executionStatus: 'failure',
+                        subject: param.event.subject,
+                        error: param.error,
+                    }, null, span)
+                        .catch(function (e) {
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'CRITICAL',
+                            message: "Error in orchestrator persisting the failure state: ".concat(e.message),
+                        });
+                    })];
+            case 1:
+                _f.sent();
+                (0, arvo_core_1.logToSpan)({
+                    level: 'ERROR',
+                    message: "".concat(handlerType || 'Arvo orchestration handler', " execution failed: ").concat(error.message),
+                });
+                errorEvents = (0, exports.createSystemErrorEvents)(__assign(__assign({}, param), { error: error }));
+                for (_i = 0, _a = Object.entries(errorEvents); _i < _a.length; _i++) {
+                    _b = _a[_i], errEvtIdx = _b[0], errEvt = _b[1];
+                    for (_c = 0, _d = Object.entries(errEvt.otelAttributes); _c < _d.length; _c++) {
+                        _e = _d[_c], key = _e[0], value = _e[1];
+                        span.setAttribute("to_emit.".concat(errEvtIdx, ".").concat(key), value);
+                    }
+                }
+                return [2 /*return*/, {
+                        errorToThrow: null,
+                        events: errorEvents,
+                    }];
+        }
+    });
+}); };
+exports.handleOrchestrationErrors = handleOrchestrationErrors;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionState.d.ts

@@ -0,0 +1,11 @@
+export declare const OrchestrationExecutionStatus: {
+    readonly FAILURE: "failure";
+    readonly NORMAL: "normal";
+};
+export type OrchestrationExecutionMemoryRecord<T extends Record<string, unknown>> = (T & {
+    executionStatus: typeof OrchestrationExecutionStatus.NORMAL;
+}) | (Partial<T> & {
+    executionStatus: typeof OrchestrationExecutionStatus.FAILURE;
+    error: Error;
+    subject: string;
+});

package/dist/ArvoOrchestrationUtils/orchestrationExecutionState.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrchestrationExecutionStatus = void 0;
+exports.OrchestrationExecutionStatus = {
+    FAILURE: 'failure',
+    NORMAL: 'normal',
+};

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

@@ -0,0 +1,8 @@
+import type { Span } from '@opentelemetry/api';
+import { type ArvoEvent } from 'arvo-core';
+import type { SyncEventResource } from '../../SyncEventResource';
+import type { AcquiredLockStatusType } from '../../SyncEventResource/types';
+/**
+ * Handles lock acquisition with proper error handling
+ */
+export declare const acquireLockWithValidation: (syncEventResource: SyncEventResource<Record<string, any>>, event: ArvoEvent, span: Span) => Promise<AcquiredLockStatusType>;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/acquireLockWithValidation.js

@@ -0,0 +1,69 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireLockWithValidation = void 0;
+var arvo_core_1 = require("arvo-core");
+var error_1 = require("../error");
+/**
+ * Handles lock acquisition with proper error handling
+ */
+var acquireLockWithValidation = function (syncEventResource, event, span) { return __awaiter(void 0, void 0, void 0, function () {
+    var acquiredLock;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: return [4 /*yield*/, syncEventResource.acquireLock(event, span)];
+            case 1:
+                acquiredLock = _a.sent();
+                if (acquiredLock === 'NOT_ACQUIRED') {
+                    throw new error_1.TransactionViolation({
+                        cause: error_1.TransactionViolationCause.LOCK_UNACQUIRED,
+                        message: 'Lock acquisition denied - Unable to obtain exclusive access to event processing',
+                        initiatingEvent: event,
+                    });
+                }
+                if (acquiredLock === 'ACQUIRED') {
+                    (0, arvo_core_1.logToSpan)({
+                        level: 'INFO',
+                        message: "This execution acquired lock at resource '".concat(event.subject, "'"),
+                    }, span);
+                }
+                return [2 /*return*/, acquiredLock];
+        }
+    });
+}); };
+exports.acquireLockWithValidation = acquireLockWithValidation;

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

@@ -0,0 +1,40 @@
+import { type Span } from '@opentelemetry/api';
+import { type ArvoEvent, type ArvoOrchestrationSubjectContent, type ArvoOrchestratorContract, type ArvoSemanticVersion, type OpenTelemetryHeaders, type VersionedArvoContract } from 'arvo-core';
+import type IArvoEventHandler from '../../IArvoEventHandler';
+import type { SyncEventResource } from '../../SyncEventResource';
+import type { ArvoEventHandlerOpenTelemetryOptions } from '../../types';
+import type { OrchestrationExecutionMemoryRecord } from '../orchestrationExecutionState';
+import type { ArvoOrchestrationHandlerType } from '../types';
+export type OrchestrationExecutionContext<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = {
+    event: ArvoEvent;
+    opentelemetry: ArvoEventHandlerOpenTelemetryOptions;
+    spanName: string;
+    source: string;
+    syncEventResource: SyncEventResource<TState>;
+    executionunits: number;
+    systemErrorDomain?: (string | null)[];
+    selfContract: VersionedArvoContract<ArvoOrchestratorContract, ArvoSemanticVersion>;
+    domain: string | null;
+    _handlerType: ArvoOrchestrationHandlerType;
+};
+export type CoreExecutionFn<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = (params: {
+    span: any;
+    otelHeaders: OpenTelemetryHeaders;
+    orchestrationParentSubject: string | null;
+    initEventId: string;
+    parsedEventSubject: ArvoOrchestrationSubjectContent;
+    state: TState | null;
+    _handlerType: ArvoOrchestrationHandlerType;
+}) => Promise<{
+    emittables: ArvoEvent[];
+    newState: TState;
+}>;
+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
+ */
+export declare const executeWithOrchestrationWrapper: <TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>>({ event, opentelemetry, spanName, source, syncEventResource, executionunits, systemErrorDomain, selfContract, domain, _handlerType, }: OrchestrationExecutionContext<TState>, coreExecutionFn: CoreExecutionFn<TState>) => Promise<Awaited<ReturnType<IArvoEventHandler["execute"]>>>;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/index.js

@@ -0,0 +1,228 @@
+"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 __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWithOrchestrationWrapper = exports.returnEventsWithLogging = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+var handlerErrors_1 = require("../handlerErrors");
+var acquireLockWithValidation_1 = require("./acquireLockWithValidation");
+var validateAndParseSubject_1 = require("./validateAndParseSubject");
+var returnEventsWithLogging = function (param, span) {
+    var _a, _b;
+    (0, arvo_core_1.logToSpan)({
+        level: 'INFO',
+        message: "Execution completed with issues and emitted ".concat((_b = (_a = param.events) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0, " events"),
+    }, span);
+    return param;
+};
+exports.returnEventsWithLogging = returnEventsWithLogging;
+/**
+ * Wraps orchestration execution with common infrastructure:
+ * - OpenTelemetry span management
+ * - Lock acquisition and release
+ * - State management
+ * - Error handling and system error generation
+ */
+var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return __awaiter(void 0, [_a, coreExecutionFn_1], void 0, function (_b, coreExecutionFn) {
+    var _c;
+    var event = _b.event, opentelemetry = _b.opentelemetry, spanName = _b.spanName, source = _b.source, syncEventResource = _b.syncEventResource, executionunits = _b.executionunits, systemErrorDomain = _b.systemErrorDomain, selfContract = _b.selfContract, domain = _b.domain, _handlerType = _b._handlerType;
+    return __generator(this, function (_d) {
+        switch (_d.label) {
+            case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+                    name: spanName,
+                    spanOptions: {
+                        kind: api_1.SpanKind.PRODUCER,
+                        attributes: __assign((_c = {}, _c[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = arvo_core_1.ArvoExecutionSpanKind.ORCHESTRATOR, _c[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = arvo_core_1.OpenInferenceSpanKind.CHAIN, _c), Object.fromEntries(Object.entries(event.otelAttributes).map(function (_a) {
+                            var key = _a[0], value = _a[1];
+                            return ["to_process.0.".concat(key), value];
+                        }))),
+                    },
+                    context: opentelemetry.inheritFrom === 'EVENT'
+                        ? {
+                            inheritFrom: 'TRACE_HEADERS',
+                            traceHeaders: {
+                                traceparent: event.traceparent,
+                                tracestate: event.tracestate,
+                            },
+                        }
+                        : {
+                            inheritFrom: 'CONTEXT',
+                            context: api_1.context.active(),
+                        },
+                    disableSpanManagement: true,
+                    fn: function (span) { return __awaiter(void 0, void 0, void 0, function () {
+                        var otelHeaders, orchestrationParentSubject, initEventId, acquiredLock, parsedEventSubject, state, _a, emittables, newState, i, _i, _b, _c, key, value, error_1, _d, errorToThrow, errorEvents;
+                        var _e, _f, _g, _h;
+                        return __generator(this, function (_j) {
+                            switch (_j.label) {
+                                case 0:
+                                    (0, arvo_core_1.logToSpan)({
+                                        level: 'INFO',
+                                        message: "Starting execution for ".concat(event.type, " on subject ").concat(event.subject),
+                                    }, span);
+                                    otelHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
+                                    orchestrationParentSubject = null;
+                                    initEventId = null;
+                                    acquiredLock = null;
+                                    _j.label = 1;
+                                case 1:
+                                    _j.trys.push([1, 6, 8, 10]);
+                                    parsedEventSubject = (0, validateAndParseSubject_1.validateAndParseSubject)(event, source, syncEventResource, span, 'orchestrator');
+                                    if (!parsedEventSubject) {
+                                        return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: [] }, span)];
+                                    }
+                                    return [4 /*yield*/, (0, acquireLockWithValidation_1.acquireLockWithValidation)(syncEventResource, event, span)];
+                                case 2:
+                                    // Lock acquisition
+                                    acquiredLock = _j.sent();
+                                    return [4 /*yield*/, syncEventResource.acquireState(event, span)];
+                                case 3:
+                                    state = _j.sent();
+                                    if ((state === null || state === void 0 ? void 0 : state.executionStatus) === 'failure') {
+                                        (0, arvo_core_1.logToSpan)({
+                                            level: 'WARNING',
+                                            message: "The orchestration has failed in a previous event. Ignoring event id: ".concat(event.id, " with event subject: ").concat(event.subject),
+                                        }, span);
+                                        return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: [] }, span)];
+                                    }
+                                    orchestrationParentSubject = (_e = state === null || state === void 0 ? void 0 : state.parentSubject) !== null && _e !== void 0 ? _e : null;
+                                    initEventId = (_f = state === null || state === void 0 ? void 0 : state.initEventId) !== null && _f !== void 0 ? _f : null;
+                                    if (!state) {
+                                        (0, arvo_core_1.logToSpan)({
+                                            level: 'INFO',
+                                            message: "Initializing new execution state for subject: ".concat(event.subject),
+                                        });
+                                        if (event.type !== source) {
+                                            (0, arvo_core_1.logToSpan)({
+                                                level: 'WARNING',
+                                                message: "Invalid initialization event detected. Expected type '".concat(source, "' but received '").concat(event.type, "'."),
+                                            });
+                                            return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: [] }, span)];
+                                        }
+                                    }
+                                    else {
+                                        (0, arvo_core_1.logToSpan)({
+                                            level: 'INFO',
+                                            message: "Resuming execution with existing state for subject: ".concat(event.subject),
+                                        });
+                                    }
+                                    // Extract parent subject from init event if applicable
+                                    if (event.type === source) {
+                                        orchestrationParentSubject = (_h = (_g = event === null || event === void 0 ? void 0 : event.data) === null || _g === void 0 ? void 0 : _g.parentSubject$$) !== null && _h !== void 0 ? _h : null;
+                                    }
+                                    return [4 /*yield*/, coreExecutionFn({
+                                            span: span,
+                                            otelHeaders: otelHeaders,
+                                            orchestrationParentSubject: orchestrationParentSubject,
+                                            initEventId: initEventId !== null && initEventId !== void 0 ? initEventId : event.id,
+                                            parsedEventSubject: parsedEventSubject,
+                                            state: state,
+                                            _handlerType: _handlerType,
+                                        })];
+                                case 4:
+                                    _a = _j.sent(), emittables = _a.emittables, newState = _a.newState;
+                                    span.setAttribute("arvo.".concat(_handlerType, ".execution.status"), newState.executionStatus);
+                                    // Add OpenTelemetry attributes for emitted events
+                                    for (i = 0; i < emittables.length; i++) {
+                                        for (_i = 0, _b = Object.entries(emittables[i].otelAttributes); _i < _b.length; _i++) {
+                                            _c = _b[_i], key = _c[0], value = _c[1];
+                                            span.setAttribute("to_emit.".concat(i, ".").concat(key), value);
+                                        }
+                                    }
+                                    // Persist state
+                                    return [4 /*yield*/, syncEventResource.persistState(event, newState, state, span)];
+                                case 5:
+                                    // Persist state
+                                    _j.sent();
+                                    (0, arvo_core_1.logToSpan)({
+                                        level: 'INFO',
+                                        message: "State update persisted in memory for subject ".concat(event.subject),
+                                    });
+                                    (0, arvo_core_1.logToSpan)({
+                                        level: 'INFO',
+                                        message: "Execution successfully completed and emitted ".concat(emittables.length, " events"),
+                                    });
+                                    return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: emittables }, span)];
+                                case 6:
+                                    error_1 = _j.sent();
+                                    return [4 /*yield*/, (0, handlerErrors_1.handleOrchestrationErrors)(_handlerType, {
+                                            error: error_1,
+                                            event: event,
+                                            otelHeaders: otelHeaders,
+                                            orchestrationParentSubject: orchestrationParentSubject,
+                                            initEventId: initEventId,
+                                            selfContract: selfContract,
+                                            systemErrorDomain: systemErrorDomain,
+                                            executionunits: executionunits,
+                                            source: source,
+                                            domain: domain,
+                                            syncEventResource: syncEventResource,
+                                        }, span)];
+                                case 7:
+                                    _d = _j.sent(), errorToThrow = _d.errorToThrow, errorEvents = _d.events;
+                                    if (errorToThrow)
+                                        throw errorToThrow;
+                                    return [2 /*return*/, {
+                                            events: errorEvents,
+                                        }];
+                                case 8: return [4 /*yield*/, syncEventResource.releaseLock(event, acquiredLock, span)];
+                                case 9:
+                                    _j.sent();
+                                    span.end();
+                                    return [7 /*endfinally*/];
+                                case 10: return [2 /*return*/];
+                            }
+                        });
+                    }); },
+                })];
+            case 1: return [2 /*return*/, _d.sent()];
+        }
+    });
+}); };
+exports.executeWithOrchestrationWrapper = executeWithOrchestrationWrapper;

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

@@ -0,0 +1,7 @@
+import type { Span } from '@opentelemetry/api';
+import { type ArvoEvent, type ArvoOrchestrationSubjectContent } from 'arvo-core';
+import type { SyncEventResource } from '../../SyncEventResource';
+/**
+ * Validates and parses orchestration subject
+ */
+export declare const validateAndParseSubject: (event: ArvoEvent, expectedSource: string, syncEventResource: SyncEventResource<any>, span: Span, handlerType: "orchestrator" | "resumable") => ArvoOrchestrationSubjectContent | null;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/validateAndParseSubject.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndParseSubject = void 0;
+var arvo_core_1 = require("arvo-core");
+/**
+ * Validates and parses orchestration subject
+ */
+var validateAndParseSubject = function (event, expectedSource, syncEventResource, span, handlerType) {
+    var _a;
+    syncEventResource.validateEventSubject(event, span);
+    var parsedEventSubject = arvo_core_1.ArvoOrchestrationSubject.parse(event.subject);
+    span.setAttributes((_a = {},
+        _a["arvo.parsed.subject.".concat(handlerType, ".name")] = parsedEventSubject.orchestrator.name,
+        _a["arvo.parsed.subject.".concat(handlerType, ".version")] = parsedEventSubject.orchestrator.version,
+        _a));
+    if (parsedEventSubject.orchestrator.name !== expectedSource) {
+        (0, arvo_core_1.logToSpan)({
+            level: 'WARNING',
+            message: "Event subject mismatch - expected '".concat(expectedSource, "' but got '").concat(parsedEventSubject.orchestrator.name, "'"),
+        }, span);
+        return null;
+    }
+    return parsedEventSubject;
+};
+exports.validateAndParseSubject = validateAndParseSubject;

package/dist/ArvoOrchestrationUtils/types.d.ts

@@ -0,0 +1 @@
+export type ArvoOrchestrationHandlerType = 'orchestrator' | 'resumable';

package/dist/ArvoOrchestrationUtils/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ArvoOrchestrator/factory.js

@@ -13,6 +13,7 @@ exports.createArvoOrchestrator = void 0;
 var _1 = require(".");
 var MachineExecutionEngine_1 = require("../MachineExecutionEngine");
 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.
@@ -46,6 +47,18 @@ var createArvoOrchestrator = function (_a) {
     }
     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 representativeMachine = registry.machines[0];
+    var lastSeenVersions = [];
+    for (var _i = 0, _b = registry.machines; _i < _b.length; _i++) {
+        var machine = _b[_i];
+        if (representativeMachine.source !== machine.source) {
+            throw new errors_1.ConfigViolation("All the machines in the orchestrator must have type '".concat(representativeMachine.source, "'"));
+        }
+        if (lastSeenVersions.includes(machine.version)) {
+            throw new errors_1.ConfigViolation("An orchestrator must have unique machine versions. Machine ID:".concat(machine.id, " has duplicate version ").concat(machine.version, "."));
+        }
+        lastSeenVersions.push(machine.version);
+    }
     return new _1.ArvoOrchestrator({
         executionunits: executionunits,
         memory: memory,