arvo-event-handler/dist/ArvoOrchestrationUtils/handlerErrors.d.ts

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-me

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 ArvoOrchestrationHandlerType } from './types';
import type { NonEmptyArray } from '../types';
import { MachineMemoryMetadata } from '../MachineMemory/interface';
/**
 * Parameters for creating system error events during orchestration failures.
 */
export type CreateSystemErrorEventsParams = {
    /** The error that occurred */
    error: unknown;
    /** Event that triggered the error */
    event: ArvoEvent;
    /** OpenTelemetry headers for tracing */
    otelHeaders: OpenTelemetryHeaders;
    /** Parent orchestration subject if nested */
    orchestrationParentSubject: string | null;
    /** ID of the initiating event */
    initEventId: string | null;
    /** Self contract defining error schema */
    selfContract: VersionedArvoContract<ArvoContract, ArvoSemanticVersion>;
    /** Optional domains for error event routing */
    systemErrorDomain: NonEmptyArray<string | null>;
    /** Execution units for error events */
    executionunits: number;
    /** Source identifier */
    source: string;
    /** Type of handler reporting the error */
    handlerType: ArvoOrchestrationHandlerType;
};
/**
 * Creates standardized system error events for orchestration failures.
 *
 * Generates error events that route back to the workflow initiator, preserving
 * tracing context and orchestration hierarchy. Supports multiple domains for
 * error distribution.
 *
 * @param params - Error event creation parameters
 * @returns Array of system error events for each configured domain
 */
export declare const createSystemErrorEvents: ({ error, event, otelHeaders, orchestrationParentSubject: _orchestrationParentSubject, initEventId, selfContract, systemErrorDomain, executionunits, source, handlerType, }: CreateSystemErrorEventsParams & {
    error: Error;
}) => ArvoEvent[];
/**
 * Handles errors during orchestration execution with proper state management.
 *
 * Processes errors by determining if they are violations (retriable) or execution
 * errors (terminal). For execution errors, persists failure state and generates
 * system error events. For violations, returns the error to be thrown without
 * state persistence.
 *
 * @returns Either the violation error to throw or system error events to emit
 */
export declare const handleOrchestrationErrors: (_handlerType: ArvoOrchestrationHandlerType, param: CreateSystemErrorEventsParams & {
    syncEventResource: SyncEventResource<OrchestrationExecutionMemoryRecord<Record<string, any>>>;
}, metadata: MachineMemoryMetadata, span: Span) => Promise<{
    errorToThrow: ViolationError;
    events: null;
} | {
    errorToThrow: null;
    events: ArvoEvent[];
}>;