arvo-event-handler 3.0.7 → 3.0.10

package/dist/ArvoEventHandler/index.d.ts

@@ -1,7 +1,6 @@
-import { type SpanOptions } from '@opentelemetry/api';
 import { type ArvoContract, type ArvoEvent } from 'arvo-core';
-import IArvoEventHandler from '../IArvoEventHandler';
-import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+import type IArvoEventHandler from '../IArvoEventHandler';
+import type { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions } from '../types';
 import type { ArvoEventHandlerFunction, ArvoEventHandlerParam } from './types';
 /**
  * `ArvoEventHandler` is the foundational component for building stateless,
@@ -89,7 +88,7 @@ export default class ArvoEventHandler<TContract extends ArvoContract> implements
     /** Computational cost metric associated with event handling operations */
     readonly executionunits: number;
     /** OpenTelemetry configuration for event handling spans */
-    readonly spanOptions: SpanOptions;
+    readonly spanOptions: ArvoEventHandlerOtelSpanOptions;
     /** Version-specific event handler implementation map */
     readonly handler: ArvoEventHandlerFunction<TContract>;
     /** The source identifier for events produced by this handler */

package/dist/ArvoEventHandler/index.js

@@ -60,9 +60,11 @@ 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 handlerErrors_1 = require("../ArvoOrchestrationUtils/handlerErrors");
+var orchestrationExecutionWrapper_1 = require("../ArvoOrchestrationUtils/orchestrationExecutionWrapper");
 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.
