arvo-event-handler 3.0.7 → 3.0.8

package/dist/ArvoEventHandler/index.d.ts

@@ -1,6 +1,6 @@
 import { type SpanOptions } from '@opentelemetry/api';
 import { type ArvoContract, type ArvoEvent } from 'arvo-core';
-import IArvoEventHandler from '../IArvoEventHandler';
+import type IArvoEventHandler from '../IArvoEventHandler';
 import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
 import type { ArvoEventHandlerFunction, ArvoEventHandlerParam } from './types';
 /**

package/dist/ArvoEventHandler/index.js

@@ -60,9 +60,9 @@ var __rest = (this && this.__rest) || function (s, e) {
 Object.defineProperty(exports, "__esModule", { value: true });
 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");
-var ArvoDomain_1 = require("../ArvoDomain");
 /**
  * `ArvoEventHandler` is the foundational component for building stateless,
  * contract-bound services in the Arvo system.

package/dist/ArvoMachine/createMachine.d.ts

@@ -1,4 +1,4 @@
-import { type ArvoOrchestratorEventTypeGen, CreateArvoEvent, type InferVersionedArvoContract, type VersionedArvoContract } from 'arvo-core';
+import { type ArvoOrchestratorEventTypeGen, type CreateArvoEvent, 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 '.';

package/dist/ArvoMachine/createMachine.js

@@ -25,11 +25,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setupArvoMachine = setupArvoMachine;
 var arvo_core_1 = require("arvo-core");
+var uuid_1 = require("uuid");
 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.
  *

package/dist/ArvoOrchestrationUtils/createEmitableEvent.d.ts

@@ -0,0 +1,30 @@
+import type { Span } from '@opentelemetry/api';
+import { type ArvoEvent, type ArvoOrchestratorContract, type ArvoSemanticVersion, type OpenTelemetryHeaders, type VersionedArvoContract } from 'arvo-core';
+import type { EnqueueArvoEventActionParam } from '../ArvoMachine/types';
+export type CreateEmittableEventParams = {
+    event: EnqueueArvoEventActionParam;
+    otelHeaders: OpenTelemetryHeaders;
+    orchestrationParentSubject: string | null;
+    sourceEvent: ArvoEvent;
+    selfContract: VersionedArvoContract<ArvoOrchestratorContract, ArvoSemanticVersion>;
+    serviceContracts: Record<string, VersionedArvoContract<any, any>>;
+    initEventId: string;
+    domain: string | null;
+    executionunits: number;
+    source: string;
+};
+export declare const createEmittableEvent: ({ event, otelHeaders, orchestrationParentSubject, sourceEvent, selfContract, serviceContracts, initEventId, domain: _domain, executionunits, source, }: CreateEmittableEventParams, span: Span) => ArvoEvent;
+/**
+ * Processes raw events into emittable events with domain resolution
+ */
+export declare const processRawEventsIntoEmittables: (params: {
+    rawEvents: EnqueueArvoEventActionParam[];
+    otelHeaders: OpenTelemetryHeaders;
+    orchestrationParentSubject: string | null;
+    sourceEvent: ArvoEvent;
+    selfContract: VersionedArvoContract<ArvoOrchestratorContract, ArvoSemanticVersion>;
+    serviceContracts: Record<string, VersionedArvoContract<any, any>>;
+    initEventId: string;
+    executionunits: number;
+    source: string;
+}, span: Span) => ArvoEvent[];

