/**
 * Runtime workflow context for simplified workflow interaction.
 *
 * Provides a context object that wraps workflow execution state and
 * provides convenient methods for state management, transitions,
 * SLA tracking, and compensation.
 *
 * @module workflow/context
 *
 * @example
 * ```typescript
 * import { createWorkflowContext, WorkflowRunner } from '@contractspec/lib.contracts-spec';
 *
 * // Create context from running workflow
 * const ctx = createWorkflowContext(runner, workflowId);
 *
 * // Access state
 * console.log(ctx.currentStep);
 * console.log(ctx.state.data);
 *
 * // Check transitions
 * if (ctx.canTransition('review')) {
 *   await ctx.transition('review', { approved: true });
 * }
 *
 * // Track SLA
 * if (ctx.isSlaViolated('totalDuration')) {
 *   console.log('Remaining time:', ctx.getRemainingTime('totalDuration'));
 * }
 * ```
 */
import type { Step, WorkflowSpec } from './spec';
import type { StepExecution, WorkflowState } from './state';
/**
 * Error thrown when a workflow operation fails.
 */
export declare class WorkflowContextError extends Error {
    readonly errorType: WorkflowContextErrorType;
    readonly workflowId: string;
    readonly details?: Record<string, unknown>;
    constructor(type: WorkflowContextErrorType, workflowId: string, message: string, details?: Record<string, unknown>);
}
export type WorkflowContextErrorType = 'invalid_transition' | 'workflow_completed' | 'workflow_failed' | 'step_not_found' | 'guard_rejected' | 'sla_violated';
export interface WorkflowTransitionResult {
    success: boolean;
    previousStep: string;
    currentStep: string;
    status: WorkflowState['status'];
    error?: string;
}
export interface AvailableTransition {
    from: string;
    to: string;
    label?: string;
    condition?: string;
}
export interface SlaStatus {
    key: string;
    type: 'workflow' | 'step';
    stepId?: string;
    limitMs: number;
    elapsedMs: number;
    remainingMs: number;
    violated: boolean;
    percentUsed: number;
}
export interface WorkflowEvent {
    timestamp: Date;
    type: 'step_started' | 'step_completed' | 'step_failed' | 'step_retried' | 'transition';
    stepId?: string;
    fromStep?: string;
    toStep?: string;
    input?: unknown;
    output?: unknown;
    error?: string;
}
/**
 * Runtime context for interacting with a workflow instance.
 *
 * Provides a simplified interface over WorkflowRunner for common
 * workflow operations like state access, transitions, and SLA tracking.
 */
export interface WorkflowContext<TData extends Record<string, unknown> = Record<string, unknown>> {
    /** Unique workflow instance identifier. */
    readonly workflowId: string;
    /** Workflow spec key. */
    readonly workflowKey: string;
    /** Workflow spec version. */
    readonly workflowVersion: string;
    /** Current step identifier. */
    readonly currentStep: string;
    /** Current workflow status. */
    readonly status: WorkflowState['status'];
    /** Workflow data/state. */
    readonly data: TData;
    /** Execution history. */
    readonly history: readonly StepExecution[];
    /**
     * Get the current workflow state.
     * @returns Full workflow state object
     */
    getState(): WorkflowState<TData>;
    /**
     * Get a value from workflow data.
     * @param key - Data key to retrieve
     * @returns Value or undefined
     */
    getData<Key extends keyof TData>(key: Key): TData[Key] | undefined;
    /**
     * Check if workflow is in a terminal state.
     * @returns True if completed, failed, or cancelled
     */
    isTerminal(): boolean;
    /**
     * Check if workflow is running.
     * @returns True if status is 'running'
     */
    isRunning(): boolean;
    /**
     * Get the current step definition.
     * @returns Step definition or undefined
     */
    getCurrentStepDef(): Step | undefined;
    /**
     * Get the retry count for a step.
     * @param stepId - Step to check (defaults to current step)
     * @returns Number of retry attempts
     */
    getRetryCount(stepId?: string): number;
    /**
     * Check if a transition to a target step is valid.
     * @param toStepId - Target step identifier
     * @returns True if transition is valid from current step
     */
    canTransition(toStepId: string): boolean;
    /**
     * Get all available transitions from current step.
     * @returns Array of available transitions
     */
    getAvailableTransitions(): AvailableTransition[];
    /**
     * Check if the current step has any outgoing transitions.
     * @returns True if there are outgoing transitions
     */
    hasNextStep(): boolean;
    /**
     * Get remaining time for an SLA constraint.
     * @param slaKey - 'totalDuration' or step ID
     * @returns Remaining milliseconds, or null if no SLA configured
     */
    getRemainingTime(slaKey: string): number | null;
    /**
     * Check if an SLA constraint has been violated.
     * @param slaKey - 'totalDuration' or step ID
     * @returns True if SLA has been violated
     */
    isSlaViolated(slaKey: string): boolean;
    /**
     * Get status of all SLA constraints.
     * @returns Array of SLA statuses
     */
    getAllSlaStatuses(): SlaStatus[];
    /**
     * Check if compensation/rollback is available.
     * @returns True if workflow has compensation strategy
     */
    hasCompensation(): boolean;
    /**
     * Get steps that have compensation handlers.
     * @returns Array of step IDs with compensation
     */
    getCompensableSteps(): string[];
    /**
     * Convert execution history to workflow events.
     * @returns Array of workflow events
     */
    getEvents(): WorkflowEvent[];
}
/**
 * Creates a workflow context from state and spec.
 *
 * @param state - Current workflow state
 * @param spec - Workflow specification
 * @returns WorkflowContext for interacting with the workflow
 *
 * @example
 * ```typescript
 * const state = await runner.getState(workflowId);
 * const spec = registry.get(state.workflowName, state.workflowVersion);
 * const ctx = createWorkflowContext(state, spec);
 *
 * console.log('Current step:', ctx.currentStep);
 * console.log('Available transitions:', ctx.getAvailableTransitions());
 * ```
 */
export declare function createWorkflowContext<TData extends Record<string, unknown> = Record<string, unknown>>(state: WorkflowState<TData>, spec: WorkflowSpec): WorkflowContext<TData>;
/**
 * Calculate workflow progress as a percentage.
 *
 * @param ctx - Workflow context
 * @returns Progress percentage (0-100)
 */
export declare function calculateWorkflowProgress(ctx: WorkflowContext): number;
/**
 * Get the duration of a workflow in milliseconds.
 *
 * @param ctx - Workflow context
 * @returns Duration in milliseconds
 */
export declare function getWorkflowDuration(ctx: WorkflowContext): number;
/**
 * Get the average step duration in milliseconds.
 *
 * @param ctx - Workflow context
 * @returns Average duration or 0 if no completed steps
 */
export declare function getAverageStepDuration(ctx: WorkflowContext): number;
