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, type ArvoEventHandlerOtelSpanOptions, type NonEmptyArray } from '../../types';
import { type OrchestrationExecutionMemoryRecord } from '../orchestrationExecutionState';
import type { ArvoOrchestrationHandlerType } from '../types';
/**
 * Configuration context for orchestration execution.
 * Contains all resources and settings needed for the execution lifecycle.
 */
export type OrchestrationExecutionContext<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = {
    /** Event triggering the orchestration */
    event: ArvoEvent;
    /** OpenTelemetry configuration for tracing */
    opentelemetry: ArvoEventHandlerOpenTelemetryOptions;
    /** Source identifier for the orchestrator */
    source: string;
    /** Resource manager for state and lock operations */
    syncEventResource: SyncEventResource<TState>;
    /** Maximum execution units per cycle */
    executionunits: number;
    /** Optional domains for system error routing */
    systemErrorDomain: NonEmptyArray<string | null>;
    /** Self contract defining orchestrator interface */
    selfContract: VersionedArvoContract<ArvoOrchestratorContract, ArvoSemanticVersion>;
    /** Type of orchestration handler */
    _handlerType: ArvoOrchestrationHandlerType;
    /** OpenTelemetry span configuration */
    spanOptions: ArvoEventHandlerOtelSpanOptions & {
        spanName: NonNullable<ArvoEventHandlerOtelSpanOptions['spanName']>;
    };
};
/**
 * Core execution function signature for orchestration logic.
 * Receives prepared context and returns emitted events with new state.
 */
export type CoreExecutionFn<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = (params: {
    /** OpenTelemetry span for tracing */
    span: any;
    /** Current OpenTelemetry headers */
    otelHeaders: OpenTelemetryHeaders;
    /** Parent orchestration subject if nested */
    orchestrationParentSubject: string | null;
    /** ID of the initialization event */
    initEventId: string;
    /** Parsed event subject content */
    parsedEventSubject: ArvoOrchestrationSubjectContent;
    /** Current persisted state or null for new orchestrations */
    state: TState | null;
    /** Type of handler executing */
    _handlerType: ArvoOrchestrationHandlerType;
}) => Promise<{
    /** Events to emit from this execution */
    emittables: ArvoEvent[];
    /** New state to persist */
    newState: TState;
}>;
/**
 * Helper to log and return execution results.
 * @returns The same result after logging
 */
export declare const returnEventsWithLogging: (param: Awaited<ReturnType<IArvoEventHandler["execute"]>>, span: Span) => Awaited<ReturnType<IArvoEventHandler["execute"]>>;
/**
 * Wraps orchestration execution with infrastructure concerns.
 *
 * Provides a complete execution wrapper that handles:
 * - OpenTelemetry span creation and management
 * - Event subject validation and parsing
 * - Lock acquisition for concurrent safety
 * - State retrieval and persistence
 * - Error handling with system error event generation
 * - Lock release in all scenarios
 *
 * This wrapper ensures consistent behavior across all orchestration handlers
 * while allowing custom core logic via the execution function parameter.
 * @returns Emitted events from successful execution or error handling
 */
export declare const executeWithOrchestrationWrapper: <TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>>({ event, opentelemetry, spanOptions, source, syncEventResource, executionunits, systemErrorDomain, selfContract, _handlerType, }: OrchestrationExecutionContext<TState>, coreExecutionFn: CoreExecutionFn<TState>) => Promise<Awaited<ReturnType<IArvoEventHandler["execute"]>>>;