package/dist/ArvoOrchestrationUtils/createEmitableEvent.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processRawEventsIntoEmittables = exports.createEmittableEvent = void 0;
+var arvo_core_1 = require("arvo-core");
+var ArvoDomain_1 = require("../ArvoDomain");
+var errors_1 = require("../errors");
+var createEmittableEvent = function (_a, span) {
+    var _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    var event = _a.event, otelHeaders = _a.otelHeaders, orchestrationParentSubject = _a.orchestrationParentSubject, sourceEvent = _a.sourceEvent, selfContract = _a.selfContract, serviceContracts = _a.serviceContracts, initEventId = _a.initEventId, _domain = _a.domain, executionunits = _a.executionunits, source = _a.source;
+    (0, arvo_core_1.logToSpan)({
+        level: 'INFO',
+        message: "Creating emittable event: ".concat(event.type),
+    }, span);
+    var serviceContractMap = Object.fromEntries(Object.values(serviceContracts).map(function (item) { return [
+        item.accepts.type,
+        item,
+    ]; }));
+    var schema = null;
+    var contract = null;
+    var subject = sourceEvent.subject;
+    var parentId = sourceEvent.id;
+    var domain = (0, ArvoDomain_1.resolveEventDomain)({
+        domainToResolve: _domain,
+        handlerSelfContract: selfContract,
+        eventContract: null,
+        triggeringEvent: sourceEvent,
+    });
+    if (event.type === selfContract.metadata.completeEventType) {
+        (0, arvo_core_1.logToSpan)({
+            level: 'INFO',
+            message: "Creating event for workflow completion: ".concat(event.type),
+        }, span);
+        contract = selfContract;
+        schema = selfContract.emits[selfContract.metadata.completeEventType];
+        subject = orchestrationParentSubject !== null && orchestrationParentSubject !== void 0 ? orchestrationParentSubject : sourceEvent.subject;
+        parentId = initEventId;
+        domain = (0, ArvoDomain_1.resolveEventDomain)({
+            domainToResolve: _domain,
+            handlerSelfContract: selfContract,
+            eventContract: selfContract,
+            triggeringEvent: sourceEvent,
+        });
+    }
+    else if (serviceContractMap[event.type]) {
+        (0, arvo_core_1.logToSpan)({
+            level: 'INFO',
+            message: "Creating service event for external system: ".concat(event.type),
+        }, span);
+        contract = serviceContractMap[event.type];
+        schema = serviceContractMap[event.type].accepts.schema;
+        domain = (0, ArvoDomain_1.resolveEventDomain)({
+            domainToResolve: _domain,
+            handlerSelfContract: selfContract,
+            eventContract: contract,
+            triggeringEvent: sourceEvent,
+        });
+        if (contract.metadata.contractType === 'ArvoOrchestratorContract') {
+            if (event.data.parentSubject$$) {
+                try {
+                    arvo_core_1.ArvoOrchestrationSubject.parse(event.data.parentSubject$$);
+                }
+                catch (_o) {
+                    throw new errors_1.ExecutionViolation("Invalid parentSubject$$ for the event(type='".concat(event.type, "', uri='").concat((_b = event.dataschema) !== null && _b !== void 0 ? _b : arvo_core_1.EventDataschemaUtil.create(contract), "'). It must be follow the ArvoOrchestrationSubject schema. The easiest way is to use the current orchestration subject by storing the subject via the context block in the machine definition."));
+                }
+            }
+            try {
+                if (event.data.parentSubject$$) {
+                    subject = arvo_core_1.ArvoOrchestrationSubject.from({
+                        orchestator: contract.accepts.type,
+                        version: contract.version,
+                        subject: event.data.parentSubject$$,
+                        domain: domain !== null && domain !== void 0 ? domain : null,
+                        meta: {
+                            redirectto: (_c = event.redirectto) !== null && _c !== void 0 ? _c : source,
+                        },
+                    });
+                }
+                else {
+                    subject = arvo_core_1.ArvoOrchestrationSubject.new({
+                        version: contract.version,
+                        orchestator: contract.accepts.type,
+                        initiator: source,
+                        domain: domain !== null && domain !== void 0 ? domain : undefined,
+                        meta: {
+                            redirectto: (_d = event.redirectto) !== null && _d !== void 0 ? _d : source,
+                        },
+                    });
+                }
+            }
+            catch (error) {
+                throw new errors_1.ExecutionViolation("Orchestration subject creation failed due to invalid parameters - Event: ".concat(event.type, " - ").concat(error === null || error === void 0 ? void 0 : error.message));
+            }
+        }
+    }
+    var finalDataschema = event.dataschema;
+    var finalData = event.data;
+    if (contract && schema) {
+        try {
+            finalData = schema.parse(event.data);
+            finalDataschema = arvo_core_1.EventDataschemaUtil.create(contract);
+        }
+        catch (error) {
+            throw new errors_1.ContractViolation("Invalid event data: Schema validation failed.\nEvent type: ".concat(event.type, "\nDetails: ").concat(error.message));
+        }
+    }
+    var emittableEvent = (0, arvo_core_1.createArvoEvent)({
+        id: event.id,
+        source: source,
+        type: event.type,
+        subject: subject,
+        dataschema: finalDataschema !== null && finalDataschema !== void 0 ? finalDataschema : undefined,
+        data: finalData,
+        to: (_e = event.to) !== null && _e !== void 0 ? _e : event.type,
+        accesscontrol: (_g = (_f = event.accesscontrol) !== null && _f !== void 0 ? _f : sourceEvent.accesscontrol) !== null && _g !== void 0 ? _g : undefined,
+        redirectto: (_h = event.redirectto) !== null && _h !== void 0 ? _h : source,
+        executionunits: (_j = event.executionunits) !== null && _j !== void 0 ? _j : executionunits,
+        traceparent: (_k = otelHeaders.traceparent) !== null && _k !== void 0 ? _k : undefined,
+        tracestate: (_l = otelHeaders.tracestate) !== null && _l !== void 0 ? _l : undefined,
+        parentid: parentId,
+        domain: domain !== null && domain !== void 0 ? domain : undefined,
+    }, (_m = event.__extensions) !== null && _m !== void 0 ? _m : {});
+    (0, arvo_core_1.logToSpan)({
+        level: 'INFO',
+        message: "Event created successfully: ".concat(emittableEvent.type),
+    }, span);
+    return emittableEvent;
+};
+exports.createEmittableEvent = createEmittableEvent;
+/**
+ * Processes raw events into emittable events with domain resolution
+ */
+var processRawEventsIntoEmittables = function (params, span) {
+    var _a;
+    var emittables = [];
+    for (var _i = 0, _b = params.rawEvents; _i < _b.length; _i++) {
+        var item = _b[_i];
+        for (var _c = 0, _d = Array.from(new Set((_a = item.domain) !== null && _a !== void 0 ? _a : [null])); _c < _d.length; _c++) {
+            var _dom = _d[_c];
+            var evt = (0, exports.createEmittableEvent)({
+                event: item,
+                otelHeaders: params.otelHeaders,
+                orchestrationParentSubject: params.orchestrationParentSubject,
+                sourceEvent: params.sourceEvent,
+                selfContract: params.selfContract,
+                serviceContracts: params.serviceContracts,
+                initEventId: params.initEventId,
+                domain: _dom,
+                executionunits: params.executionunits,
+                source: params.source,
+            }, span);
+            emittables.push(evt);
+            for (var _e = 0, _f = Object.entries(emittables[emittables.length - 1].otelAttributes); _e < _f.length; _e++) {
+                var _g = _f[_e], key = _g[0], value = _g[1];
+                span.setAttribute("to_emit.".concat(emittables.length - 1, ".").concat(key), value);
+            }
+        }
+    }
+    return emittables;
+};
+exports.processRawEventsIntoEmittables = processRawEventsIntoEmittables;