@@ -208,32 +210,32 @@ var ArvoEventHandler = /** @class */ (function () {
      *                           in handler configuration, or when contract URI mismatch occurs
      * @throws {ExecutionViolation} for explicitly handled runtime errors that should bubble up
      */
-    ArvoEventHandler.prototype.execute = function (event_1) {
-        return __awaiter(this, arguments, void 0, function (event, opentelemetry) {
+    ArvoEventHandler.prototype.execute = function (event, opentelemetry) {
+        return __awaiter(this, void 0, void 0, function () {
             var otelConfig;
             var _this = this;
-            if (opentelemetry === void 0) { opentelemetry = {
-                inheritFrom: 'EVENT',
-            }; }
-            return __generator(this, function (_a) {
-                switch (_a.label) {
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
-                        otelConfig = (0, utils_1.createEventHandlerTelemetryConfig)("Handler<".concat(this.contract.uri, ">"), this.spanOptions, opentelemetry, event);
+                        otelConfig = (0, utils_1.createEventHandlerTelemetryConfig)(((_b = (_a = this.spanOptions).spanName) === null || _b === void 0 ? void 0 : _b.call(_a, { selfContractUri: this.contract.uri, consumedEvent: event })) ||
+                            "Handler<".concat(this.contract.uri, ">"), this.spanOptions, opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : { inheritFrom: 'EVENT' }, event);
                         return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan(__assign(__assign({}, otelConfig), { fn: function (span) { return __awaiter(_this, void 0, void 0, function () {
-                                    var otelSpanHeaders, _i, _a, _b, key, value, parsedDataSchema, handlerContract_1, inputEventValidation, _handleOutput, outputs, result, _c, outputs_1, item, __extensions, handlerResult, domains, _d, _e, _dom, _f, _g, _h, key, value, error_1, result, _j, _k, _dom, _l, _m, _o, key, value;
-                                    var _this = this;
-                                    var _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
-                                    return __generator(this, function (_z) {
-                                        switch (_z.label) {
+                                    var otelSpanHeaders, _i, _a, _b, key, value, parsedDataSchema, handlerContract_1, inputEventValidation, _handleOutput, outputs, result, _c, outputs_1, item, __extensions, handlerResult, domains, _d, _e, _dom, _f, _g, _h, key, value, error_1, errorEvents, _j, _k, _l, errEvtIdx, errEvt, _m, _o, _p, key, value;
+                                    var _q, _r, _s, _t, _u, _v;
+                                    return __generator(this, function (_w) {
+                                        switch (_w.label) {
                                             case 0:
                                                 otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
-                                                _z.label = 1;
+                                                _w.label = 1;
                                             case 1:
-                                                _z.trys.push([1, 3, 4, 5]);
+                                                _w.trys.push([1, 3, 4, 5]);
+                                                span.setAttribute('arvo.handler.execution.status', 'normal');
+                                                span.setAttribute('arvo.handler.execution.type', 'handler');
                                                 span.setStatus({ code: api_1.SpanStatusCode.OK });
                                                 for (_i = 0, _a = Object.entries(event.otelAttributes); _i < _a.length; _i++) {
                                                     _b = _a[_i], key = _b[0], value = _b[1];
-                                                    span.setAttribute("to_process.0.".concat(key), value);
+                                                    span.setAttribute("consumable.0.".concat(key), value);
                                                 }
                                                 if (this.contract.type !== event.type) {
                                                     throw new errors_1.ConfigViolation("Event type mismatch: Received '".concat(event.type, "', expected '").concat(this.contract.type, "'"));
@@ -256,9 +258,9 @@ var ArvoEventHandler = /** @class */ (function () {
                                                     });
                                                 }
                                                 try {
-                                                    handlerContract_1 = this.contract.version((_p = parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version) !== null && _p !== void 0 ? _p : 'latest');
+                                                    handlerContract_1 = this.contract.version((_q = parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version) !== null && _q !== void 0 ? _q : 'latest');
                                                 }
-                                                catch (_0) {
+                                                catch (_x) {
                                                     throw new errors_1.ConfigViolation("Invalid contract version: ".concat(parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version, ". Available versions: ").concat(Object.keys(this.contract.versions).join(', ')));
                                                 }
                                                 (0, arvo_core_1.logToSpan)({
@@ -289,7 +291,7 @@ var ArvoEventHandler = /** @class */ (function () {
                                                         spanHeaders: otelSpanHeaders,
                                                     })];
                                             case 2:
-                                                _handleOutput = _z.sent();
+                                                _handleOutput = _w.sent();
                                                 if (!_handleOutput)
                                                     return [2 /*return*/, {
                                                             events: [],
@@ -306,85 +308,65 @@ var ArvoEventHandler = /** @class */ (function () {
                                                     item = outputs_1[_c];
                                                     try {
                                                         __extensions = item.__extensions, handlerResult = __rest(item, ["__extensions"]);
-                                                        domains = (_r = (_q = handlerResult.domain) === null || _q === void 0 ? void 0 : _q.map(function (item) {
+                                                        domains = (_s = (_r = handlerResult.domain) === null || _r === void 0 ? void 0 : _r.map(function (item) {
                                                             return (0, ArvoDomain_1.resolveEventDomain)({
                                                                 domainToResolve: item,
                                                                 handlerSelfContract: handlerContract_1,
                                                                 eventContract: handlerContract_1,
                                                                 triggeringEvent: event,
                                                             });
-                                                        })) !== null && _r !== void 0 ? _r : [null];
+                                                        })) !== null && _s !== void 0 ? _s : [null];
                                                         for (_d = 0, _e = Array.from(new Set(domains)); _d < _e.length; _d++) {
                                                             _dom = _e[_d];
                                                             result.push((0, arvo_core_1.createArvoEventFactory)(handlerContract_1).emits(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: this.source, subject: event.subject, 
                                                                 // 'source'
                                                                 // prioritise returned 'to', 'redirectto' and then
-                                                                to: (0, utils_1.coalesceOrDefault)([handlerResult.to, event.redirectto], event.source), executionunits: (0, utils_1.coalesce)(handlerResult.executionunits, this.executionunits), accesscontrol: (_t = (_s = handlerResult.accesscontrol) !== null && _s !== void 0 ? _s : event.accesscontrol) !== null && _t !== void 0 ? _t : undefined, parentid: event.id, domain: _dom }), __extensions));
+                                                                to: (0, utils_1.coalesceOrDefault)([handlerResult.to, event.redirectto], event.source), executionunits: (0, utils_1.coalesce)(handlerResult.executionunits, this.executionunits), accesscontrol: (_u = (_t = handlerResult.accesscontrol) !== null && _t !== void 0 ? _t : event.accesscontrol) !== null && _u !== void 0 ? _u : undefined, parentid: event.id, domain: _dom }), __extensions));
                                                             for (_f = 0, _g = Object.entries(result[result.length - 1].otelAttributes); _f < _g.length; _f++) {
                                                                 _h = _g[_f], key = _h[0], value = _h[1];
-                                                                span.setAttribute("to_emit.".concat(result.length - 1, ".").concat(key), value);
+                                                                span.setAttribute("emittables.".concat(result.length - 1, ".").concat(key), value);
                                                             }
                                                         }
                                                     }
                                                     catch (e) {
-                                                        throw new errors_1.ContractViolation((_u = e === null || e === void 0 ? void 0 : e.message) !== null && _u !== void 0 ? _u : 'Invalid data');
+                                                        throw new errors_1.ContractViolation((_v = e === null || e === void 0 ? void 0 : e.message) !== null && _v !== void 0 ? _v : 'Invalid data');
                                                     }
                                                 }
-                                                (0, arvo_core_1.logToSpan)({
-                                                    level: 'INFO',
-                                                    message: "Event processing completed successfully. Generated ".concat(result.length, " event(s)"),
-                                                });
-                                                (0, arvo_core_1.logToSpan)({
-                                                    level: 'INFO',
-                                                    message: 'Event handled successfully',
-                                                });
-                                                return [2 /*return*/, {
-                                                        events: result,
-                                                    }];
+                                                return [2 /*return*/, (0, orchestrationExecutionWrapper_1.returnEventsWithLogging)({ events: result }, span)];
                                             case 3:
-                                                error_1 = _z.sent();
+                                                error_1 = _w.sent();
+                                                span.setAttribute('arvo.handler.execution.status', 'failure');
                                                 (0, arvo_core_1.exceptionToSpan)(error_1);
                                                 span.setStatus({
                                                     code: api_1.SpanStatusCode.ERROR,
                                                     message: "Event processing failed: ".concat(error_1.message),
                                                 });
-                                                if (error_1.name.includes('ViolationError')) {
+                                                if ((0, arvo_core_1.isViolationError)(error_1)) {
                                                     throw error_1;
                                                 }
-                                                result = [];
-                                                for (_j = 0, _k = Array.from(new Set(this.systemErrorDomain
-                                                    ? this.systemErrorDomain.map(function (item) {
-                                                        return (0, ArvoDomain_1.resolveEventDomain)({
-                                                            domainToResolve: item,
-                                                            handlerSelfContract: _this.contract.version('latest'),
-                                                            eventContract: _this.contract.version('latest'),
-                                                            triggeringEvent: event,
-                                                        });
-                                                    })
-                                                    : [event.domain, this.domain, null])); _j < _k.length; _j++) {
-                                                    _dom = _k[_j];
-                                                    result.push((0, arvo_core_1.createArvoEventFactory)(this.contract.version('latest')).systemError({
-                                                        source: this.source,
-                                                        subject: event.subject,
-                                                        // The system error must always got back to
-                                                        // the source
-                                                        to: event.source,
-                                                        error: error_1,
-                                                        executionunits: this.executionunits,
-                                                        traceparent: (_v = otelSpanHeaders.traceparent) !== null && _v !== void 0 ? _v : undefined,
-                                                        tracestate: (_w = otelSpanHeaders.tracestate) !== null && _w !== void 0 ? _w : undefined,
-                                                        accesscontrol: (_x = event.accesscontrol) !== null && _x !== void 0 ? _x : undefined,
-                                                        parentid: (_y = event.id) !== null && _y !== void 0 ? _y : undefined,
-                                                        domain: _dom,
-                                                    }));
-                                                    for (_l = 0, _m = Object.entries(result[result.length - 1].otelAttributes); _l < _m.length; _l++) {
-                                                        _o = _m[_l], key = _o[0], value = _o[1];
-                                                        span.setAttribute("to_emit.".concat(result.length - 1, ".").concat(key), value);
+                                                errorEvents = (0, handlerErrors_1.createSystemErrorEvents)({
+                                                    error: error_1,
+                                                    event: event,
+                                                    otelHeaders: otelSpanHeaders,
+                                                    orchestrationParentSubject: null,
+                                                    initEventId: event.id,
+                                                    selfContract: this.contract.version('any'),
+                                                    systemErrorDomain: undefined,
+                                                    executionunits: this.executionunits,
+                                                    source: this.source,
+                                                    domain: this.domain,
+                                                    handlerType: 'handler',
+                                                });
+                                                for (_j = 0, _k = Object.entries(errorEvents); _j < _k.length; _j++) {
+                                                    _l = _k[_j], errEvtIdx = _l[0], errEvt = _l[1];
+                                                    for (_m = 0, _o = Object.entries(errEvt.otelAttributes); _m < _o.length; _m++) {
+                                                        _p = _o[_m], key = _p[0], value = _p[1];
+                                                        span.setAttribute("emittables.".concat(errEvtIdx, ".").concat(key), value);
                                                     }
                                                 }
-                                                return [2 /*return*/, {
-                                                        events: result,
-                                                    }];
+                                                return [2 /*return*/, (0, orchestrationExecutionWrapper_1.returnEventsWithLogging)({
+                                                        events: errorEvents,
+                                                    }, span)];
                                             case 4:
                                                 span.end();
                                                 return [7 /*endfinally*/];
@@ -392,7 +374,7 @@ var ArvoEventHandler = /** @class */ (function () {
                                         }
                                     });
                                 }); } }))];
-                    case 1: return [2 /*return*/, _a.sent()];
+                    case 1: return [2 /*return*/, _c.sent()];
                 }
             });
         });

package/dist/ArvoEventHandler/types.d.ts

@@ -1,6 +1,7 @@
-import type { Span, SpanOptions } from '@opentelemetry/api';
+import type { Span } from '@opentelemetry/api';
 import type { ArvoContract, ArvoEvent, ArvoSemanticVersion, CreateArvoEvent, InferArvoEvent, OpenTelemetryHeaders, VersionedArvoContract } from 'arvo-core';
 import type { z } from 'zod';
+import type { ArvoEventHandlerOtelSpanOptions } from '../types';
 /**
  * Represents the input for an ArvoEvent handler function.
  */
@@ -90,7 +91,7 @@ export type ArvoEventHandlerParam<TContract extends ArvoContract> = {
     /**
      * The OpenTelemetry span options
      */
-    spanOptions?: SpanOptions;
+    spanOptions?: ArvoEventHandlerOtelSpanOptions;
     /**
      * Optional configuration to customize where system error events are emitted.
      *

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("emittables.".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,36 @@
+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;
+    handlerType: ArvoOrchestrationHandlerType;
+};
+/**
+ * Creates system error events
+ */
+export declare const createSystemErrorEvents: ({ error, event, otelHeaders, orchestrationParentSubject, initEventId, selfContract, systemErrorDomain, executionunits, source, domain, handlerType, }: 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[];
+}>;