arvo-event-handler 3.0.26 → 3.0.27

package/dist/ArvoOrchestrationUtils/handlerErrors.d.ts

@@ -1,9 +1,10 @@
 import { type Span } from '@opentelemetry/api';
 import { type ArvoContract, type ArvoEvent, type ArvoSemanticVersion, type OpenTelemetryHeaders, type VersionedArvoContract, type ViolationError } from 'arvo-core';
 import type { SyncEventResource } from '../SyncEventResource';
-import type { OrchestrationExecutionMemoryRecord } from './orchestrationExecutionState';
+import { type OrchestrationExecutionMemoryRecord } from './orchestrationExecutionState';
 import { type ArvoOrchestrationHandlerType } from './types';
 import type { NonEmptyArray } from '../types';
+import { MachineMemoryMetadata } from '../MachineMemory/interface';
 /**
  * Parameters for creating system error events during orchestration failures.
  */
@@ -54,7 +55,7 @@ export declare const createSystemErrorEvents: ({ error, event, otelHeaders, orch
  */
 export declare const handleOrchestrationErrors: (_handlerType: ArvoOrchestrationHandlerType, param: CreateSystemErrorEventsParams & {
     syncEventResource: SyncEventResource<OrchestrationExecutionMemoryRecord<Record<string, any>>>;
-}, span: Span) => Promise<{
+}, metadata: MachineMemoryMetadata, span: Span) => Promise<{
     errorToThrow: ViolationError;
     events: null;
 } | {

package/dist/ArvoOrchestrationUtils/handlerErrors.js

@@ -53,6 +53,7 @@ var arvo_core_1 = require("arvo-core");
 var ArvoDomain_1 = require("../ArvoDomain");
 var errors_1 = require("../errors");
 var utils_1 = require("../utils");
+var orchestrationExecutionState_1 = require("./orchestrationExecutionState");
 var types_1 = require("./types");
 /**
  * Creates standardized system error events for orchestration failures.
@@ -136,7 +137,7 @@ exports.createSystemErrorEvents = createSystemErrorEvents;
  *
  * @returns Either the violation error to throw or system error events to emit
  */
-var handleOrchestrationErrors = function (_handlerType, param, span) { return __awaiter(void 0, void 0, void 0, function () {
+var handleOrchestrationErrors = function (_handlerType, param, metadata, 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) {
@@ -170,10 +171,11 @@ var handleOrchestrationErrors = function (_handlerType, param, span) { return __
                 }
                 return [4 /*yield*/, param.syncEventResource
                         .persistState(param.event, {
-                        executionStatus: 'failure',
+                        __type: 'OrchestrationExecutionMemoryRecord',
+                        executionStatus: orchestrationExecutionState_1.OrchestrationExecutionStatus.FAILURE,
                         subject: param.event.subject,
                         error: param.error,
-                    }, null, span)
+                    }, null, metadata, span)
                         .catch(function (e) {
                         (0, arvo_core_1.logToSpan)({
                             level: 'CRITICAL',

package/dist/ArvoOrchestrationUtils/orchestrationExecutionState.d.ts

@@ -9,6 +9,8 @@ export declare const OrchestrationExecutionStatus: {
     readonly NORMAL: "normal";
     /** Orchestration has failed and entered terminal error state */
     readonly FAILURE: "failure";
+    /** Orchestration is marked as done */
+    readonly DONE: "done";
 };
 /**
  * Discriminated union representing persisted orchestration state.
@@ -26,8 +28,10 @@ export declare const OrchestrationExecutionStatus: {
  * @template T - Custom state fields specific to the orchestration type
  */
 export type OrchestrationExecutionMemoryRecord<T extends Record<string, unknown>> = (T & {
-    executionStatus: typeof OrchestrationExecutionStatus.NORMAL;
+    __type: 'OrchestrationExecutionMemoryRecord';
+    executionStatus: typeof OrchestrationExecutionStatus.NORMAL | typeof OrchestrationExecutionStatus.DONE;
 }) | (Partial<T> & {
+    __type: 'OrchestrationExecutionMemoryRecord';
     executionStatus: typeof OrchestrationExecutionStatus.FAILURE;
     error: Error;
     subject: string;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionState.js

@@ -12,4 +12,6 @@ exports.OrchestrationExecutionStatus = {
     NORMAL: 'normal',
     /** Orchestration has failed and entered terminal error state */
     FAILURE: 'failure',
+    /** Orchestration is marked as done */
+    DONE: 'done',
 };

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

@@ -2,6 +2,7 @@ import type { Span } from '@opentelemetry/api';
 import { type ArvoEvent } from 'arvo-core';
 import type { SyncEventResource } from '../../SyncEventResource';
 import type { AcquiredLockStatusType } from '../../SyncEventResource/types';
+import { MachineMemoryMetadata } from '../../MachineMemory/interface';
 /**
  * Acquires an exclusive lock for event processing with validation.
  *
@@ -9,4 +10,4 @@ import type { AcquiredLockStatusType } from '../../SyncEventResource/types';
  * processing. Throws if lock cannot be acquired, preventing concurrent modifications.
  * @throws {TransactionViolation} When lock cannot be acquired
  */
-export declare const acquireLockWithValidation: (syncEventResource: SyncEventResource<Record<string, any>>, event: ArvoEvent, span: Span) => Promise<AcquiredLockStatusType>;
+export declare const acquireLockWithValidation: (syncEventResource: SyncEventResource<Record<string, any>>, event: ArvoEvent, metadata: MachineMemoryMetadata, span: Span) => Promise<AcquiredLockStatusType>;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/acquireLockWithValidation.js

@@ -46,11 +46,11 @@ var error_1 = require("../error");
  * processing. Throws if lock cannot be acquired, preventing concurrent modifications.
  * @throws {TransactionViolation} When lock cannot be acquired
  */
-var acquireLockWithValidation = function (syncEventResource, event, span) { return __awaiter(void 0, void 0, void 0, function () {
+var acquireLockWithValidation = function (syncEventResource, event, metadata, 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 0: return [4 /*yield*/, syncEventResource.acquireLock(event, metadata, span)];
             case 1:
                 acquiredLock = _a.sent();
                 if (acquiredLock === 'NOT_ACQUIRED') {

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

@@ -2,8 +2,8 @@ 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, ArvoEventHandlerOtelSpanOptions, NonEmptyArray } from '../../types';
-import type { OrchestrationExecutionMemoryRecord } from '../orchestrationExecutionState';
+import { type ArvoEventHandlerOpenTelemetryOptions, type ArvoEventHandlerOtelSpanOptions, type NonEmptyArray } from '../../types';
+import { type OrchestrationExecutionMemoryRecord } from '../orchestrationExecutionState';
 import type { ArvoOrchestrationHandlerType } from '../types';
 /**
  * Configuration context for orchestration execution.

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/index.js

@@ -50,8 +50,10 @@ 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 types_1 = require("../../types");
 var utils_1 = require("../../utils");
 var handlerErrors_1 = require("../handlerErrors");
+var orchestrationExecutionState_1 = require("../orchestrationExecutionState");
 var acquireLockWithValidation_1 = require("./acquireLockWithValidation");
 var validateAndParseSubject_1 = require("./validateAndParseSubject");
 /**
@@ -90,7 +92,7 @@ var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return
             case 0:
                 otelConfig = (0, utils_1.createEventHandlerTelemetryConfig)(spanOptions.spanName({ selfContractUri: selfContract.uri, consumedEvent: event }), spanOptions, opentelemetry, event);
                 return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan(__assign(__assign({}, otelConfig), { fn: function (span) { return __awaiter(void 0, void 0, void 0, function () {
-                            var _i, _a, _b, key, value, otelHeaders, orchestrationParentSubject, initEventId, acquiredLock, parsedEventSubject, state, _c, emittables, newState, i, _d, _e, _f, key, value, error_1, _g, errorToThrow, errorEvents;
+                            var _i, _a, _b, key, value, otelHeaders, orchestrationParentSubject, initEventId, acquiredLock, machineMemoryMetadata, parsedEventSubject, state, _c, emittables, newState, i, _d, _e, _f, key, value, error_1, _g, errorToThrow, errorEvents;
                             var _h, _j, _k, _l;
                             return __generator(this, function (_m) {
                                 switch (_m.label) {
@@ -110,34 +112,42 @@ var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return
                                         orchestrationParentSubject = null;
                                         initEventId = null;
                                         acquiredLock = null;
+                                        machineMemoryMetadata = {
+                                            subject: event.subject,
+                                            source: source,
+                                            initiator: types_1.Materialized.pending(),
+                                            parentSubject: types_1.Materialized.pending(),
+                                        };
                                         _m.label = 1;
                                     case 1:
-                                        _m.trys.push([1, 6, 8, 10]);
+                                        _m.trys.push([1, 8, 10, 12]);
                                         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)];
+                                        return [4 /*yield*/, (0, acquireLockWithValidation_1.acquireLockWithValidation)(syncEventResource, event, machineMemoryMetadata, span)];
                                     case 2:
                                         // Lock acquisition
                                         acquiredLock = _m.sent();
-                                        return [4 /*yield*/, syncEventResource.acquireState(event, span)];
+                                        return [4 /*yield*/, syncEventResource.acquireState(event, machineMemoryMetadata, span)];
                                     case 3:
                                         state = _m.sent();
-                                        if ((state === null || state === void 0 ? void 0 : state.executionStatus) === 'failure') {
+                                        if ((state === null || state === void 0 ? void 0 : state.executionStatus) === orchestrationExecutionState_1.OrchestrationExecutionStatus.FAILURE ||
+                                            (state === null || state === void 0 ? void 0 : state.executionStatus) === orchestrationExecutionState_1.OrchestrationExecutionStatus.DONE) {
                                             span.setAttribute('arvo.handler.execution.status', state.executionStatus);
                                             (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),
+                                                message: "The orchestration is in terminal state '".concat(state.executionStatus, "'. Ignoring event id: ").concat(event.id, " with event subject: ").concat(event.subject),
                                             }, span);
                                             span.setStatus({
-                                                code: api_1.SpanStatusCode.ERROR,
-                                                message: "The orchestration has failed in a previous event. Ignoring event id: ".concat(event.id, " with event subject: ").concat(event.subject),
+                                                code: state.executionStatus === orchestrationExecutionState_1.OrchestrationExecutionStatus.FAILURE ? api_1.SpanStatusCode.ERROR : api_1.SpanStatusCode.OK,
+                                                message: "The orchestration is in terminal state '".concat(state.executionStatus, "'. Ignoring event id: ").concat(event.id, " with event subject: ").concat(event.subject),
                                             });
                                             return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: [] }, span)];
                                         }
                                         orchestrationParentSubject = (_h = state === null || state === void 0 ? void 0 : state.parentSubject) !== null && _h !== void 0 ? _h : null;
                                         initEventId = (_j = state === null || state === void 0 ? void 0 : state.initEventId) !== null && _j !== void 0 ? _j : null;
+                                        machineMemoryMetadata = __assign(__assign({}, machineMemoryMetadata), { initiator: types_1.Materialized.resolved(parsedEventSubject.execution.initiator), parentSubject: types_1.Materialized.resolved(orchestrationParentSubject) });
                                         if (!state) {
                                             (0, arvo_core_1.logToSpan)({
                                                 level: 'INFO',
@@ -180,10 +190,16 @@ var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return
                                             }
                                         }
                                         // Persist state
-                                        return [4 /*yield*/, syncEventResource.persistState(event, newState, state, span)];
+                                        return [4 /*yield*/, syncEventResource.persistState(event, newState, state, machineMemoryMetadata, span)];
                                     case 5:
                                         // Persist state
                                         _m.sent();
+                                        if (!(newState.executionStatus === orchestrationExecutionState_1.OrchestrationExecutionStatus.DONE)) return [3 /*break*/, 7];
+                                        return [4 /*yield*/, syncEventResource.cleanup(event, newState, state, machineMemoryMetadata, span)];
+                                    case 6:
+                                        _m.sent();
+                                        _m.label = 7;
+                                    case 7:
                                         (0, arvo_core_1.logToSpan)({
                                             level: 'INFO',
                                             message: "State update persisted in memory for subject ".concat(event.subject),
@@ -193,7 +209,7 @@ var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return
                                             message: "Execution successfully completed and emitted ".concat(emittables.length, " events"),
                                         });
                                         return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: emittables }, span)];
-                                    case 6:
+                                    case 8:
                                         error_1 = _m.sent();
                                         span.setAttribute('arvo.handler.execution.status', 'failure');
                                         return [4 /*yield*/, (0, handlerErrors_1.handleOrchestrationErrors)(_handlerType, {
@@ -208,20 +224,20 @@ var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return
                                                 source: source,
                                                 syncEventResource: syncEventResource,
                                                 handlerType: _handlerType,
-                                            }, span)];
-                                    case 7:
+                                            }, machineMemoryMetadata, span)];
+                                    case 9:
                                         _g = _m.sent(), errorToThrow = _g.errorToThrow, errorEvents = _g.events;
                                         if (errorToThrow)
                                             throw errorToThrow;
                                         return [2 /*return*/, {
                                                 events: errorEvents,
                                             }];
-                                    case 8: return [4 /*yield*/, syncEventResource.releaseLock(event, acquiredLock, span)];
-                                    case 9:
+                                    case 10: return [4 /*yield*/, syncEventResource.releaseLock(event, acquiredLock, machineMemoryMetadata, span)];
+                                    case 11:
                                         _m.sent();
                                         span.end();
                                         return [7 /*endfinally*/];
-                                    case 10: return [2 /*return*/];
+                                    case 12: return [2 /*return*/];
                                 }
                             });
                         }); } }))];

