arvo-event-handler 3.0.18 → 3.0.20

package/.nvmrc

@@ -0,0 +1 @@
+v20.17.0

package/Dockerfile

@@ -0,0 +1,7 @@
+ARG NODE_VERSION=18
+FROM node:${NODE_VERSION}-alpine
+WORKDIR /app
+COPY node_modules ./node_modules
+COPY package*.json ./
+COPY . .
+RUN npm run build

package/Dockerfile.install

@@ -0,0 +1,23 @@
+ARG NODE_VERSION=18
+FROM node:${NODE_VERSION}-alpine
+
+RUN npm install -g @aikidosec/safe-chain
+RUN safe-chain setup-ci
+
+WORKDIR /install
+COPY package*.json ./
+COPY .npmrc ./
+
+# Build arguments for optional package installation
+ARG PACKAGES=""
+ARG DEV=""
+
+# Install dependencies in isolation
+# Lifecycle scripts can run but have no access to host secrets
+# If PACKAGES specified: install those specific packages
+# Otherwise: install all dependencies from package.json
+RUN if [ -n "$PACKAGES" ]; then \
+        [ "$DEV" = "true" ] && npm install -D $PACKAGES || npm install $PACKAGES; \
+    else \
+        npm install; \
+    fi

package/Dockerfile.test

@@ -0,0 +1,7 @@
+ARG NODE_VERSION=18
+FROM node:${NODE_VERSION}-alpine
+WORKDIR /app
+COPY node_modules ./node_modules
+COPY package*.json ./
+COPY . .
+CMD ["npm", "test"]

package/README.md

