@tasker-systems/tasker 0.1.0-alpha.1

package/dist/index-B3BcknlZ.d.ts

@@ -0,0 +1,1349 @@
+import { EventEmitter } from 'eventemitter3';
+import { l as FfiStepEvent, p as StepExecutionResult, k as FfiDispatchMetrics, T as TaskerRuntime } from './runtime-interface-CE4viUt7.js';
+
+/**
+ * Event emitter for TypeScript workers.
+ *
+ * Provides a type-safe event emitter wrapper that works across
+ * all supported runtimes (Bun, Node.js, Deno).
+ */
+
+/**
+ * Event payload types
+ */
+interface StepExecutionReceivedPayload {
+    event: FfiStepEvent;
+    receivedAt: Date;
+}
+interface StepExecutionStartedPayload {
+    eventId: string;
+    stepUuid: string;
+    taskUuid: string;
+    handlerName: string;
+    startedAt: Date;
+}
+interface StepExecutionCompletedPayload {
+    eventId: string;
+    stepUuid: string;
+    taskUuid: string;
+    result: StepExecutionResult;
+    executionTimeMs: number;
+    completedAt: Date;
+}
+interface StepExecutionFailedPayload {
+    eventId: string;
+    stepUuid: string;
+    taskUuid: string;
+    error: Error;
+    failedAt: Date;
+}
+interface StepCompletionSentPayload {
+    eventId: string;
+    stepUuid: string;
+    success: boolean;
+    sentAt: Date;
+}
+/** TAS-125: Checkpoint yield event payload */
+interface StepCheckpointYieldSentPayload {
+    eventId: string;
+    stepUuid: string;
+    cursor: unknown;
+    itemsProcessed: number;
+    timestamp: Date;
+}
+interface WorkerEventPayload {
+    workerId?: string;
+    timestamp: Date;
+    message?: string;
+}
+interface WorkerErrorPayload {
+    error: Error;
+    timestamp: Date;
+    context?: Record<string, unknown>;
+}
+interface PollerCyclePayload {
+    eventsProcessed: number;
+    cycleNumber: number;
+    timestamp: Date;
+}
+interface MetricsPayload {
+    metrics: FfiDispatchMetrics;
+    timestamp: Date;
+}
+/**
+ * Event map for type-safe event handling
+ */
+interface TaskerEventMap {
+    'step.execution.received': StepExecutionReceivedPayload;
+    'step.execution.started': StepExecutionStartedPayload;
+    'step.execution.completed': StepExecutionCompletedPayload;
+    'step.execution.failed': StepExecutionFailedPayload;
+    'step.completion.sent': StepCompletionSentPayload;
+    'step.execution.timeout': StepExecutionFailedPayload;
+    'step.checkpoint_yield.sent': StepCheckpointYieldSentPayload;
+    'worker.started': WorkerEventPayload;
+    'worker.ready': WorkerEventPayload;
+    'worker.shutdown.started': WorkerEventPayload;
+    'worker.stopped': WorkerEventPayload;
+    'worker.error': WorkerErrorPayload;
+    'poller.started': WorkerEventPayload;
+    'poller.stopped': WorkerEventPayload;
+    'poller.cycle.complete': PollerCyclePayload;
+    'poller.starvation.detected': MetricsPayload;
+    'poller.error': WorkerErrorPayload;
+    'metrics.updated': MetricsPayload;
+    'metrics.error': WorkerErrorPayload;
+}
+/**
+ * Type-safe event emitter for Tasker events
+ */
+declare class TaskerEventEmitter extends EventEmitter<TaskerEventMap> {
+    private readonly instanceId;
+    constructor();
+    /**
+     * Get the unique instance ID for this emitter
+     */
+    getInstanceId(): string;
+    /**
+     * Emit a step execution received event
+     */
+    emitStepReceived(event: FfiStepEvent): void;
+    /**
+     * Emit a step execution started event
+     */
+    emitStepStarted(eventId: string, stepUuid: string, taskUuid: string, handlerName: string): void;
+    /**
+     * Emit a step execution completed event
+     */
+    emitStepCompleted(eventId: string, stepUuid: string, taskUuid: string, result: StepExecutionResult, executionTimeMs: number): void;
+    /**
+     * Emit a step execution failed event
+     */
+    emitStepFailed(eventId: string, stepUuid: string, taskUuid: string, error: Error): void;
+    /**
+     * Emit a step completion sent event
+     */
+    emitCompletionSent(eventId: string, stepUuid: string, success: boolean): void;
+    /**
+     * Emit a worker started event
+     */
+    emitWorkerStarted(workerId?: string): void;
+    /**
+     * Emit a worker ready event
+     */
+    emitWorkerReady(workerId?: string): void;
+    /**
+     * Emit a worker shutdown started event
+     */
+    emitWorkerShutdownStarted(workerId?: string): void;
+    /**
+     * Emit a worker stopped event
+     */
+    emitWorkerStopped(workerId?: string): void;
+    /**
+     * Emit a worker error event
+     */
+    emitWorkerError(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Emit a metrics updated event
+     */
+    emitMetricsUpdated(metrics: FfiDispatchMetrics): void;
+    /**
+     * Emit a starvation detected event
+     */
+    emitStarvationDetected(metrics: FfiDispatchMetrics): void;
+}
+
+/**
+ * Standard event names for the TypeScript worker.
+ *
+ * These constants provide type-safe event names that match
+ * the event system used by other language workers.
+ */
+/**
+ * Event names for step execution lifecycle
+ */
+declare const StepEventNames: {
+    /** Emitted when a step execution event is received from the FFI layer */
+    readonly STEP_EXECUTION_RECEIVED: "step.execution.received";
+    /** Emitted when a step handler starts executing */
+    readonly STEP_EXECUTION_STARTED: "step.execution.started";
+    /** Emitted when a step handler completes successfully */
+    readonly STEP_EXECUTION_COMPLETED: "step.execution.completed";
+    /** Emitted when a step handler fails */
+    readonly STEP_EXECUTION_FAILED: "step.execution.failed";
+    /** Emitted when a step completion is sent back to Rust */
+    readonly STEP_COMPLETION_SENT: "step.completion.sent";
+    /** Emitted when a step handler times out */
+    readonly STEP_EXECUTION_TIMEOUT: "step.execution.timeout";
+    /** TAS-125: Emitted when a checkpoint yield is sent back to Rust */
+    readonly STEP_CHECKPOINT_YIELD_SENT: "step.checkpoint_yield.sent";
+};
+/**
+ * Event names for worker lifecycle
+ */
+declare const WorkerEventNames: {
+    /** Emitted when the worker starts up */
+    readonly WORKER_STARTED: "worker.started";
+    /** Emitted when the worker is ready to process events */
+    readonly WORKER_READY: "worker.ready";
+    /** Emitted when graceful shutdown begins */
+    readonly WORKER_SHUTDOWN_STARTED: "worker.shutdown.started";
+    /** Emitted when the worker has fully stopped */
+    readonly WORKER_STOPPED: "worker.stopped";
+    /** Emitted when the worker encounters an error */
+    readonly WORKER_ERROR: "worker.error";
+};
+/**
+ * Event names for polling lifecycle
+ */
+declare const PollerEventNames: {
+    /** Emitted when the poller starts */
+    readonly POLLER_STARTED: "poller.started";
+    /** Emitted when the poller stops */
+    readonly POLLER_STOPPED: "poller.stopped";
+    /** Emitted when a poll cycle completes */
+    readonly POLLER_CYCLE_COMPLETE: "poller.cycle.complete";
+    /** Emitted when starvation is detected */
+    readonly POLLER_STARVATION_DETECTED: "poller.starvation.detected";
+    /** Emitted when the poller encounters an error */
+    readonly POLLER_ERROR: "poller.error";
+};
+/**
+ * Event names for metrics
+ */
+declare const MetricsEventNames: {
+    /** Emitted periodically with FFI dispatch metrics */
+    readonly METRICS_UPDATED: "metrics.updated";
+    /** Emitted when metrics collection fails */
+    readonly METRICS_ERROR: "metrics.error";
+};
+/**
+ * All event names combined
+ */
+declare const EventNames: {
+    /** Emitted periodically with FFI dispatch metrics */
+    readonly METRICS_UPDATED: "metrics.updated";
+    /** Emitted when metrics collection fails */
+    readonly METRICS_ERROR: "metrics.error";
+    /** Emitted when the poller starts */
+    readonly POLLER_STARTED: "poller.started";
+    /** Emitted when the poller stops */
+    readonly POLLER_STOPPED: "poller.stopped";
+    /** Emitted when a poll cycle completes */
+    readonly POLLER_CYCLE_COMPLETE: "poller.cycle.complete";
+    /** Emitted when starvation is detected */
+    readonly POLLER_STARVATION_DETECTED: "poller.starvation.detected";
+    /** Emitted when the poller encounters an error */
+    readonly POLLER_ERROR: "poller.error";
+    /** Emitted when the worker starts up */
+    readonly WORKER_STARTED: "worker.started";
+    /** Emitted when the worker is ready to process events */
+    readonly WORKER_READY: "worker.ready";
+    /** Emitted when graceful shutdown begins */
+    readonly WORKER_SHUTDOWN_STARTED: "worker.shutdown.started";
+    /** Emitted when the worker has fully stopped */
+    readonly WORKER_STOPPED: "worker.stopped";
+    /** Emitted when the worker encounters an error */
+    readonly WORKER_ERROR: "worker.error";
+    /** Emitted when a step execution event is received from the FFI layer */
+    readonly STEP_EXECUTION_RECEIVED: "step.execution.received";
+    /** Emitted when a step handler starts executing */
+    readonly STEP_EXECUTION_STARTED: "step.execution.started";
+    /** Emitted when a step handler completes successfully */
+    readonly STEP_EXECUTION_COMPLETED: "step.execution.completed";
+    /** Emitted when a step handler fails */
+    readonly STEP_EXECUTION_FAILED: "step.execution.failed";
+    /** Emitted when a step completion is sent back to Rust */
+    readonly STEP_COMPLETION_SENT: "step.completion.sent";
+    /** Emitted when a step handler times out */
+    readonly STEP_EXECUTION_TIMEOUT: "step.execution.timeout";
+    /** TAS-125: Emitted when a checkpoint yield is sent back to Rust */
+    readonly STEP_CHECKPOINT_YIELD_SENT: "step.checkpoint_yield.sent";
+};
+/**
+ * Type representing all possible event names
+ */
+type EventName = (typeof EventNames)[keyof typeof EventNames];
+/**
+ * Type representing step event names
+ */
+type StepEventName = (typeof StepEventNames)[keyof typeof StepEventNames];
+/**
+ * Type representing worker event names
+ */
+type WorkerEventName = (typeof WorkerEventNames)[keyof typeof WorkerEventNames];
+/**
+ * Type representing poller event names
+ */
+type PollerEventName = (typeof PollerEventNames)[keyof typeof PollerEventNames];
+/**
+ * Type representing metrics event names
+ */
+type MetricsEventName = (typeof MetricsEventNames)[keyof typeof MetricsEventNames];
+
+/**
+ * Event poller for TypeScript workers.
+ *
+ * Provides a polling loop that retrieves step events from the Rust FFI layer
+ * and dispatches them to registered handlers. Uses a 10ms polling interval
+ * matching other language workers.
+ */
+
+/**
+ * Configuration for the event poller
+ */
+interface EventPollerConfig$1 {
+    /** Polling interval in milliseconds (default: 10) */
+    pollIntervalMs?: number;
+    /** Number of polls between starvation checks (default: 100) */
+    starvationCheckInterval?: number;
+    /** Number of polls between cleanup operations (default: 1000) */
+    cleanupInterval?: number;
+    /** Number of polls between metrics emissions (default: 100) */
+    metricsInterval?: number;
+    /** Maximum events to process per poll cycle (default: 100) */
+    maxEventsPerCycle?: number;
+}
+/**
+ * Callback for step event handling
+ */
+type StepEventCallback = (event: FfiStepEvent) => Promise<void>;
+/**
+ * Callback for error handling
+ */
+type ErrorCallback = (error: Error) => void;
+/**
+ * Callback for metrics handling
+ */
+type MetricsCallback = (metrics: FfiDispatchMetrics) => void;
+/**
+ * Event poller state
+ */
+type PollerState = 'stopped' | 'running' | 'stopping';
+/**
+ * Event poller for retrieving and dispatching step events from the FFI layer.
+ *
+ * The poller runs a continuous loop that:
+ * 1. Polls for step events at 10ms intervals
+ * 2. Dispatches received events to registered handlers
+ * 3. Periodically checks for starvation conditions
+ * 4. Performs cleanup of timed-out events
+ * 5. Emits metrics for monitoring
+ */
+declare class EventPoller {
+    private readonly runtime;
+    private readonly config;
+    private readonly emitter;
+    private state;
+    private pollCount;
+    private cycleCount;
+    private intervalId;
+    private stepEventCallback;
+    private errorCallback;
+    private metricsCallback;
+    /**
+     * Create a new EventPoller.
+     *
+     * @param runtime - The FFI runtime for polling events
+     * @param emitter - The event emitter to dispatch events to (required, no fallback)
+     * @param config - Optional configuration for polling behavior
+     */
+    constructor(runtime: TaskerRuntime, emitter: TaskerEventEmitter, config?: EventPollerConfig$1);
+    /**
+     * Get the current poller state
+     */
+    getState(): PollerState;
+    /**
+     * Check if the poller is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the total number of polls executed
+     */
+    getPollCount(): number;
+    /**
+     * Get the total number of cycles completed
+     */
+    getCycleCount(): number;
+    /**
+     * Register a callback for step events
+     */
+    onStepEvent(callback: StepEventCallback): this;
+    /**
+     * Register a callback for errors
+     */
+    onError(callback: ErrorCallback): this;
+    /**
+     * Register a callback for metrics
+     */
+    onMetrics(callback: MetricsCallback): this;
+    /**
+     * Start the polling loop
+     */
+    start(): void;
+    /**
+     * Stop the polling loop
+     */
+    stop(): Promise<void>;
+    /**
+     * Execute a single poll cycle
+     */
+    private poll;
+    /**
+     * Handle a step event
+     */
+    private handleStepEvent;
+    /**
+     * Check for starvation conditions
+     */
+    private checkStarvation;
+    /**
+     * Emit current metrics
+     */
+    private emitMetrics;
+    /**
+     * Handle an error
+     */
+    private handleError;
+}
+/**
+ * Create an event poller with the given runtime, emitter, and configuration
+ */
+declare function createEventPoller(runtime: TaskerRuntime, emitter: TaskerEventEmitter, config?: EventPollerConfig$1): EventPoller;
+
+/**
+ * Standard error types for cross-language consistency.
+ *
+ * These values align with Ruby and Python worker implementations
+ * and are used by the orchestration layer for retry decisions.
+ *
+ * @see TAS-92 Cross-Language API Alignment
+ */
+declare enum ErrorType {
+    /**
+     * Permanent, non-recoverable failure.
+     * Examples: invalid input, resource not found, authentication failure.
+     */
+    PERMANENT_ERROR = "permanent_error",
+    /**
+     * Transient failure that may succeed on retry.
+     * Examples: network timeout, service unavailable, rate limiting.
+     */
+    RETRYABLE_ERROR = "retryable_error",
+    /**
+     * Input validation failure.
+     * Examples: missing required field, invalid format, constraint violation.
+     */
+    VALIDATION_ERROR = "validation_error",
+    /**
+     * Operation timed out.
+     * Examples: HTTP request timeout, database query timeout.
+     */
+    TIMEOUT = "timeout",
+    /**
+     * Failure within the step handler itself.
+     * Examples: unhandled exception, handler misconfiguration.
+     */
+    HANDLER_ERROR = "handler_error"
+}
+/**
+ * Check if an error type is one of the standard values.
+ *
+ * @param errorType - The error type string to check
+ * @returns True if the error type matches one of the standard values
+ *
+ * @example
+ * isStandardErrorType('permanent_error'); // true
+ * isStandardErrorType('custom_error');    // false
+ */
+declare function isStandardErrorType(errorType: string): boolean;
+/**
+ * Get the recommended retryable flag for a given error type.
+ *
+ * @param errorType - The error type string
+ * @returns True if the error type is typically retryable
+ *
+ * @example
+ * isTypicallyRetryable('timeout');          // true
+ * isTypicallyRetryable('permanent_error');  // false
+ */
+declare function isTypicallyRetryable(errorType: string): boolean;
+
+/**
+ * Parameters for constructing a StepContext.
+ */
+interface StepContextParams {
+    event: FfiStepEvent;
+    taskUuid: string;
+    stepUuid: string;
+    correlationId: string;
+    handlerName: string;
+    inputData: Record<string, unknown>;
+    dependencyResults: Record<string, unknown>;
+    stepConfig: Record<string, unknown>;
+    stepInputs: Record<string, unknown>;
+    retryCount: number;
+    maxRetries: number;
+}
+/**
+ * Context provided to step handlers during execution.
+ *
+ * Contains all information needed for a step handler to execute,
+ * including input data, dependency results, and configuration.
+ *
+ * Matches Python's StepContext and Ruby's StepContext (post-TAS-96).
+ *
+ * @example
+ * ```typescript
+ * class MyHandler extends StepHandler {
+ *   async call(context: StepContext): Promise<StepHandlerResult> {
+ *     const orderId = context.inputData['order_id'];
+ *     const previousResult = context.getDependencyResult('step_1');
+ *     // ... handler logic ...
+ *     return this.success({ processed: true });
+ *   }
+ * }
+ * ```
+ */
+declare class StepContext {
+    /** The original FFI step event */
+    readonly event: FfiStepEvent;
+    /** Task UUID */
+    readonly taskUuid: string;
+    /** Step UUID */
+    readonly stepUuid: string;
+    /** Correlation ID for tracing */
+    readonly correlationId: string;
+    /** Name of the handler being executed */
+    readonly handlerName: string;
+    /** Input data for the handler (from task context) */
+    readonly inputData: Record<string, unknown>;
+    /** Results from dependent steps */
+    readonly dependencyResults: Record<string, unknown>;
+    /** Handler-specific configuration (from step_definition.handler.initialization) */
+    readonly stepConfig: Record<string, unknown>;
+    /** Step-specific inputs (from workflow_step.inputs, used for batch cursor config) */
+    readonly stepInputs: Record<string, unknown>;
+    /** Current retry attempt number */
+    readonly retryCount: number;
+    /** Maximum retry attempts allowed */
+    readonly maxRetries: number;
+    constructor(params: StepContextParams);
+    /**
+     * Create a StepContext from an FFI event.
+     *
+     * Extracts input data, dependency results, and configuration from
+     * the task_sequence_step payload.
+     *
+     * The FFI data structure mirrors the Ruby TaskSequenceStepWrapper:
+     * - task.context -> inputData (task context with user inputs)
+     * - dependency_results -> results from parent steps
+     * - step_definition.handler.initialization -> stepConfig
+     * - workflow_step.attempts -> retryCount
+     * - workflow_step.max_attempts -> maxRetries
+     * - workflow_step.inputs -> stepInputs
+     *
+     * @param event - The FFI step event
+     * @param handlerName - Name of the handler to execute
+     * @returns A StepContext populated from the event
+     */
+    static fromFfiEvent(event: FfiStepEvent, handlerName: string): StepContext;
+    /**
+     * Get the computed result value from a dependency step.
+     *
+     * This method extracts the actual computed value from a dependency result,
+     * unwrapping any nested structure. Matches Python's get_dependency_result().
+     *
+     * The dependency result structure can be:
+     * - {"result": actual_value} - unwraps to actual_value
+     * - primitive value - returns as-is
+     *
+     * @param stepName - Name of the dependency step
+     * @returns The computed result value, or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Instead of:
+     * const step1Result = context.dependencyResults['step_1'] || {};
+     * const value = step1Result.result;  // Might be nested!
+     *
+     * // Use:
+     * const value = context.getDependencyResult('step_1');  // Unwrapped
+     * ```
+     */
+    getDependencyResult(stepName: string): unknown;
+    /**
+     * Get a value from the input data.
+     *
+     * @param key - The key to look up in inputData
+     * @returns The value or undefined if not found
+     */
+    getInput<T = unknown>(key: string): T | undefined;
+    /**
+     * Get a value from the step configuration.
+     *
+     * @param key - The key to look up in stepConfig
+     * @returns The value or undefined if not found
+     */
+    getConfig<T = unknown>(key: string): T | undefined;
+    /**
+     * Check if this is a retry attempt.
+     *
+     * @returns True if retryCount > 0
+     */
+    isRetry(): boolean;
+    /**
+     * Check if this is the last allowed retry attempt.
+     *
+     * @returns True if retryCount >= maxRetries - 1
+     */
+    isLastRetry(): boolean;
+    /**
+     * Get a value from the input data with a default.
+     *
+     * @param key - The key to look up in inputData
+     * @param defaultValue - Value to return if key not found or undefined
+     * @returns The value or default if not found/undefined
+     *
+     * @example
+     * ```typescript
+     * const batchSize = context.getInputOr('batch_size', 100);
+     * ```
+     */
+    getInputOr<T = unknown>(key: string, defaultValue: T): T;
+    /**
+     * Extract a nested field from a dependency result.
+     *
+     * Useful when dependency results are complex objects and you need
+     * to extract a specific nested value without manual object traversal.
+     *
+     * @param stepName - Name of the dependency step
+     * @param path - Path elements to traverse into the result
+     * @returns The nested value, or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Extract nested field from dependency result
+     * const csvPath = context.getDependencyField('analyze_csv', 'csv_file_path');
+     * // Multiple levels deep
+     * const value = context.getDependencyField('step_1', 'data', 'items');
+     * ```
+     */
+    getDependencyField(stepName: string, ...path: string[]): unknown;
+    /**
+     * Get the raw checkpoint data from the workflow step.
+     *
+     * @returns The checkpoint data object or null if not set
+     */
+    get checkpoint(): Record<string, unknown> | null;
+    /**
+     * Get the checkpoint cursor position.
+     *
+     * The cursor represents the current position in batch processing,
+     * allowing handlers to resume from where they left off.
+     *
+     * @returns The cursor value (number, string, or object) or null if not set
+     *
+     * @example
+     * ```typescript
+     * const cursor = context.checkpointCursor;
+     * const startFrom = cursor ?? 0;
+     * ```
+     */
+    get checkpointCursor(): unknown;
+    /**
+     * Get the number of items processed in the current batch run.
+     *
+     * @returns Number of items processed (0 if no checkpoint)
+     */
+    get checkpointItemsProcessed(): number;
+    /**
+     * Get the accumulated results from batch processing.
+     *
+     * Accumulated results allow handlers to maintain running totals
+     * or aggregated state across checkpoint boundaries.
+     *
+     * @returns The accumulated results object or null if not set
+     *
+     * @example
+     * ```typescript
+     * const totals = context.accumulatedResults ?? {};
+     * const currentSum = totals.sum ?? 0;
+     * ```
+     */
+    get accumulatedResults(): Record<string, unknown> | null;
+    /**
+     * Check if a checkpoint exists for this step.
+     *
+     * @returns True if a checkpoint cursor exists
+     *
+     * @example
+     * ```typescript
+     * if (context.hasCheckpoint()) {
+     *   console.log(`Resuming from cursor: ${context.checkpointCursor}`);
+     * }
+     * ```
+     */
+    hasCheckpoint(): boolean;
+    /**
+     * Get all dependency result keys.
+     *
+     * @returns Array of step names that have dependency results
+     */
+    getDependencyResultKeys(): string[];
+    /**
+     * Get all dependency results matching a step name prefix.
+     *
+     * This is useful for batch processing where multiple worker steps
+     * share a common prefix (e.g., "process_batch_001", "process_batch_002").
+     *
+     * Returns the unwrapped result values (same as getDependencyResult).
+     *
+     * @param prefix - Step name prefix to match
+     * @returns Array of unwrapped result values from matching steps
+     *
+     * @example
+     * ```typescript
+     * // For batch worker results named: process_batch_001, process_batch_002, etc.
+     * const batchResults = context.getAllDependencyResults('process_batch_');
+     * const total = batchResults.reduce((sum, r) => sum + r.count, 0);
+     * ```
+     */
+    getAllDependencyResults(prefix: string): unknown[];
+}
+
+/**
+ * Configuration for a batch worker instance.
+ *
+ * Used by batchable handlers to define the work partition for each worker.
+ */
+interface BatchWorkerConfig {
+    /** Unique identifier for this batch */
+    batch_id: string;
+    /** Starting cursor position (inclusive) */
+    cursor_start: number;
+    /** Ending cursor position (exclusive) */
+    cursor_end: number;
+    /** Number of rows/items in this batch */
+    row_count: number;
+    /** Index of this worker (0-based) */
+    worker_index: number;
+    /** Total number of workers processing this data */
+    total_workers: number;
+    /** Optional additional metadata for this batch */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for constructing a StepHandlerResult.
+ */
+interface StepHandlerResultParams {
+    success: boolean;
+    result?: Record<string, unknown> | null;
+    errorMessage?: string | null;
+    errorType?: string | null;
+    errorCode?: string | null;
+    retryable?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from a step handler execution.
+ *
+ * Step handlers return this to indicate success or failure,
+ * along with any output data or error details.
+ *
+ * Matches Python's StepHandlerResult and Ruby's StepHandlerCallResult.
+ *
+ * @example Success case
+ * ```typescript
+ * return StepHandlerResult.success({ processed: 100 });
+ * ```
+ *
+ * @example Failure case
+ * ```typescript
+ * return StepHandlerResult.failure(
+ *   'Validation failed',
+ *   ErrorType.VALIDATION_ERROR,
+ *   false
+ * );
+ * ```
+ *
+ * @example Failure with error code
+ * ```typescript
+ * return StepHandlerResult.failure(
+ *   'Payment gateway timeout',
+ *   ErrorType.TIMEOUT,
+ *   true,
+ *   { gateway: 'stripe' },
+ *   'GATEWAY_TIMEOUT'
+ * );
+ * ```
+ */
+declare class StepHandlerResult {
+    /** Whether the handler executed successfully */
+    readonly success: boolean;
+    /** Handler output data (success case) */
+    readonly result: Record<string, unknown> | null;
+    /** Error message (failure case) */
+    readonly errorMessage: string | null;
+    /** Error type/category for classification */
+    readonly errorType: string | null;
+    /** Optional application-specific error code */
+    readonly errorCode: string | null;
+    /** Whether the error is retryable */
+    readonly retryable: boolean;
+    /** Additional execution metadata */
+    readonly metadata: Record<string, unknown>;
+    constructor(params: StepHandlerResultParams);
+    /**
+     * Create a successful handler result.
+     *
+     * This is the primary factory method for creating success results.
+     * Aligned with Ruby and Python worker APIs.
+     *
+     * @param result - The handler output data
+     * @param metadata - Optional additional metadata
+     * @returns A StepHandlerResult indicating success
+     *
+     * @example
+     * ```typescript
+     * return StepHandlerResult.success(
+     *   { processed: 100, skipped: 5 }
+     * );
+     * ```
+     */
+    static success(result: Record<string, unknown>, metadata?: Record<string, unknown>): StepHandlerResult;
+    /**
+     * Create a failure handler result.
+     *
+     * @param message - Human-readable error message
+     * @param errorType - Error type/category for classification. Use ErrorType enum.
+     * @param retryable - Whether the error is retryable (default: true)
+     * @param metadata - Optional additional metadata
+     * @param errorCode - Optional application-specific error code
+     * @returns A StepHandlerResult indicating failure
+     *
+     * @example
+     * ```typescript
+     * return StepHandlerResult.failure(
+     *   'Invalid input format',
+     *   ErrorType.VALIDATION_ERROR,
+     *   false
+     * );
+     * ```
+     *
+     * @example With error code
+     * ```typescript
+     * return StepHandlerResult.failure(
+     *   'Gateway timeout',
+     *   ErrorType.TIMEOUT,
+     *   true,
+     *   { duration_ms: 30000 },
+     *   'GATEWAY_TIMEOUT'
+     * );
+     * ```
+     */
+    static failure(message: string, errorType?: ErrorType | string, retryable?: boolean, metadata?: Record<string, unknown>, errorCode?: string): StepHandlerResult;
+    /**
+     * Check if this result indicates success.
+     */
+    isSuccess(): boolean;
+    /**
+     * Check if this result indicates failure.
+     */
+    isFailure(): boolean;
+    /**
+     * Convert to JSON for serialization.
+     *
+     * Uses snake_case keys to match the Rust FFI contract.
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Public interface for executable handlers (TAS-93).
+ *
+ * This interface defines the contract that all handlers must fulfill
+ * to be executed by the resolver chain. Both StepHandler and
+ * MethodDispatchWrapper implement this interface.
+ *
+ * Use this type when you need to accept either a handler or a wrapped handler.
+ */
+interface ExecutableHandler {
+    /** Unique identifier for this handler */
+    readonly name: string;
+    /** Version string for the handler */
+    readonly version: string;
+    /** List of capability strings the handler supports */
+    readonly capabilities: string[];
+    /**
+     * Execute the step handler logic.
+     *
+     * @param context - Execution context with input data and configuration
+     * @returns Promise resolving to handler result
+     */
+    call(context: StepContext): Promise<StepHandlerResult>;
+    /**
+     * Return JSON schema for handler configuration.
+     *
+     * @returns JSON schema object, or null if no schema is defined
+     */
+    configSchema(): Record<string, unknown> | null;
+}
+/**
+ * Interface for step handler class metadata.
+ *
+ * Handler classes must implement these static properties.
+ */
+interface StepHandlerClass {
+    /** Unique identifier for this handler. Must match step definition. */
+    handlerName: string;
+    /** Version string for the handler (default: "1.0.0") */
+    handlerVersion?: string;
+    /** Constructor that creates a handler instance */
+    new (): StepHandler;
+}
+/**
+ * Abstract base class for step handlers.
+ *
+ * All step handlers must extend this class and implement
+ * the `call` method. The handlerName static property must be set
+ * to a unique identifier for the handler.
+ *
+ * TAS-131: TypeScript handlers are async by default. The `call` method
+ * returns a Promise, enabling use of async/await for I/O operations
+ * like HTTP requests, database queries, and file operations.
+ *
+ * Matches Python's StepHandler and Ruby's StepHandler base classes.
+ *
+ * @example
+ * ```typescript
+ * class ProcessOrderHandler extends StepHandler {
+ *   static handlerName = 'process_order';
+ *   static handlerVersion = '1.0.0';
+ *
+ *   async call(context: StepContext): Promise<StepHandlerResult> {
+ *     const orderId = context.getInput<string>('order_id');
+ *     // Can use async operations like fetch, database queries, etc.
+ *     const data = await fetchOrderDetails(orderId);
+ *     return this.success({ order_id: orderId, status: 'processed', data });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class StepHandler {
+    /**
+     * Unique identifier for this handler.
+     * Must be set by subclasses and match the step definition.
+     */
+    static handlerName: string;
+    /**
+     * Version string for the handler.
+     * Default: "1.0.0"
+     */
+    static handlerVersion: string;
+    /**
+     * Execute the step handler logic.
+     *
+     * This method is called by the execution subscriber when a step
+     * event is received that matches this handler's name.
+     *
+     * @param context - Execution context with input data, dependency results,
+     *                  and configuration
+     * @returns Promise resolving to StepHandlerResult indicating success or failure
+     *
+     * @example
+     * ```typescript
+     * async call(context: StepContext): Promise<StepHandlerResult> {
+     *   try {
+     *     const result = await processData(context.inputData);
+     *     return this.success(result);
+     *   } catch (error) {
+     *     return this.failure(
+     *       error.message,
+     *       ErrorType.HANDLER_ERROR,
+     *       true
+     *     );
+     *   }
+     * }
+     * ```
+     */
+    abstract call(context: StepContext): Promise<StepHandlerResult>;
+    /**
+     * Get the handler name.
+     *
+     * @returns The handlerName static property, or the class name if not set
+     */
+    get name(): string;
+    /**
+     * Get the handler version.
+     *
+     * @returns The handlerVersion static property
+     */
+    get version(): string;
+    /**
+     * Return handler capabilities.
+     *
+     * Override this to advertise specific capabilities for handler selection.
+     *
+     * @returns List of capability strings (default: ["process"])
+     */
+    get capabilities(): string[];
+    /**
+     * Return JSON schema for handler configuration.
+     *
+     * Override this to provide a schema for validating step_config.
+     *
+     * @returns JSON schema object, or null if no schema is defined
+     */
+    configSchema(): Record<string, unknown> | null;
+    /**
+     * Create a success result.
+     *
+     * Convenience method for creating success results.
+     *
+     * @param result - Result data object
+     * @param metadata - Optional metadata object
+     * @returns StepHandlerResult with success=true
+     *
+     * @example
+     * ```typescript
+     * return this.success({ processed: 100 });
+     * ```
+     */
+    protected success(result: Record<string, unknown>, metadata?: Record<string, unknown>): StepHandlerResult;
+    /**
+     * Create a failure result.
+     *
+     * Convenience method for creating failure results.
+     *
+     * @param message - Error message
+     * @param errorType - Error type classification. Use ErrorType enum for consistency.
+     * @param retryable - Whether the error is retryable (default: true)
+     * @param metadata - Optional metadata object
+     * @param errorCode - Optional application-specific error code
+     * @returns StepHandlerResult with success=false
+     *
+     * @example
+     * ```typescript
+     * return this.failure(
+     *   'Invalid input',
+     *   ErrorType.VALIDATION_ERROR,
+     *   false
+     * );
+     * ```
+     */
+    protected failure(message: string, errorType?: ErrorType | string, retryable?: boolean, metadata?: Record<string, unknown>, errorCode?: string): StepHandlerResult;
+    /**
+     * Get a string representation of the handler.
+     */
+    toString(): string;
+}
+
+/**
+ * Step execution subscriber for TypeScript workers.
+ *
+ * Subscribes to step execution events from the EventPoller and dispatches
+ * them to the appropriate handlers via the HandlerRegistry.
+ *
+ * Matches Python's StepExecutionSubscriber pattern (TAS-92 aligned).
+ */
+
+/**
+ * Interface for handler registry required by StepExecutionSubscriber.
+ *
+ * TAS-93: Updated to support async resolution via ResolverChain.
+ * Returns ExecutableHandler which includes both StepHandler and MethodDispatchWrapper.
+ */
+interface HandlerRegistryInterface {
+    /** Resolve and instantiate a handler by name (async for resolver chain support) */
+    resolve(name: string): Promise<ExecutableHandler | null>;
+}
+/**
+ * Configuration for the step execution subscriber.
+ */
+interface StepExecutionSubscriberConfig {
+    /** Worker ID for result attribution */
+    workerId?: string;
+    /** Maximum concurrent handler executions (default: 10) */
+    maxConcurrent?: number;
+    /** Handler execution timeout in milliseconds (default: 300000 = 5 minutes) */
+    handlerTimeoutMs?: number;
+}
+/**
+ * Subscribes to step execution events and dispatches them to handlers.
+ *
+ * This is the critical component that connects the FFI event stream
+ * to TypeScript handler execution. It:
+ * 1. Listens for step events from the EventPoller via EventEmitter
+ * 2. Resolves the appropriate handler from the HandlerRegistry
+ * 3. Creates a StepContext from the FFI event
+ * 4. Executes the handler
+ * 5. Submits the result back to Rust via FFI
+ *
+ * @example
+ * ```typescript
+ * const subscriber = new StepExecutionSubscriber(
+ *   eventEmitter,
+ *   handlerRegistry,
+ *   runtime,
+ *   { workerId: 'worker-1' }
+ * );
+ *
+ * subscriber.start();
+ *
+ * // Later...
+ * subscriber.stop();
+ * ```
+ */
+declare class StepExecutionSubscriber {
+    private readonly emitter;
+    private readonly registry;
+    private readonly runtime;
+    private readonly workerId;
+    private readonly maxConcurrent;
+    private readonly handlerTimeoutMs;
+    private running;
+    private activeHandlers;
+    private processedCount;
+    private errorCount;
+    /**
+     * Create a new StepExecutionSubscriber.
+     *
+     * @param emitter - The event emitter to subscribe to (required, no fallback)
+     * @param registry - The handler registry for resolving step handlers
+     * @param runtime - The FFI runtime for submitting results (required, no fallback)
+     * @param config - Optional configuration for execution behavior
+     */
+    constructor(emitter: TaskerEventEmitter, registry: HandlerRegistryInterface, runtime: TaskerRuntime, config?: StepExecutionSubscriberConfig);
+    /**
+     * Start subscribing to step execution events.
+     */
+    start(): void;
+    /**
+     * Stop subscribing to step execution events.
+     *
+     * Note: Does not wait for in-flight handlers to complete.
+     * Use waitForCompletion() if you need to wait.
+     */
+    stop(): void;
+    /**
+     * Check if the subscriber is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get the count of events processed.
+     */
+    getProcessedCount(): number;
+    /**
+     * Get the count of errors encountered.
+     */
+    getErrorCount(): number;
+    /**
+     * Get the count of currently active handlers.
+     */
+    getActiveHandlers(): number;
+    /**
+     * Wait for all active handlers to complete.
+     *
+     * @param timeoutMs - Maximum time to wait (default: 30000)
+     * @returns True if all handlers completed, false if timeout
+     */
+    waitForCompletion(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Handle a step execution event.
+     */
+    private handleEvent;
+    /**
+     * Process a step execution event.
+     */
+    private processEvent;
+    /**
+     * Execute a function with a timeout.
+     */
+    private executeWithTimeout;
+    /**
+     * Extract handler name from FFI event.
+     *
+     * The handler name is in step_definition.handler.callable
+     */
+    private extractHandlerName;
+    /**
+     * Submit a handler result via FFI.
+     *
+     * TAS-125: Detects checkpoint yields and routes them to checkpointYieldStepEvent
+     * instead of the normal completion path.
+     */
+    private submitResult;
+    /**
+     * TAS-125: Submit a checkpoint yield via FFI.
+     *
+     * Called when a handler returns a checkpoint_yield result.
+     * This persists the checkpoint and re-dispatches the step.
+     */
+    private submitCheckpointYield;
+    /**
+     * Submit an error result via FFI (for handler resolution/execution failures).
+     */
+    private submitErrorResult;
+    /**
+     * Build a StepExecutionResult from a handler result.
+     *
+     * IMPORTANT: metadata.retryable must be set for Rust's is_retryable() to work correctly.
+     */
+    private buildExecutionResult;
+    /**
+     * Build an error StepExecutionResult for handler resolution/execution failures.
+     *
+     * IMPORTANT: metadata.retryable must be set for Rust's is_retryable() to work correctly.
+     */
+    private buildErrorExecutionResult;
+    /**
+     * Send a completion result to Rust via FFI and handle the response.
+     *
+     * @returns true if the completion was accepted by Rust, false otherwise
+     */
+    private sendCompletionViaFfi;
+    /**
+     * Handle successful FFI completion submission.
+     */
+    private handleFfiSuccess;
+    /**
+     * Handle FFI completion rejection (event not in pending map).
+     */
+    private handleFfiRejection;
+    /**
+     * Handle FFI completion error.
+     */
+    private handleFfiError;
+}
+
+/**
+ * EventSystem - Unified event processing system for TypeScript workers.
+ *
+ * This class owns and manages the complete event flow:
+ * - TaskerEventEmitter: Event bus for step events
+ * - EventPoller: Polls FFI for step events, emits to emitter
+ * - StepExecutionSubscriber: Subscribes to emitter, dispatches to handlers
+ *
+ * By owning all three components, EventSystem guarantees they share the
+ * same emitter instance, eliminating reference sharing bugs.
+ *
+ * Design principles:
+ * - Explicit construction: All dependencies injected via constructor
+ * - Clear ownership: This class owns the emitter lifecycle
+ * - Explicit lifecycle: start() and stop() methods with defined phases
+ */
+
+/**
+ * Configuration for EventPoller within EventSystem.
+ */
+interface EventPollerConfig {
+    /** Polling interval in milliseconds (default: 10) */
+    pollIntervalMs?: number;
+    /** Number of polls between starvation checks (default: 100) */
+    starvationCheckInterval?: number;
+    /** Number of polls between cleanup operations (default: 1000) */
+    cleanupInterval?: number;
+    /** Number of polls between metrics emissions (default: 100) */
+    metricsInterval?: number;
+    /** Maximum events to process per poll cycle (default: 100) */
+    maxEventsPerCycle?: number;
+}
+/**
+ * Configuration for StepExecutionSubscriber within EventSystem.
+ */
+interface SubscriberConfig {
+    /** Unique identifier for this worker (default: typescript-worker-{pid}) */
+    workerId?: string;
+    /** Maximum number of concurrent handler executions (default: 10) */
+    maxConcurrent?: number;
+    /** Timeout for individual handler execution in milliseconds (default: 300000) */
+    handlerTimeoutMs?: number;
+}
+/**
+ * Complete configuration for EventSystem.
+ */
+interface EventSystemConfig {
+    /** Configuration for the event poller */
+    poller?: EventPollerConfig;
+    /** Configuration for the step execution subscriber */
+    subscriber?: SubscriberConfig;
+}
+/**
+ * Statistics about the event system's operation.
+ */
+interface EventSystemStats {
+    /** Whether the system is currently running */
+    running: boolean;
+    /** Total events processed by the subscriber */
+    processedCount: number;
+    /** Total errors encountered during processing */
+    errorCount: number;
+    /** Number of currently active handler executions */
+    activeHandlers: number;
+    /** Total poll cycles executed */
+    pollCount: number;
+}
+/**
+ * Unified event processing system.
+ *
+ * Owns the complete event flow: emitter → poller → subscriber.
+ * Guarantees all components share the same emitter instance.
+ *
+ * @example
+ * ```typescript
+ * const eventSystem = new EventSystem(runtime, registry, {
+ *   poller: { pollIntervalMs: 10 },
+ *   subscriber: { workerId: 'worker-1', maxConcurrent: 10 },
+ * });
+ *
+ * eventSystem.start();
+ * // ... processing events ...
+ * await eventSystem.stop();
+ * ```
+ */
+declare class EventSystem {
+    private readonly emitter;
+    private readonly poller;
+    private readonly subscriber;
+    private running;
+    /**
+     * Create a new EventSystem.
+     *
+     * @param runtime - The FFI runtime for polling events and submitting results
+     * @param registry - The handler registry for resolving step handlers
+     * @param config - Optional configuration for poller and subscriber
+     */
+    constructor(runtime: TaskerRuntime, registry: HandlerRegistryInterface, config?: EventSystemConfig);
+    /**
+     * Start the event system.
+     *
+     * Starts the subscriber first (to register listeners), then the poller.
+     * This ensures no events are missed.
+     */
+    start(): void;
+    /**
+     * Stop the event system gracefully.
+     *
+     * Stops ingress first (poller), waits for in-flight handlers,
+     * then stops the subscriber.
+     *
+     * @param drainTimeoutMs - Maximum time to wait for in-flight handlers (default: 30000)
+     */
+    stop(drainTimeoutMs?: number): Promise<void>;
+    /**
+     * Check if the event system is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get the event emitter (for testing or advanced use cases).
+     */
+    getEmitter(): TaskerEventEmitter;
+    /**
+     * Get current statistics about the event system.
+     */
+    getStats(): EventSystemStats;
+}
+
+export { type MetricsCallback as A, type BatchWorkerConfig as B, type PollerState as C, type StepEventCallback as D, type ExecutableHandler as E, type EventSystemConfig as F, type EventSystemStats as G, type StepExecutionSubscriberConfig as H, ErrorType as I, isStandardErrorType as J, isTypicallyRetryable as K, type StepContextParams as L, type MetricsPayload as M, type StepHandlerResultParams as N, type PollerCyclePayload as P, StepHandlerResult as S, TaskerEventEmitter as T, type WorkerErrorPayload as W, StepHandler as a, StepContext as b, type StepHandlerClass as c, EventPoller as d, StepExecutionSubscriber as e, EventSystem as f, type StepCompletionSentPayload as g, type StepExecutionCompletedPayload as h, type StepExecutionFailedPayload as i, type StepExecutionReceivedPayload as j, type StepExecutionStartedPayload as k, type TaskerEventMap as l, type WorkerEventPayload as m, type EventName as n, EventNames as o, type MetricsEventName as p, MetricsEventNames as q, type PollerEventName as r, PollerEventNames as s, type StepEventName as t, StepEventNames as u, type WorkerEventName as v, WorkerEventNames as w, createEventPoller as x, type ErrorCallback as y, type EventPollerConfig$1 as z };