package/dist/ArvoOrchestrator/index.js

@@ -55,6 +55,7 @@ var orchestrationExecutionWrapper_1 = require("../ArvoOrchestrationUtils/orchest
 var SyncEventResource_1 = require("../SyncEventResource");
 var errors_1 = require("../errors");
 var ArvoDomain_1 = require("../ArvoDomain");
+var orchestrationExecutionState_1 = require("../ArvoOrchestrationUtils/orchestrationExecutionState");
 /**
  * Orchestrates state machine execution and lifecycle management.
  *
@@ -206,7 +207,10 @@ var ArvoOrchestrator = /** @class */ (function () {
                                     message: "Machine execution completed - Status: ".concat(executionResult.state.status, ", Generated events: ").concat(emittables.length),
                                 }, span);
                                 newState = {
-                                    executionStatus: 'normal',
+                                    __type: 'OrchestrationExecutionMemoryRecord',
+                                    executionStatus: executionResult.finalOutput
+                                        ? orchestrationExecutionState_1.OrchestrationExecutionStatus.DONE
+                                        : orchestrationExecutionState_1.OrchestrationExecutionStatus.NORMAL,
                                     initEventId: initEventId,
                                     subject: event.subject,
                                     parentSubject: orchestrationParentSubject,

package/dist/ArvoOrchestrator/types.d.ts

@@ -135,7 +135,8 @@ export type ArvoOrchestratorParam = {
  * Simplified interface for {@link createArvoOrchestrator} that automatically
  * constructs default registry and execution engine components.
  */
-export type CreateArvoOrchestratorParam = Pick<ArvoOrchestratorParam, 'memory' | 'executionunits' | 'spanOptions' | 'defaultEventEmissionDomains'> & {
+export type CreateArvoOrchestratorParam = Pick<ArvoOrchestratorParam, 'executionunits' | 'spanOptions' | 'defaultEventEmissionDomains'> & {
+    memory: IMachineMemory<Record<string, any>>;
     /**
      * Optional override for resource locking requirement.
      *

package/dist/ArvoResumable/index.js

@@ -56,6 +56,7 @@ var orchestrationExecutionWrapper_1 = require("../ArvoOrchestrationUtils/orchest
 var index_1 = require("../SyncEventResource/index");
 var errors_1 = require("../errors");
 var ArvoDomain_1 = require("../ArvoDomain");
+var orchestrationExecutionState_1 = require("../ArvoOrchestrationUtils/orchestrationExecutionState");
 /**
  * ArvoResumable complements {@link ArvoOrchestrator} by providing imperative
  * handler functions for orchestration logic instead of declarative state machines.
@@ -266,7 +267,10 @@ var ArvoResumable = /** @class */ (function () {
                                             produced: emittables.map(function (item) { return item.toJSON(); }),
                                         };
                                         newState = {
-                                            executionStatus: 'normal',
+                                            __type: 'OrchestrationExecutionMemoryRecord',
+                                            executionStatus: (executionResult === null || executionResult === void 0 ? void 0 : executionResult.output)
+                                                ? orchestrationExecutionState_1.OrchestrationExecutionStatus.DONE
+                                                : orchestrationExecutionState_1.OrchestrationExecutionStatus.NORMAL,
                                             status: (executionResult === null || executionResult === void 0 ? void 0 : executionResult.output) ? 'done' : 'active',
                                             initEventId: initEventId,
                                             parentSubject: orchestrationParentSubject,

package/dist/MachineMemory/Simple.d.ts

@@ -1,21 +1,47 @@
 import type { IMachineMemory } from './interface';
 /**
- * In-memory implementation of machine state storage for single-instance NodeJS apps.
- *
- * Best for: Container apps, request-scoped workflows, testing, demos
- * Not for: Multi-instance deployments, persistent workflows, distributed systems
+ * In-memory implementation of machine state storage for single-instance NodeJS applications.
  *
  * @example
  * const memory = new SimpleMachineMemory();
  * const orchestrator = createArvoOrchestrator({
  *   memory,
- *   executionunits: 1,
  *   machines: [workflow]
  * });
+ *
+ * @warning Concurrency Limitations
+ *
+ * This implementation is NOT concurrency-safe. Lock acquisition is not atomic,
+ * making it unsuitable for parallel event processing where multiple handlers
+ * might process events for the same workflow simultaneously.
+ *
+ * **Safe Usage:**
+ * - {@link SimpleEventBroker} (sequential event processing)
+ * - Isolated handlers without shared durable state requirements
+ *
+ * **Unsafe Usage:**
+ * - In-memory parallel/concurrent event brokers (e.g., p-queue with prefetch > 1)
+ *
+ * For concurrent in-process event processing, use the concurrency-safe memory
+ * backend from the `@arvo-tools/concurrent` package, which provides atomic lock
+ * operations suitable for parallel execution within a single process.
+ *
+ * **Unsuitable For:**
+ * - Multi-instance deployments
+ * - Distributed systems requiring shared state across processes
+ *
+ * For these scenarios, implement or use a database-backed memory backend
+ * (Redis, PostgreSQL, DynamoDB, etc.) that provides distributed state
+ * persistence and atomic locking across instances. You can also explore the
+ * Arvo tool eco-system `@arvo-tools`
  */
 export declare class SimpleMachineMemory<T extends Record<string, any> = Record<string, any>> implements IMachineMemory<T> {
     private readonly memoryMap;
     private readonly lockMap;
+    private readonly enableCleanup;
+    constructor(config?: {
+        enableCleanup?: boolean;
+    });
     /**
      * Gets stored state for a machine instance
      * @param id Machine instance ID
@@ -44,8 +70,6 @@ export declare class SimpleMachineMemory<T extends Record<string, any> = Record<
      * @throws {Error} When id is empty or undefined
      */
     unlock(id: string): Promise<boolean>;
-    /**
-     * Clears all stored data and locks
-     */
-    clear(key?: string): void;
+    cleanup(id: string): Promise<void>;
+    clear(): void;
 }

package/dist/MachineMemory/Simple.js

@@ -48,24 +48,50 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SimpleMachineMemory = void 0;
+var arvo_core_1 = require("arvo-core");
 /**
- * In-memory implementation of machine state storage for single-instance NodeJS apps.
- *
- * Best for: Container apps, request-scoped workflows, testing, demos
- * Not for: Multi-instance deployments, persistent workflows, distributed systems
+ * In-memory implementation of machine state storage for single-instance NodeJS applications.
  *
  * @example
  * const memory = new SimpleMachineMemory();
  * const orchestrator = createArvoOrchestrator({
  *   memory,
- *   executionunits: 1,
  *   machines: [workflow]
  * });
+ *
+ * @warning Concurrency Limitations
+ *
+ * This implementation is NOT concurrency-safe. Lock acquisition is not atomic,
+ * making it unsuitable for parallel event processing where multiple handlers
+ * might process events for the same workflow simultaneously.
+ *
+ * **Safe Usage:**
+ * - {@link SimpleEventBroker} (sequential event processing)
+ * - Isolated handlers without shared durable state requirements
+ *
+ * **Unsafe Usage:**
+ * - In-memory parallel/concurrent event brokers (e.g., p-queue with prefetch > 1)
+ *
+ * For concurrent in-process event processing, use the concurrency-safe memory
+ * backend from the `@arvo-tools/concurrent` package, which provides atomic lock
+ * operations suitable for parallel execution within a single process.
+ *
+ * **Unsuitable For:**
+ * - Multi-instance deployments
+ * - Distributed systems requiring shared state across processes
+ *
+ * For these scenarios, implement or use a database-backed memory backend
+ * (Redis, PostgreSQL, DynamoDB, etc.) that provides distributed state
+ * persistence and atomic locking across instances. You can also explore the
+ * Arvo tool eco-system `@arvo-tools`
  */
 var SimpleMachineMemory = /** @class */ (function () {
-    function SimpleMachineMemory() {
+    function SimpleMachineMemory(config) {
+        var _a;
         this.memoryMap = new Map();
         this.lockMap = new Map();
+        this.enableCleanup = true;
+        this.enableCleanup = (_a = config === null || config === void 0 ? void 0 : config.enableCleanup) !== null && _a !== void 0 ? _a : true;
     }
     /**
      * Gets stored state for a machine instance
@@ -141,17 +167,26 @@ var SimpleMachineMemory = /** @class */ (function () {
             });
         });
     };
-    /**
-     * Clears all stored data and locks
-     */
-    SimpleMachineMemory.prototype.clear = function (key) {
-        if (key) {
-            this.memoryMap.delete(key);
-            this.lockMap.delete(key);
-            return;
-        }
-        this.memoryMap.clear();
+    SimpleMachineMemory.prototype.cleanup = function (id) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                if (!this.enableCleanup) {
+                    (0, arvo_core_1.logToSpan)({
+                        level: 'INFO',
+                        message: 'Skipping cleanup due to config setting',
+                    });
+                    return [2 /*return*/];
+                }
+                this.memoryMap.delete(id);
+                this.lockMap.delete(id);
+                return [2 /*return*/];
+            });
+        });
+    };
+    // Clears all stored data and locks
+    SimpleMachineMemory.prototype.clear = function () {
         this.lockMap.clear();
+        this.memoryMap.clear();
     };
     return SimpleMachineMemory;
 }());

package/dist/MachineMemory/interface.d.ts

@@ -1,57 +1,156 @@
+import { Materializable } from '../types';
+export type MachineMemoryMetadata = {
+    /**
+     * Workflow instance identifier (same as event.subject).
+     * This unique identifier remains constant throughout the workflow's entire lifecycle.
+     */
+    subject: string;
+    /**
+     * Parent workflow's subject for tracking orchestration hierarchies.
+     *
+     * When materialized, a null value indicates this is a root workflow with no parent.
+     * A string value indicates this is a child workflow with the specified parent subject.
+     * A pending state means the parent context has not yet been determined.
+     *
+     * This enables hierarchical workflow tracking and cleanup strategies that differentiate
+     * between root workflows, child workflows, and workflows with pending parent determination.
+     */
+    parentSubject: Materializable<string | null>;
+    /**
+     * Identifier of the entity or process that initiated this workflow.
+     *
+     * When materialized, contains the initiator's identifier.
+     * A pending state means the initiator has not yet been determined.
+     */
+    initiator: Materializable<string>;
+    /**
+     * Orchestrator's source identifier (handler.source).
+     * Identifies which orchestrator type is managing this workflow instance.
+     */
+    source: string;
+};
 /**
- * Manages machine state memory operations with optimistic locking strategy.
- * Implements a "fail fast on acquire, be tolerant on release" approach for resource management.
- * @template T - Structure of stored data
+ * Manages workflow instance state with optimistic locking for orchestration handlers.
+ *
+ * Each workflow execution has a unique identifier (event.subject) that remains constant
+ * throughout its entire lifecycle. This interface uses that subject as the key for all
+ * state operations, enabling multiple concurrent executions of the same orchestrator
+ * to maintain isolated state.
+ *
+ * Implements "fail fast on acquire, be tolerant on release" locking philosophy:
+ * - Lock acquisition fails quickly after reasonable retries to prevent duplicate execution
+ * - Lock release tolerates failures since TTL-based expiry provides automatic recovery
+ *
+ * @template T - Structure of the workflow state data stored per instance
  */
-export interface IMachineMemory<T extends Record<string, any>> {
-    /**
-     * Gets state data for machine ID (event.subject).
-     * Should implement minimal retries (e.g. 2-3 attempts) with backoff for transient failures.
-     * Must distinguish between:
-     * - No data exists: Returns null (normal case for new machines)
-     * - Operation failed: Throws error after all retries exhausted
-     *
-     * Retry strategy should be quick with reasonable timeout to avoid blocking:
-     * - Few retry attempts (2-3)
-     * - Short backoff delays (e.g. 100ms with exponential backoff)
-     * - Total operation time under 1s
-     *
-     * @param id - Machine ID
-     * @returns null if no data exists, T if data found
-     * @throws Error if read operation fails after retries (e.g. connection error, permission denied)
-     */
-    read(id: string): Promise<T | null>;
-    /**
-     * Saves state data for machine ID (event.subject).
-     * Should fail fast - if write fails, throw error immediately.
-     * No retry logic as consistency is critical and caller handles failures.
-     * @param id - Machine ID
-     * @param data - State to save
-     * @param prevData - The previous snapshot of the data
+export interface IMachineMemory<T extends Record<string, any> = Record<string, any>> {
+    /**
+     * Retrieves persisted state for a specific workflow instance.
+     *
+     * The orchestrator calls this when resuming a workflow to load the context
+     * needed to continue from where it previously stopped. Returns null for
+     * new workflow instances that have no persisted state yet.
+     *
+     * Should implement minimal retries (2-3 attempts) with short backoff for
+     * transient failures to avoid blocking event processing. Total operation
+     * time should stay under 1 second.
+     *
+     * @param id - Workflow instance identifier (event.subject)
+     * @param metadata - Workflow context (subject, parent subject, source)
+     * @returns null if no state exists for this workflow instance, T if state found
+     * @throws Error if read operation fails after retries (connection error, permission denied, etc.)
+     */
+    read(id: string, metadata: MachineMemoryMetadata | null): Promise<T | null>;
+    /**
+     * Persists updated state for a specific workflow instance.
+     *
+     * Called after the orchestrator processes an event and needs to save
+     * the workflow's current context before terminating. The next event
+     * for this workflow will load this saved state to resume execution.
+     *
+     * Should fail fast without retries - if persistence fails, the orchestrator
+     * must know immediately to avoid state inconsistency. The caller handles
+     * failures through retry mechanisms or dead letter queues.
+     *
+     * @param id - Workflow instance identifier (event.subject)
+     * @param data - Current workflow state to persist
+     * @param prevData - Previous state snapshot (can be used for compare-and-swap or audit trails)
+     * @param metadata - Workflow context (subject, parent subject, source)
      * @throws Error if write operation fails
      */
-    write(id: string, data: T, prevData: T | null): Promise<void>;
+    write(id: string, data: T, prevData: T | null, metadata: MachineMemoryMetadata | null): Promise<void>;
     /**
-     * Acquires execution lock for machine ID (event.subject).
-     * Should implement reasonable retries with backoff for transient lock conflicts.
-     * Must fail fast after retry attempts exhausted - no long polling.
-     * @param id - Machine ID
-     * @returns True if lock acquired successfully
-     * @throws Error if lock operation fails (not same as lock denial)
+     * Acquires exclusive execution lock for a workflow instance.
+     *
+     * Prevents concurrent processing of the same workflow instance across
+     * distributed orchestrator instances. The orchestrator acquires this lock
+     * before reading/modifying state to ensure only one instance processes
+     * events for this workflow at any given time.
+     *
+     * Should implement reasonable retries (2-3 attempts) with backoff for
+     * transient lock conflicts, then fail fast. Returns false if another
+     * instance holds the lock after retries exhausted.
+     *
+     * CRITICAL: Should set TTL when acquiring lock (typically 30s-5m based on
+     * expected execution duration) to prevent permanent deadlocks if unlock fails.
+     *
+     * @param id - Workflow instance identifier (event.subject)
+     * @param metadata - Workflow context (subject, parent subject, source)
+     * @returns true if lock acquired successfully, false if lock held by another instance
+     * @throws Error if lock operation itself fails (not same as lock being unavailable)
      */
-    lock(id: string): Promise<boolean>;
+    lock(id: string, metadata: MachineMemoryMetadata | null): Promise<boolean>;
     /**
-     * Releases execution lock for machine ID (event.subject).
-     * Can retry a few times on failure but should not over-engineer.
-     * System will eventually recover even if unlock fails.
+     * Releases execution lock for a workflow instance.
+     *
+     * Called after the orchestrator finishes processing an event and persisting
+     * state. Can retry a few times on transient failures but should not block
+     * execution - the TTL-based expiry ensures eventual recovery even if unlock fails.
+     *
+     * The "be tolerant on release" philosophy means unlock failures don't cascade
+     * into workflow failures. The lock will auto-expire via TTL, allowing the
+     * workflow to resume after the timeout period.
+     *
+     * @param id - Workflow instance identifier (event.subject)
+     * @param metadata - Workflow context (subject, parent subject, source)
+     * @returns true if unlocked successfully, false if unlock failed (non-critical)
+     */
+    unlock(id: string, metadata: MachineMemoryMetadata | null): Promise<boolean>;
+    /**
+     * Optional cleanup hook invoked during successful workflow completion.
+     *
+     * The orchestrator calls this automatically when a workflow instance:
+     * 1. Reaches a final completion state (terminal state or returns output)
+     * 2. Successfully persists the final workflow state to storage
+     *
+     * This executes AFTER final state persistence but BEFORE the completion
+     * event is emitted back to the initiator. This ordering ensures the final
+     * state is durably saved before cleanup runs, while allowing cleanup logic
+     * to complete before the workflow signals completion to external systems.
+     *
+     * IMPORTANT: This hook is NOT called when orchestration execution fails
+     * (e.g., lock acquisition failure, state persistence failure, handler errors).
+     * It only executes for workflows that successfully reach their final state.
+     *
+     * Receives the same state transition data as write() to enable intelligent
+     * cleanup decisions based on how the workflow completed and what changed
+     * in the final step.
+     *
+     * This hook enables custom memory management strategies:
+     * - Mark state as eligible for garbage collection based on final state values
+     * - Archive completed workflows to cold storage with state-dependent retention
+     * - Implement conditional retention policies (e.g., keep failures longer than successes)
+     * - Extract specific data from final state for long-term analytics storage
+     * - Compare final vs previous state to determine appropriate storage tier
+     * - Trigger external cleanup processes with workflow completion context
      *
-     * Implementation MUST include lock expiry mechanism (TTL):
-     * - Set reasonable TTL when acquiring lock (e.g. 30s-5m based on execution patterns)
-     * - Ensure locks auto-expire to prevent deadlocks from unlock failures
-     * - Consider execution patterns when setting TTL to avoid premature expiry
+     * Implementations are not required to delete state immediately - they can
+     * implement whatever retention/archival strategy suits their operational needs.
      *
-     * @param id - Machine ID
-     * @returns True if unlocked successfully
+     * @param id - Workflow instance identifier (event.subject)
+     * @param data - Final workflow state that was just persisted
+     * @param prevData - Previous state before final persistence (null if this was first/only state)
+     * @param metadata - Workflow context (subject, parent subject, source)
      */
-    unlock(id: string): Promise<boolean>;
+    cleanup?(id: string, data: T, prevData: T | null, metadata: MachineMemoryMetadata | null): Promise<void>;
 }

package/dist/SyncEventResource/index.d.ts

@@ -1,6 +1,6 @@
 import type { Span } from '@opentelemetry/api';
 import { type ArvoEvent } from 'arvo-core';
-import type { IMachineMemory } from '../MachineMemory/interface';
+import type { IMachineMemory, MachineMemoryMetadata } from '../MachineMemory/interface';
 import type { AcquiredLockStatusType, ReleasedLockStatusType } from './types';
 /**
  * A synchronous event resource that manages machine memory state based on event subjects.
@@ -52,7 +52,7 @@ export declare class SyncEventResource<T extends Record<string, any>> {
      *
      * @throws {TransactionViolation} When lock acquisition fails due to system errors
      */
-    acquireLock(event: ArvoEvent, span?: Span): Promise<AcquiredLockStatusType>;
+    acquireLock(event: ArvoEvent, metadata: MachineMemoryMetadata, span?: Span): Promise<AcquiredLockStatusType>;
     /**
      * Retrieves the current state from memory for the given event subject.
      *
@@ -65,7 +65,7 @@ export declare class SyncEventResource<T extends Record<string, any>> {
      *
      * @throws {TransactionViolation} When the read operation fails due to storage errors
      */
-    acquireState(event: ArvoEvent, span?: Span): Promise<T | null>;
+    acquireState(event: ArvoEvent, metadata: MachineMemoryMetadata, span?: Span): Promise<T | null>;
     /**
      * Persists the updated memory state to distributed storage.
      *
@@ -76,7 +76,7 @@ export declare class SyncEventResource<T extends Record<string, any>> {
      *
      * @throws {TransactionViolation} When the write operation fails due to storage errors
      */
-    persistState(event: ArvoEvent, record: T, prevRecord: T | null, span?: Span): Promise<void>;
+    persistState(event: ArvoEvent, record: T, prevRecord: T | null, metadata: MachineMemoryMetadata, span?: Span): Promise<void>;
     /**
      * Validates that the event subject conforms to the ArvoOrchestrationSubject format.
      *
@@ -86,8 +86,6 @@ export declare class SyncEventResource<T extends Record<string, any>> {
      * distributed service architecture.
      *
      * @throws {ExecutionViolation} When the event subject format is invalid
-     *
-     * @protected
      */
     validateEventSubject(event: ArvoEvent, span?: Span): void;
     /**
@@ -103,8 +101,24 @@ export declare class SyncEventResource<T extends Record<string, any>> {
      *          - 'NOOP': No lock was acquired, so no operation was performed
      *          - 'RELEASED': Lock was successfully released
      *          - 'ERROR': Lock release failed, potential resource leak
+     */
+    releaseLock(event: ArvoEvent, acquiredLock: AcquiredLockStatusType | null, metadata: MachineMemoryMetadata, span?: Span): Promise<ReleasedLockStatusType>;
+    /**
+     * Invokes the optional cleanup hook after successful workflow completion.
+     *
+     * This method calls the memory implementation's cleanup hook if it exists, allowing
+     * implementations to perform custom memory management operations like archiving,
+     * marking for garbage collection, or implementing retention policies.
+     *
+     * Cleanup is a non-critical operation - failures are logged but do not throw exceptions
+     * or disrupt the workflow completion process. The assumption is that cleanup operations
+     * can be retried later or handled through separate maintenance processes.
      *
-     * @protected
+     * @param event - The ArvoEvent that triggered workflow completion
+     * @param record - Final workflow state that was just persisted
+     * @param prevRecord - Previous state before final persistence
+     * @param metadata - Workflow context (subject, parent subject, source)
+     * @param span - Optional OpenTelemetry span for observability
      */
-    releaseLock(event: ArvoEvent, acquiredLock: AcquiredLockStatusType | null, span?: Span): Promise<ReleasedLockStatusType>;
+    cleanup(event: ArvoEvent, record: T, prevRecord: T | null, metadata: MachineMemoryMetadata, span?: Span): Promise<void>;
 }

