/**
 * Performance profiling instrumentation for Manifest runtime engine.
 *
 * Records timing data for each execution phase to enable performance analysis
 * and flame graph visualization in diagnostic tools.
 */
/**
 * Execution phases that can be profiled during command execution.
 * These correspond to the fixed execution order defined in the spec:
 * policies -> constraints -> guards -> approval gate -> actions -> emits -> return
 */
export type ExecutionPhase = 'total' | 'tenantContextGate' | 'idempotencyCheck' | 'asyncDispatch' | 'policyEvaluation' | 'constraintValidation' | 'guardEvaluation' | 'approvalGate' | 'autoCreate' | 'actionExecution' | 'eventEmission' | 'reactionCascading' | 'computedEvaluation';
/**
 * Detailed timing information for a single execution phase.
 */
export interface PhaseTiming {
    /** The phase being measured */
    phase: ExecutionPhase;
    /** Duration in milliseconds (high precision) */
    duration: number;
    /** Timestamp when the phase started (relative to command start) */
    startOffset: number;
    /** Timestamp when the phase ended (relative to command start) */
    endOffset: number;
    /** Nested timing data for sub-operations (e.g., individual guards, actions) */
    children?: PhaseTiming[];
    /** Optional metadata about the phase (e.g., expression evaluated, constraint name) */
    metadata?: PhaseMetadata;
}
/**
 * Optional metadata attached to phase timing for context.
 */
export interface PhaseMetadata {
    /** Name of the item being executed (e.g., guard index, action type) */
    name?: string;
    /** Expression or operation being performed */
    expression?: string;
    /** Count of items processed (e.g., number of policies evaluated) */
    count?: number;
    /** Index of the item in a loop (e.g., guard index) */
    index?: number;
    /** Entity name if applicable */
    entityName?: string;
    /** Command name if applicable */
    commandName?: string;
}
/**
 * Complete profile data for a single command execution.
 */
export interface CommandProfile {
    /** Entity name (if applicable) */
    entityName?: string;
    /** Command being executed */
    commandName: string;
    /** Instance ID (if applicable) */
    instanceId?: string;
    /** Total execution duration in milliseconds */
    totalDuration: number;
    /** Timestamp when execution started (Unix timestamp ms) */
    startTime: number;
    /** Timestamp when execution ended (Unix timestamp ms) */
    endTime: number;
    /** Whether the command succeeded */
    success: boolean;
    /** Per-phase timing data (ordered by execution) */
    phases: PhaseTiming[];
    /** Slowest individual expression evaluation (if available) */
    slowestExpression?: {
        phase: ExecutionPhase;
        expression: string;
        duration: number;
    };
    /** Number of entities in the entity graph (for complexity analysis) */
    entityGraphSize?: number;
    /** Number of instances loaded during execution */
    instancesLoaded?: number;
}
/**
 * Aggregated profile data across multiple command executions.
 * Used for CLI summary output.
 */
export interface ProfileSummary {
    /** Total commands profiled */
    totalCommands: number;
    /** Total execution time across all commands */
    totalDuration: number;
    /** Average command duration */
    averageDuration: number;
    /** Slowest command */
    slowestCommand: {
        commandName: string;
        entityName?: string;
        duration: number;
    };
    /** Fastest command */
    fastestCommand: {
        commandName: string;
        entityName?: string;
        duration: number;
    };
    /** Per-phase statistics */
    phaseStats: Map<ExecutionPhase, PhaseStats>;
    /** Commands sorted by duration (slowest first) */
    slowestCommands: Array<{
        commandName: string;
        entityName?: string;
        duration: number;
    }>;
}
/**
 * Statistics for a single execution phase across multiple runs.
 */
export interface PhaseStats {
    /** Total time spent in this phase */
    totalDuration: number;
    /** Average duration per command */
    averageDuration: number;
    /** Maximum duration */
    maxDuration: number;
    /** Percentage of total execution time */
    percentOfTotal: number;
    /** Number of times this phase was executed */
    executionCount: number;
}
/**
 * A collector that accumulates timing data during command execution.
 * Instances are created per-command and attached to the execution context.
 */
export declare class ProfileCollector {
    private phases;
    private startTime;
    private commandStartTime;
    private currentPhaseStart;
    private slowestExpression;
    /** Start a new command profiling session */
    start(startTime: number): void;
    /** Mark the start of a phase */
    startPhase(phase: ExecutionPhase): void;
    /** Mark the end of a phase and record its timing */
    endPhase(phase: ExecutionPhase, metadata?: PhaseMetadata, children?: PhaseTiming[]): void;
    /** Complete profiling and return the final profile data */
    complete(commandName: string, entityName: string | undefined, instanceId: string | undefined, success: boolean, entityGraphSize?: number, instancesLoaded?: number): CommandProfile;
    /** Get current phase timing data (for intermediate reporting) */
    getPhases(): ReadonlyArray<PhaseTiming>;
    /** Get the current elapsed time since profiling started */
    getElapsed(): number;
}
/**
 * Runtime options for enabling/disabling profiling.
 */
export interface ProfilingOptions {
    /** If true, collect detailed timing data for each command execution */
    enabled?: boolean;
    /** Optional callback to receive profile data after each command */
    onProfileComplete?: (profile: CommandProfile) => void;
    /** If true, include detailed per-operation timing (e.g., each guard, each action) */
    detailed?: boolean;
}
/**
 * Aggregate multiple command profiles into a summary.
 */
export declare function summarizeProfiles(profiles: CommandProfile[]): ProfileSummary;
/**
 * Convert profile data to a flame graph format suitable for visualization.
 * Returns a hierarchical structure with phases and children.
 */
export declare function toFlameGraph(profile: CommandProfile): FlameGraphNode;
/**
 * Flame graph node structure for visualization.
 */
export interface FlameGraphNode {
    /** Display name for the node */
    name: string;
    /** Duration in milliseconds */
    value: number;
    /** Execution phase */
    phase: ExecutionPhase;
    /** Child nodes (sub-operations) */
    children?: FlameGraphNode[];
    /** Optional metadata */
    metadata?: PhaseMetadata;
}
//# sourceMappingURL=profiling.d.ts.map