@@ -1,102 +1,142 @@
-# Arvo Event Handler
-
-The `arvo-event-handler` package serves as the comprehensive orchestration and event processing foundation for building sophisticated, reliable event-driven systems within the Arvo architecture. This package provides a complete toolkit of components that work seamlessly together to handle everything from simple event processing to complex distributed workflow orchestration, all while maintaining strict type safety, comprehensive observability, and robust error handling.
-
 [![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-white.svg)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 
-## Installation
-
-Install the package along with its core dependency:
-
-```bash
-npm install arvo-event-handler arvo-core
-```
-
-```bash
-yarn add arvo-event-handler arvo-core
-```
-
-## The Event Handlers
-
-The Arvo event handling architecture is based on three handler patterns.
-
-### 1. Simple Event Handler
-
-This kind of event handling is provided by [`ArvoEventHandler`](src/ArvoEventHandler/README.md). This approach transforms ArvoContract definitions into stateless, pure function handlers that process individual events in isolation. Each handler binds to a specific contract, validates incoming events against schema definitions, executes business logic, and returns response events. It supports multiple contract versions for backward compatibility and enables multi-domain event broadcasting for parallel processing pipelines. This pattern is ideal for microservices, API endpoints, and any scenario where you need reliable, contract-enforced event processing without complex state management or workflow coordination.
-
-### 2. State-machine based workflow orchestration
+# Arvo - A toolkit for event driven applications (arvo-event-handler)
 
-This kind of event handling is provided by [`ArvoMachine`](src/ArvoMachine/README.md) which defines the state machine and [`ArvoOrchestrator`](src/ArvoOrchestrator/README.md) which executes it. This approach uses declarative state machine definitions to model complex business processes with multiple states, transitions, and conditional logic. ArvoMachine creates XState-compatible machines with Arvo-specific constraints and contract bindings, while ArvoOrchestrator provides the runtime environment for executing these machines with distributed state persistence, resource locking, and comprehensive lifecycle management. This pattern excels at complex workflows with parallel states, timing requirements, conditional branching, and scenarios where visual workflow modeling and deterministic state transitions are crucial for business process management.
+The orchestration and event processing foundation for [Arvo](https://www.arvo.land/), providing everything from simple event handlers to complex workflow orchestration with state machines and imperative resumables.
 
-### 3. Dynamic stateful event handling and orchestration
+This package provides three core handler patterns and essential infrastructure for building reliable event-driven systems:
 
-This kind of event handling is provided by [`ArvoResumable`](src/ArvoResumable/README.md). The event handling is a different approach to workflow processing and complements the state machine pattern by offering an imperative programming model where developers write handler functions that explicitly manage workflow state through context objects. Instead of defining states and transitions declaratively, you write code that examines incoming events, updates workflow context, and decides what actions to take next. This approach provides direct control over workflow logic, making it easier to debug and understand for teams familiar with traditional programming patterns, while still offering the same reliability, observability, and distributed coordination features as state machine orchestration.
+**ArvoEventHandler** - Stateless event processors that transform contract-defined events. Perfect for microservices, API endpoints, and simple request-response patterns.
 
-## Core Infrastructure Components
+**ArvoOrchestrator** - Declarative state machine-based workflow orchestration using XState. Ideal for complex business processes with clear states, transitions, and parallel execution.
 
-Beyond the three main handler patterns, the package includes essential infrastructure components that enable robust distributed system operation.
+**ArvoResumable** - Imperative workflow handlers with explicit state management. Best for dynamic workflows, AI-driven decision logic, and teams preferring traditional programming patterns.
 
-### Memory - State Persistance
-
-The [`IMachineMemory`](src/MachineMemory/README.md) interface defines how workflow state gets persisted and coordinated across distributed instances. It implements an optimistic locking strategy with "fail fast on acquire, be tolerant on release" semantics, ensuring data consistency while enabling system recovery from transient failures. 
-
-This package includes `SimpleMachineMemory` for development/ prototyping scenarios and provides example for implementing cloud-based production-ready distributed storage solutions.
-
-### Error Handling 
-
-The Arvo event handling system uses a layered error handling approach that provides clear boundaries between different types of failures, enabling appropriate responses at each level.
-
-**Business Logic Failures** are expected outcomes in your business processes and should be modeled as explicit events in your `ArvoContract` definitions. For example, when a user already exists during registration or a payment is declined, these represent normal business scenarios rather than system errors. By defining these as emittable events, downstream consumers can distinguish between business logic outcomes and actual system problems, enabling appropriate handling logic for each scenario.
-
-**Transient System Errors** occur when underlying infrastructure or external services fail temporarily. Database connection timeouts, API unavailability, or network issues fall into this category. The system automatically converts uncaught exceptions into standardized system error events with the type pattern `sys.{contract.type}.error`. These events carry error details and can trigger retry mechanisms, circuit breakers, or alternative processing paths while maintaining the event-driven flow of your system.
-
-**Violations** represent critical failures that require immediate attention and cannot be handled through normal event processing patterns. The system defines four distinct violation types to help you identify and respond to different categories of critical issues:
-
-- `ContractViolation` occurs when event data fails contract validation, indicating schema mismatches between services. This typically signals version incompatibilities or data corruption that requires developer intervention to resolve.
+## Installation
+```bash
+npm install arvo-event-handler arvo-core xstate@5 zod@3
+```
 
-- `ConfigViolation` happens when events are routed to handlers that cannot process them, revealing system topology or configuration problems that need infrastructure-level fixes.
+## Quick Start
+
+### Simple Event Handler
+```typescript
+import { createArvoEventHandler } from 'arvo-event-handler';
+import { createArvoContract } from 'arvo-core';
+import { z } from 'zod';
+
+const contract = createArvoContract({
+  uri: '#/contracts/user',
+  type: 'user.validate',
+  versions: {
+    '1.0.0': {
+      accepts: z.object({ email: z.string().email() }),
+      emits: {
+        'evt.user.validate.success': z.object({ valid: z.boolean() })
+      }
+    }
+  }
+});
+
+const handler = createArvoEventHandler({
+  contract,
+  executionunits: 0,
+  handler: {
+    '1.0.0': async ({ event }) => ({
+      type: 'evt.user.validate.success',
+      data: { valid: true }
+    })
+  }
+});
+```
 
-- `ExecutionViolation` provides a mechanism for custom error handling when your business logic encounters scenarios that cannot be resolved through normal event patterns and require special intervention.
+### State Machine Orchestrator
+```typescript
+import { createArvoOrchestrator, setupArvoMachine } from 'arvo-event-handler';
+import { createArvoOrchestratorContract } from 'arvo-core';
+
+const orchestratorContract = createArvoOrchestratorContract({
+  uri: '#/orchestrator/workflow',
+  name: 'workflow',
+  versions: {
+    '1.0.0': {
+      init: z.object({ userId: z.string() }),
+      complete: z.object({ result: z.string() })
+    }
+  }
+});
+
+const machine = setupArvoMachine({
+  contracts: {
+    self: orchestratorContract.version('1.0.0'),
+    services: { /* service contracts */ }
+  }
+}).createMachine({
+  // XState machine definition
+});
+
+const orchestrator = createArvoOrchestrator({
+  machines: [machine],
+  memory, // IMachineMemory implementation
+  executionunits: 0
+});
+```
 
-- `TransactionViolation` is raised specifically by `ArvoOrchestrator` and `ArvoResumable` when state persistence operations fail. The accompanying `TransactionViolationCause` provides detailed information about what went wrong, allowing you to implement appropriate recovery strategies for distributed transaction failures.
+### Imperative Resumable
+```typescript
+import { createArvoResumable } from 'arvo-event-handler';
+
+const resumable = createArvoResumable({
+  contracts: {
+    self: orchestratorContract,
+    services: { /* service contracts */ }
+  },
+  memory,
+  executionunits: 0,
+  handler: {
+    '1.0.0': async ({ input, service, context }) => {
+      if (input) {
+        return {
+          context: { userId: input.data.userId },
+          services: [{ type: 'user.validate', data: { /* ... */ } }]
+        };
+      }
+      // Handle service responses and return output
+    }
+  }
+});
+```
 
+## Additional Core Components
 
-### Local Developement & Testing
+**IMachineMemory** - State persistence interface with optimistic locking for distributed workflow coordination. Includes `SimpleMachineMemory` for local development.
 
-The package provides `createSimpleEventBroker` utility which creates local event buses perfect for testing, development, and single-function workflow coordination. It enables comprehensive integration testing without external message brokers while supporting the same event patterns used in production distributed systems.
+**Error Handling** - Three-tier system: business logic failures as contract events, transient errors as system events, and violations for critical failures requiring immediate intervention.
 
+**SimpleEventBroker** - Local in-memory FIFO queue-based event broker for testing and development without external message infrastructure. Also suitable for production deployments with limited scale (≤1000 users).
 
-## Architecture Principles
+**SimpleMachineMemory** - Local in-memory hash map based storage for testing and development without external database infrastructure.
 
-The entire system follows consistent architectural principles that promote reliability and maintainability. All handlers implement the signature `ArvoEvent => Promise<{ events: ArvoEvent[] }>`, creating predictable event flow patterns throughout the system. Contract-first development ensures all service interactions are explicitly defined and validated, eliminating common integration issues while providing compile-time type safety.
+All handlers implement the same interface `IArvoEventHandler` regardless of complexity, enabling consistent patterns across your entire system. Contract-first development ensures type safety and validation at every boundary. Built-in OpenTelemetry integration provides complete observability. State management through pluggable interfaces supports any storage backend from memory to distributed databases.
 
-Multi-domain event broadcasting allows single handlers to create events for different processing contexts simultaneously, supporting patterns like audit trails, analytics processing, and external system integration. The comprehensive observability integration provides operational visibility through OpenTelemetry spans, structured logging, and performance metrics collection.
+The same handler code works locally with in-memory brokers during development and in production with distributed message systems and persistent state stores.
 
-The functional architecture enables natural horizontal scaling since handlers operate as pure functions with consistent behavior regardless of deployment location. State management through pluggable persistence interfaces supports various scaling strategies from single-instance deployments to sophisticated distributed configurations.
+## What is `arvo-event-handler`?
 
-## Documentation and Resources
+The `arvo-event-handler` is one of the two foundational packages in the Arvo ecosystem, alongside `arvo-core`. Together, they provide the complete foundation for building event-driven applications that are distributed system-compliant. Explore additional tools and integrations in the `@arvo-tools` namespace.
 
-| Component | Documentation | When to Use |
-|-----------|---------------|-------------|
-| **ArvoEventHandler** | [Simple Event Processing](src/ArvoEventHandler/README.md) | Stateless services, API endpoints, microservices, simple request-response processing |
-| **ArvoMachine** | [State Machine Workflows](src/ArvoMachine/README.md) | Complex business processes with multiple states, conditional branching, parallel execution, visual workflow modeling |
-| **ArvoOrchestrator** | [Workflow Orchestration](src/ArvoOrchestrator/README.md) | Running state machines in production, distributed workflow coordination, comprehensive lifecycle management |
-| **ArvoResumable** | [Handler-Based Workflows](src/ArvoResumable/README.md) | Dynamic workflows, imperative programming preference, rapid prototyping, teams familiar with traditional programming patterns |
-| **MachineMemory** | [State Persistence Interface](src/MachineMemory/README.md) | Custom state storage requirements, distributed locking strategies, production persistence implementations |
+Learn more at the official Arvo website: [https://www.arvo.land/](https://www.arvo.land/)
 
-## Package Information
+## Documentation
 
-| Resource | Link |
-|----------|------|
-| Package | [npm package](https://www.npmjs.com/package/arvo-event-handler) |
-| Repository | [GitHub repository](https://github.com/SaadAhmad123/arvo-event-handler) |
-| Documentation | [Complete documentation](https://saadahmad123.github.io/arvo-event-handler/index.html) |
-| Core Package | [arvo-core documentation](https://saadahmad123.github.io/arvo-core/index.html) |
+Complete guides, API reference, and tutorials at [https://www.arvo.land/](https://www.arvo.land/)
 
 ## License
 
-This package is available under the MIT License. For more details, refer to the [LICENSE.md](LICENSE.md) file in the project repository.
+MIT - See [LICENSE.md](LICENSE.md)
+
+---
 
 ### SonarCloud Metrics
 

package/dist/ArvoMachine/createMachine.d.ts

@@ -132,6 +132,7 @@ export declare function setupArvoMachine<TContext extends MachineContext, TSelfC
         enqueueArvoEvent: EnqueueArvoEventActionParam;
     }>, ToParameterizedObject<TGuards>, never, TTag, InferVersionedArvoContract<TSelfContract>["accepts"], z.input<TSelfContract["emits"][ReturnType<typeof ArvoOrchestratorEventTypeGen.complete<ExtractOrchestratorType<TSelfContract["accepts"]["type"]>>>]> & {
         __id?: CreateArvoEvent<Record<string, unknown>, string>["id"];
+        __executionunits?: CreateArvoEvent<Record<string, unknown>, string>["executionunits"];
     }, InferServiceContract<TServiceContracts>["emitted"], TMeta>>(config: TConfig & {
         id: string;
         version?: TSelfContract["version"];
@@ -146,10 +147,12 @@ export declare function setupArvoMachine<TContext extends MachineContext, TSelfC
         type: K_2;
         params: TGuards[K_2];
     }; }>, never, {} | {
-        [x: string]: {} | any | {
-            [x: string]: {} | any | any;
+        [x: string]: {} | /*elided*/ any | {
+            [x: string]: {} | /*elided*/ any | /*elided*/ any;
         };
     } | {
-        [x: string]: {} | any | any;
+        [x: string]: {} | {
+            [x: string]: {} | /*elided*/ any | /*elided*/ any;
+        } | /*elided*/ any;
     }, TTag, TSelfContract["accepts"]["schema"]["_output"], { [K_3 in string & keyof TSelfContract["emits"]]: import("arvo-core").InferArvoEvent<import("arvo-core").ArvoEvent<TSelfContract["emits"][K_3]["_output"], Record<string, any>, K_3>>; }[`arvo.orc.${ExtractOrchestratorType<TSelfContract["accepts"]["type"]>}.done`]["data"], { [K_4 in keyof TServiceContracts]: EnqueueArvoEventActionParam<z.input<TServiceContracts[K_4]["accepts"]["schema"]>, TServiceContracts[K_4]["accepts"]["type"], Record<string, string | number | boolean | null>>; }[keyof TServiceContracts], TMeta, any>>;
 };

package/dist/ArvoOrchestrator/index.js

@@ -182,6 +182,7 @@ var ArvoOrchestrator = /** @class */ (function () {
                                         domain: orchestrationParentSubject
                                             ? [arvo_core_1.ArvoOrchestrationSubject.parse(orchestrationParentSubject).execution.domain]
                                             : [null],
+                                        executionunits: executionResult.finalOutput.__executionunits,
                                     });
                                 }
                                 emittables = (0, createEmitableEvent_1.processRawEventsIntoEmittables)({

package/dist/ArvoResumable/index.js

@@ -241,6 +241,7 @@ var ArvoResumable = /** @class */ (function () {
                                                 domain: orchestrationParentSubject
                                                     ? [arvo_core_1.ArvoOrchestrationSubject.parse(orchestrationParentSubject).execution.domain]
                                                     : [null],
+                                                executionunits: executionResult.output.__executionunits,
                                             });
                                         }
                                         emittables = (0, createEmitableEvent_1.processRawEventsIntoEmittables)({

package/dist/ArvoResumable/types.d.ts

@@ -97,6 +97,7 @@ type Handler<TState extends ArvoResumableState<Record<string, any>>, TSelfContra
         [L in keyof InferVersionedArvoContract<TSelfContract>['emits']]: EnqueueArvoEventActionParam<InferVersionedArvoContract<TSelfContract>['emits'][L]['data'], InferVersionedArvoContract<TSelfContract>['emits'][L]['type']>['data'];
     }[keyof InferVersionedArvoContract<TSelfContract>['emits']] & {
         __id?: CreateArvoEvent<Record<string, unknown>, string>['id'];
+        __executionunits?: CreateArvoEvent<Record<string, unknown>, string>['executionunits'];
     };
     /**
      * Service call events to emit.

package/justfile

@@ -0,0 +1,126 @@
+# Docker-Isolated NPM Development Environment
+#
+# This justfile provides Docker-based sandbox isolation for npm operations to protect against
+# supply chain attacks during local development on local machine. All npm operations 
+# run in ephemeral containers with no access to your host filesystem, environment 
+# variables, or secrets.
+#
+# WHAT THIS PROTECTS AGAINST:
+# - Malicious install scripts stealing SSH keys, AWS credentials, or other secrets
+# - Package typosquatting attacks that exfiltrate local environment variables
+# - Compromised packages accessing your home directory during installation
+# - Supply chain attacks that attempt to modify files outside node_modules
+# - Malicious code execution during build and test phases (runs in isolated containers)
+#
+# WHAT THIS DOESN'T PROTECT AGAINST:
+# - Malicious code in package runtime logic when you actually run your application
+# - Sophisticated obfuscated malware that bypasses basic pattern detection
+# - Attacks that only activate in production environments
+# 
+# **Disclaimer:** This does not gate against malware in node_modules or in your code 
+# (you need to update the Docker.install to add that gate as per your requirments 
+# - if you need one). Rather, its scope is **strictly limited** to attempting to protect
+# the host device from exposure if the malware gets excuted.
+#
+# HOW IT WORKS:
+# INSTALL PHASE:
+#   1. npm install runs inside a clean Docker container with no volume mounts
+#   2. Basic placeholder malware detection (so the you can add more complex methods if you want) scans run after installation completes
+#   3. Only node_modules and package files are extracted back to your host
+#   4. Container is destroyed, leaving no trace of potentially malicious install scripts
+#
+# BUILD PHASE:
+#   1. Source code and dependencies are copied into a fresh container
+#   2. Build process (TypeScript compilation, bundling, etc.) runs isolated
+#   3. Only the compiled output (dist/) is extracted back to host
+#   4. Any malicious code that tries to run during build is contained
+#
+# TEST PHASE:
+#   1. Tests run in an isolated container with optional .env file mounting
+#   2. Test dependencies can't access your host system during execution
+#   3. Container is destroyed after tests complete
+#   4. Secrets in .env are passed at runtime, never baked into image layers
+#
+# USAGE:
+#   just install                    # Install all dependencies from package.json
+#   just install <package>          # Install specific package(s)
+#   just install-dev <package>      # Install as dev dependency
+#   just test                       # Run tests in isolated container
+#   just build                      # Build project in isolated container
+#   just clean                      # Remove node_modules
+
+node_version := `cat .nvmrc | tr -d 'v\n\r'`
+
+install *PACKAGES:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    NODE_VERSION={{node_version}}
+    echo "Installing dependencies with Node $NODE_VERSION..."
+    docker build --progress=plain -f Dockerfile.install --build-arg NODE_VERSION=$NODE_VERSION --build-arg PACKAGES="{{PACKAGES}}" -t npm-installer .
+    CONTAINER_ID=$(docker create --name npm-temp npm-installer)
+    docker logs $CONTAINER_ID
+    echo "Extracting node_modules..."
+    docker cp npm-temp:/install/node_modules ./node_modules
+    docker cp npm-temp:/install/package.json ./package.json
+    docker cp npm-temp:/install/package-lock.json ./package-lock.json 2>/dev/null || true
+    echo "Cleaning up..."
+    docker rm npm-temp
+    docker rmi npm-installer
+    echo "Done."
+
+install-dev *PACKAGES:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    NODE_VERSION={{node_version}}
+    echo "Installing dev dependencies with Node $NODE_VERSION..."
+    docker build --progress=plain -f Dockerfile.install --build-arg NODE_VERSION=$NODE_VERSION --build-arg PACKAGES="{{PACKAGES}}" --build-arg DEV=true -t npm-installer .
+    CONTAINER_ID=$(docker create --name npm-temp npm-installer)
+    docker logs $CONTAINER_ID
+    echo "Extracting node_modules..."
+    docker cp npm-temp:/install/node_modules ./node_modules
+    docker cp npm-temp:/install/package.json ./package.json
+    docker cp npm-temp:/install/package-lock.json ./package-lock.json 2>/dev/null || true
+    echo "Cleaning up..."
+    docker rm npm-temp
+    docker rmi npm-installer
+    echo "Done."
+
+build:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    NODE_VERSION=$(cat .nvmrc | tr -d 'v\n\r')
+    echo "Building with Node $NODE_VERSION..."
+    # Build does not need network. So it must not use it
+    docker build --network none --progress=plain -f Dockerfile --build-arg NODE_VERSION=$NODE_VERSION -t npm-build .
+    CONTAINER_ID=$(docker create npm-build)
+    echo "Extracting build artifacts..."
+    docker cp $CONTAINER_ID:/app/dist ./dist
+    echo "Cleaning up..."
+    docker rm $CONTAINER_ID
+    docker rmi npm-build
+    echo "Build complete. Output in ./dist"
+
+test:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    NODE_VERSION=$(cat .nvmrc | tr -d 'v\n\r')
+    echo "Running tests with Node $NODE_VERSION..."
+    docker build --progress=plain -f Dockerfile.test --build-arg NODE_VERSION=$NODE_VERSION -t npm-test .
+
+    # Run tests with .env file mounted if it exists
+    if [ -f .env ]; then
+        echo "Found .env file, mounting it..."
+        docker run --rm --env-file .env npm-test
+    else
+        echo "No .env file found, running without environment variables..."
+        ## If the .env is not there then I can safely assume the there is
+        ## no need so making netowrk calls
+        docker run --rm --network none npm-test
+    fi
+    echo "Tests complete."
+
+clean:
+    rm -rf node_modules
+
+install-biome:
+    npm i -D @biomejs/biome@1.9.4

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "arvo-event-handler",
-  "version": "3.0.18",
-  "description": "Type-safe event handler system with versioning, telemetry, and contract validation for distributed Arvo event-driven architectures, featuring routing and multi-handler support.",
+  "version": "3.0.20",
+  "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": {
+    "type": "git",
+    "url": "https://github.com/SaadAhmad123/arvo-event-handler"
+  },
   "scripts": {
     "build": "tsc",
     "start": "node ./dist/index.js",
@@ -13,44 +17,59 @@
     "doc": "npx typedoc",
     "otel": "docker run --rm -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 -p 16686:16686 -p 4317:4317 -p 4318:4318 -p 9411:9411 jaegertracing/all-in-one:latest"
   },
-  "keywords": ["arvo", "event-driven architecture", "xorca", "core", "cloudevent", "opentelemetry", "orchestrator"],
+  "keywords": [
+    "arvo",
+    "event-driven",
+    "event-handler",
+    "orchestration",
+    "state-machine",
+    "xstate",
+    "workflow",
+    "resumable",
+    "virtual orchestration",
+    "cloudevents",
+    "opentelemetry",
+    "distributed-systems",
+    "microservices",
+    "agentic-ai",
+    "event-broker",
+    "observability"
+  ],
   "author": "Saad Ahmad <saadkwi12@hotmail.com>",
   "license": "MIT",
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@jest/globals": "^29.7.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.49.1",
-    "@opentelemetry/exporter-metrics-otlp-proto": "^0.52.1",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.53.0",
-    "@opentelemetry/exporter-trace-otlp-proto": "^0.52.1",
-    "@opentelemetry/resources": "^1.25.1",
-    "@opentelemetry/sdk-metrics": "^1.25.1",
-    "@opentelemetry/sdk-node": "^0.52.1",
-    "@opentelemetry/sdk-trace-node": "^1.25.1",
-    "@opentelemetry/semantic-conventions": "^1.25.1",
-    "@types/jest": "^29.5.12",
-    "@types/node": "^22.5.0",
-    "@types/uuid": "^10.0.0",
-    "dotenv": "^16.4.5",
-    "jest": "^29.7.0",
-    "prettier": "^3.3.3",
-    "ts-jest": "^29.2.5",
-    "ts-node": "^10.9.2",
-    "typedoc": "^0.26.6",
-    "typedoc-github-theme": "^0.1.2",
-    "typedoc-plugin-coverage": "^3.4.0",
-    "typedoc-plugin-mermaid": "^1.12.0",
-    "typedoc-plugin-zod": "^1.2.1",
-    "typescript": "^5.5.4"
+    "@biomejs/biome": "1.9.4",
+    "@jest/globals": "29.7.0",
+    "@opentelemetry/auto-instrumentations-node": "0.49.1",
+    "@opentelemetry/exporter-metrics-otlp-proto": "0.52.1",
+    "@opentelemetry/exporter-trace-otlp-grpc": "0.53.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "0.52.1",
+    "@opentelemetry/resources": "1.25.1",
+    "@opentelemetry/sdk-metrics": "1.25.1",
+    "@opentelemetry/sdk-node": "0.52.1",
+    "@opentelemetry/sdk-trace-node": "1.25.1",
+    "@opentelemetry/semantic-conventions": "1.38.0",
+    "@types/jest": "29.5.12",
+    "@types/node": "22.19.1",
+    "dotenv": "16.6.1",
+    "jest": "29.7.0",
+    "ts-jest": "29.4.5",
+    "ts-node": "10.9.2",
+    "typedoc": "0.28.15",
+    "typedoc-github-theme": "0.3.1",
+    "typedoc-plugin-coverage": "4.0.2",
+    "typedoc-plugin-mermaid": "1.12.0",
+    "typedoc-plugin-zod": "1.4.3",
+    "typescript": "5.9.3"
   },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/core": "^1.30.1",
-    "arvo-core": "^3.0.18",
-    "uuid": "^11.1.0",
-    "xstate": "^5.23.0",
-    "zod": "^3.25.74",
-    "zod-to-json-schema": "^3.24.6"
+    "@opentelemetry/api": "1.9.0",
+    "@opentelemetry/core": "1.30.1",
+    "arvo-core": "3.0.22",
+    "uuid": "11.1.0",
+    "xstate": "5.24.0",
+    "zod": "3.25.74",
+    "zod-to-json-schema": "3.25.0"
   },
   "engines": {
     "node": ">=18.0.0"