package/dist/ArvoOrchestrationUtils/error.d.ts

@@ -0,0 +1,18 @@
+import { type ArvoEvent, ViolationError } from 'arvo-core';
+export declare const TransactionViolationCause: {
+    readonly READ_FAILURE: "READ_MACHINE_MEMORY_FAILURE";
+    readonly LOCK_FAILURE: "LOCK_MACHINE_MEMORY_FAILURE";
+    readonly WRITE_FAILURE: "WRITE_MACHINE_MEMORY_FAILURE";
+    readonly LOCK_UNACQUIRED: "LOCK_UNACQUIRED";
+    readonly INVALID_SUBJECT: "INVALID_SUBJECT";
+};
+export type TransactionViolationCauseType = (typeof TransactionViolationCause)[keyof typeof TransactionViolationCause];
+export declare class TransactionViolation extends ViolationError<'OrchestratorTransaction'> {
+    readonly cause: TransactionViolationCauseType;
+    constructor(param: {
+        cause: TransactionViolationCauseType;
+        message: string;
+        initiatingEvent: ArvoEvent;
+    });
+}
+export declare const isTransactionViolationError: (error: unknown, cause?: TransactionViolationCauseType) => boolean;

package/dist/{ArvoOrchestrator → ArvoOrchestrationUtils}/error.js