package/dist/SyncEventResource/index.js

@@ -91,7 +91,7 @@ var SyncEventResource = /** @class */ (function () {
      *
      * @throws {TransactionViolation} When lock acquisition fails due to system errors
      */
-    SyncEventResource.prototype.acquireLock = function (event, span) {
+    SyncEventResource.prototype.acquireLock = function (event, metadata, span) {
         return __awaiter(this, void 0, void 0, function () {
             var acquired, e_1;
             return __generator(this, function (_a) {
@@ -111,7 +111,7 @@ var SyncEventResource = /** @class */ (function () {
                             level: 'INFO',
                             message: 'Acquiring lock for the event',
                         });
-                        return [4 /*yield*/, this.memory.lock(event.subject)];
+                        return [4 /*yield*/, this.memory.lock(event.subject, metadata)];
                     case 2:
                         acquired = _a.sent();
                         return [2 /*return*/, acquired ? 'ACQUIRED' : 'NOT_ACQUIRED'];
@@ -139,7 +139,7 @@ var SyncEventResource = /** @class */ (function () {
      *
      * @throws {TransactionViolation} When the read operation fails due to storage errors
      */
-    SyncEventResource.prototype.acquireState = function (event, span) {
+    SyncEventResource.prototype.acquireState = function (event, metadata, span) {
         return __awaiter(this, void 0, void 0, function () {
             var e_2;
             return __generator(this, function (_a) {
@@ -150,7 +150,7 @@ var SyncEventResource = /** @class */ (function () {
                             level: 'INFO',
                             message: 'Reading machine state for the event',
                         }, span);
-                        return [4 /*yield*/, this.memory.read(event.subject)];
+                        return [4 /*yield*/, this.memory.read(event.subject, metadata)];
                     case 1: return [2 /*return*/, _a.sent()];
                     case 2:
                         e_2 = _a.sent();
@@ -174,7 +174,7 @@ var SyncEventResource = /** @class */ (function () {
      *
      * @throws {TransactionViolation} When the write operation fails due to storage errors
      */
-    SyncEventResource.prototype.persistState = function (event, record, prevRecord, span) {
+    SyncEventResource.prototype.persistState = function (event, record, prevRecord, metadata, span) {
         return __awaiter(this, void 0, void 0, function () {
             var e_3;
             return __generator(this, function (_a) {
@@ -185,7 +185,7 @@ var SyncEventResource = /** @class */ (function () {
                             level: 'INFO',
                             message: 'Persisting machine state to the storage',
                         }, span);
-                        return [4 /*yield*/, this.memory.write(event.subject, record, prevRecord)];
+                        return [4 /*yield*/, this.memory.write(event.subject, record, prevRecord, metadata)];
                     case 1:
                         _a.sent();
                         return [3 /*break*/, 3];
@@ -210,8 +210,6 @@ var SyncEventResource = /** @class */ (function () {
      * distributed service architecture.
      *
      * @throws {ExecutionViolation} When the event subject format is invalid
-     *
-     * @protected
      */
     SyncEventResource.prototype.validateEventSubject = function (event, span) {
         (0, arvo_core_1.logToSpan)({
@@ -236,10 +234,8 @@ var SyncEventResource = /** @class */ (function () {
      *          - 'NOOP': No lock was acquired, so no operation was performed
      *          - 'RELEASED': Lock was successfully released
      *          - 'ERROR': Lock release failed, potential resource leak
-     *
-     * @protected
      */
-    SyncEventResource.prototype.releaseLock = function (event, acquiredLock, span) {
+    SyncEventResource.prototype.releaseLock = function (event, acquiredLock, metadata, span) {
         return __awaiter(this, void 0, void 0, function () {
             var err_1;
             return __generator(this, function (_a) {
@@ -255,7 +251,7 @@ var SyncEventResource = /** @class */ (function () {
                         _a.label = 1;
                     case 1:
                         _a.trys.push([1, 3, , 4]);
-                        return [4 /*yield*/, this.memory.unlock(event.subject)];
+                        return [4 /*yield*/, this.memory.unlock(event.subject, metadata)];
                     case 2:
                         _a.sent();
                         (0, arvo_core_1.logToSpan)({
@@ -275,6 +271,63 @@ var SyncEventResource = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Invokes the optional cleanup hook after successful workflow completion.
+     *
+     * This method calls the memory implementation's cleanup hook if it exists, allowing
+     * implementations to perform custom memory management operations like archiving,
+     * marking for garbage collection, or implementing retention policies.
+     *
+     * Cleanup is a non-critical operation - failures are logged but do not throw exceptions
+     * or disrupt the workflow completion process. The assumption is that cleanup operations
+     * can be retried later or handled through separate maintenance processes.
+     *
+     * @param event - The ArvoEvent that triggered workflow completion
+     * @param record - Final workflow state that was just persisted
+     * @param prevRecord - Previous state before final persistence
+     * @param metadata - Workflow context (subject, parent subject, source)
+     * @param span - Optional OpenTelemetry span for observability
+     */
+    SyncEventResource.prototype.cleanup = function (event, record, prevRecord, metadata, span) {
+        return __awaiter(this, void 0, void 0, function () {
+            var err_2;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!this.memory.cleanup) {
+                            (0, arvo_core_1.logToSpan)({
+                                level: 'INFO',
+                                message: 'Cleanup hook not implemented by memory backend, skipping cleanup operation',
+                            }, span);
+                            return [2 /*return*/];
+                        }
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'INFO',
+                            message: 'Invoking cleanup hook for completed workflow',
+                        }, span);
+                        return [4 /*yield*/, this.memory.cleanup(event.subject, record, prevRecord, metadata)];
+                    case 2:
+                        _a.sent();
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'INFO',
+                            message: 'Cleanup hook completed successfully',
+                        }, span);
+                        return [3 /*break*/, 4];
+                    case 3:
+                        err_2 = _a.sent();
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'ERROR',
+                            message: "Cleanup operation failed (non-critical): ".concat(err_2.message),
+                        }, span);
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
     return SyncEventResource;
 }());
 exports.SyncEventResource = SyncEventResource;

package/dist/index.d.ts

@@ -20,11 +20,11 @@ import { IMachineExectionEngine } from './MachineExecutionEngine/interface';
 import { ExecuteMachineInput, ExecuteMachineOutput } from './MachineExecutionEngine/types';
 import { SimpleMachineMemory } from './MachineMemory/Simple';
 import { TelemetredSimpleMachineMemory } from './MachineMemory/TelemetredSimple';
-import { IMachineMemory } from './MachineMemory/interface';
+import { IMachineMemory, MachineMemoryMetadata } from './MachineMemory/interface';
 import { MachineRegistry } from './MachineRegistry';
 import { IMachineRegistry } from './MachineRegistry/interface';
 import { ConfigViolation, ContractViolation, ExecutionViolation } from './errors';
-import { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions, EventHandlerFactory, PartialExcept } from './types';
+import { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions, EventHandlerFactory, Materializable, Materialized, PartialExcept } from './types';
 import { coalesce, coalesceOrDefault, getValueOrDefault, isNullOrUndefined } from './utils';
 import { SimpleEventBroker } from './utils/SimpleEventBroker';
 import { createSimpleEventBroker } from './utils/SimpleEventBroker/helper';
@@ -34,4 +34,4 @@ declare const xstate: {
     emit: typeof emit;
     assign: typeof assign;
 };
-export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, ArvoEventHandlerOpenTelemetryOptions, EventHandlerFactory, ContractViolation, ConfigViolation, ExecutionViolation, ArvoMachine, setupArvoMachine, ArvoMachineContext, EnqueueArvoEventActionParam, IMachineRegistry, MachineRegistry, MachineExecutionEngine, IMachineExectionEngine, ExecuteMachineInput, ExecuteMachineOutput, IMachineMemory, SimpleMachineMemory, MachineMemoryRecord, ArvoOrchestratorParam, TransactionViolation, TransactionViolationCause, ArvoOrchestrator, createArvoOrchestrator, SimpleEventBroker, createSimpleEventBroker, TelemetredSimpleMachineMemory, xstate, ArvoResumable, createArvoResumable, ArvoResumableHandler, ArvoResumableState, ArvoDomain, resolveEventDomain, isTransactionViolationError, OrchestrationExecutionStatus, ArvoEventHandlerOtelSpanOptions, runArvoTestSuites, ArvoTestStep, ArvoTestCase, ArvoTestConfig, ArvoTestSuite, ArvoTestResult, IArvoTestFramework, };
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, ArvoEventHandlerOpenTelemetryOptions, EventHandlerFactory, ContractViolation, ConfigViolation, ExecutionViolation, ArvoMachine, setupArvoMachine, ArvoMachineContext, EnqueueArvoEventActionParam, IMachineRegistry, MachineRegistry, MachineExecutionEngine, IMachineExectionEngine, ExecuteMachineInput, ExecuteMachineOutput, IMachineMemory, SimpleMachineMemory, MachineMemoryRecord, ArvoOrchestratorParam, TransactionViolation, TransactionViolationCause, ArvoOrchestrator, createArvoOrchestrator, SimpleEventBroker, createSimpleEventBroker, TelemetredSimpleMachineMemory, xstate, ArvoResumable, createArvoResumable, ArvoResumableHandler, ArvoResumableState, ArvoDomain, resolveEventDomain, isTransactionViolationError, OrchestrationExecutionStatus, ArvoEventHandlerOtelSpanOptions, runArvoTestSuites, ArvoTestStep, ArvoTestCase, ArvoTestConfig, ArvoTestSuite, ArvoTestResult, IArvoTestFramework, Materializable, Materialized, MachineMemoryMetadata, };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runArvoTestSuites = exports.OrchestrationExecutionStatus = exports.isTransactionViolationError = exports.resolveEventDomain = exports.ArvoDomain = exports.createArvoResumable = exports.ArvoResumable = exports.xstate = exports.TelemetredSimpleMachineMemory = exports.createSimpleEventBroker = exports.SimpleEventBroker = exports.createArvoOrchestrator = exports.ArvoOrchestrator = exports.TransactionViolationCause = exports.TransactionViolation = exports.SimpleMachineMemory = exports.MachineExecutionEngine = exports.MachineRegistry = exports.setupArvoMachine = exports.ArvoMachine = exports.ExecutionViolation = exports.ConfigViolation = exports.ContractViolation = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
+exports.Materialized = exports.runArvoTestSuites = exports.OrchestrationExecutionStatus = exports.isTransactionViolationError = exports.resolveEventDomain = exports.ArvoDomain = exports.createArvoResumable = exports.ArvoResumable = exports.xstate = exports.TelemetredSimpleMachineMemory = exports.createSimpleEventBroker = exports.SimpleEventBroker = exports.createArvoOrchestrator = exports.ArvoOrchestrator = exports.TransactionViolationCause = exports.TransactionViolation = exports.SimpleMachineMemory = exports.MachineExecutionEngine = exports.MachineRegistry = exports.setupArvoMachine = exports.ArvoMachine = exports.ExecutionViolation = exports.ConfigViolation = exports.ContractViolation = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
 var xstate_1 = require("xstate");
 var ArvoDomain_1 = require("./ArvoDomain");
 Object.defineProperty(exports, "ArvoDomain", { enumerable: true, get: function () { return ArvoDomain_1.ArvoDomain; } });
@@ -42,6 +42,8 @@ var errors_1 = require("./errors");
 Object.defineProperty(exports, "ConfigViolation", { enumerable: true, get: function () { return errors_1.ConfigViolation; } });
 Object.defineProperty(exports, "ContractViolation", { enumerable: true, get: function () { return errors_1.ContractViolation; } });
 Object.defineProperty(exports, "ExecutionViolation", { enumerable: true, get: function () { return errors_1.ExecutionViolation; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "Materialized", { enumerable: true, get: function () { return types_1.Materialized; } });
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "coalesce", { enumerable: true, get: function () { return utils_1.coalesce; } });
 Object.defineProperty(exports, "coalesceOrDefault", { enumerable: true, get: function () { return utils_1.coalesceOrDefault; } });

package/dist/types.d.ts

@@ -2,6 +2,46 @@ import type { SpanOptions } from '@opentelemetry/api';
 import type { ArvoEvent } from 'arvo-core';
 import type IArvoEventHandler from './IArvoEventHandler';
 export type NonEmptyArray<T> = [T, ...T[]];
+/**
+ * Represents a value that may or may not have been materialized yet.
+ *
+ * This type models the distinction between a value whose information is still pending
+ * and one that has been fully materialized with its concrete value. The materialized
+ * value itself can be of any type, including null or undefined.
+ *
+ * @template T The type of the value once materialized
+ *
+ * @remarks
+ * Use this type when you need to explicitly track whether information has been
+ * acquired or computed, distinguishing between "we haven't obtained this yet"
+ * and "we have obtained this, and here is the value".
+ *
+ * The 'pending' state indicates materialization has not yet occurred.
+ * The 'materialized' state indicates the value has been obtained and is available.
+ *
+ * This is distinct from optional or nullable types, which represent whether a value
+ * exists, rather than whether the information about that value has been determined.
+ */
+export type Materializable<T> = {
+    state: 'pending';
+} | {
+    state: 'resolved';
+    value: T;
+};
+export declare const Materialized: {
+    pending: <T>() => Extract<Materializable<T>, {
+        state: "pending";
+    }>;
+    resolved: <T>(value: T) => Extract<Materializable<T>, {
+        state: "resolved";
+    }>;
+    isPending: <T extends Materializable<any>>(value: T) => value is Extract<T, {
+        state: "pending";
+    }>;
+    isResolved: <T extends Materializable<any>>(value: T) => value is Extract<T, {
+        state: "resolved";
+    }>;
+};
 /**
  * Makes properties optional except specified keys
  *

package/dist/types.js

@@ -1,2 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Materialized = void 0;
+exports.Materialized = {
+    pending: function () { return ({ state: 'pending' }); },
+    resolved: function (value) { return ({ state: 'resolved', value: value }); },
+    isPending: function (value) {
+        return value.state === 'pending';
+    },
+    isResolved: function (value) {
+        return value.state === 'resolved';
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "3.0.26",
+  "version": "3.0.27",
   "description": "A complete set of orthogonal event handler and orchestration primitives for Arvo based applications, featuring declarative state machines (XState), imperative resumables for agentic workflows, contract-based routing, OpenTelemetry observability, and in-memory event broker for building composable event-driven architectures.",
   "main": "dist/index.js",
   "repository": {
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "arvo-core": "3.0.26",
+    "arvo-core": "3.0.27",
     "uuid": "11.1.0",
     "xstate": "5.25.0",
     "zod": "3.25.76",