@@ -15,16 +15,15 @@ var __extends = (this && this.__extends) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TransactionViolation = exports.TransactionViolationCause = void 0;
+exports.isTransactionViolationError = exports.TransactionViolation = exports.TransactionViolationCause = void 0;
 var arvo_core_1 = require("arvo-core");
-var TransactionViolationCause;
-(function (TransactionViolationCause) {
-    TransactionViolationCause["READ_FAILURE"] = "READ_MACHINE_MEMORY_FAILURE";
-    TransactionViolationCause["LOCK_FAILURE"] = "LOCK_MACHINE_MEMORY_FAILURE";
-    TransactionViolationCause["WRITE_FAILURE"] = "WRITE_MACHINE_MEMORY_FAILURE";
-    TransactionViolationCause["LOCK_UNACQUIRED"] = "LOCK_UNACQUIRED";
-    TransactionViolationCause["INVALID_SUBJECT"] = "INVALID_SUBJECT";
-})(TransactionViolationCause || (exports.TransactionViolationCause = TransactionViolationCause = {}));
+exports.TransactionViolationCause = {
+    READ_FAILURE: 'READ_MACHINE_MEMORY_FAILURE',
+    LOCK_FAILURE: 'LOCK_MACHINE_MEMORY_FAILURE',
+    WRITE_FAILURE: 'WRITE_MACHINE_MEMORY_FAILURE',
+    LOCK_UNACQUIRED: 'LOCK_UNACQUIRED',
+    INVALID_SUBJECT: 'INVALID_SUBJECT',
+};
 var TransactionViolation = /** @class */ (function (_super) {
     __extends(TransactionViolation, _super);
     function TransactionViolation(param) {
@@ -41,3 +40,9 @@ var TransactionViolation = /** @class */ (function (_super) {
     return TransactionViolation;
 }(arvo_core_1.ViolationError));
 exports.TransactionViolation = TransactionViolation;
+var isTransactionViolationError = function (error, cause) {
+    return ((0, arvo_core_1.isViolationError)(error) &&
+        error.type === 'OrchestratorTransaction' &&
+        (cause ? error.cause === cause : true));
+};
+exports.isTransactionViolationError = isTransactionViolationError;

package/dist/ArvoOrchestrationUtils/handlerErrors.d.ts

@@ -0,0 +1,35 @@
+import { type Span } from '@opentelemetry/api';
+import { type ArvoEvent, type ArvoOrchestratorContract, type ArvoSemanticVersion, type OpenTelemetryHeaders, type VersionedArvoContract, type ViolationError } from 'arvo-core';
+import type { SyncEventResource } from '../SyncEventResource';
+import type { OrchestrationExecutionMemoryRecord } from './orchestrationExecutionState';
+import type { ArvoOrchestrationHandlerType } from './types';
+/**
+ * Parameters for system error event creation
+ */
+export type CreateSystemErrorEventsParams = {
+    error: unknown;
+    event: ArvoEvent;
+    otelHeaders: OpenTelemetryHeaders;
+    orchestrationParentSubject: string | null;
+    initEventId: string | null;
+    selfContract: VersionedArvoContract<ArvoOrchestratorContract, ArvoSemanticVersion>;
+    systemErrorDomain?: (string | null)[];
+    executionunits: number;
+    source: string;
+    domain: string | null;
+};
+/**
+ * Creates system error events
+ */
+export declare const createSystemErrorEvents: ({ error, event, otelHeaders, orchestrationParentSubject, initEventId, selfContract, systemErrorDomain, executionunits, source, domain, }: CreateSystemErrorEventsParams & {
+    error: Error;
+}) => ArvoEvent[];
+export declare const handleOrchestrationErrors: (_handlerType: ArvoOrchestrationHandlerType, param: CreateSystemErrorEventsParams & {
+    syncEventResource: SyncEventResource<OrchestrationExecutionMemoryRecord<Record<string, any>>>;
+}, span: Span) => Promise<{
+    errorToThrow: ViolationError;
+    events: null;
+} | {
+    errorToThrow: null;
+    events: ArvoEvent[];
+}>;

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"]>>>;