import type * as v from '../../../shared/src/valita.ts';
import type { Condition, Ordering } from '../../../zero-protocol/src/ast.ts';
import type { attemptStartEventJSONSchema, bestPlanSelectedEventJSONSchema, connectionSelectedEventJSONSchema, nodeConstraintEventJSONSchema, PlanDebugEventJSON, planFailedEventJSONSchema } from '../../../zero-protocol/src/analyze-query-result.ts';
import type { PlannerConstraint } from './planner-constraint.ts';
import type { CostEstimate, JoinType } from './planner-node.ts';
import type { PlanState } from './planner-graph.ts';
/**
 * Structured debug events emitted during query planning.
 * These events can be accumulated, printed, or analyzed to understand
 * the planner's decision-making process.
 */
/**
 * Starting a new planning attempt with a different root connection.
 */
export type AttemptStartEvent = v.Infer<typeof attemptStartEventJSONSchema>;
/**
 * Snapshot of connection costs before selecting the next connection.
 */
export type ConnectionCostsEvent = {
    type: 'connection-costs';
    attemptNumber: number;
    costs: Array<{
        connection: string;
        cost: number;
        costEstimate: Omit<CostEstimate, 'fanout'>;
        pinned: boolean;
        constraints: Record<string, PlannerConstraint | undefined>;
        constraintCosts: Record<string, Omit<CostEstimate, 'fanout'>>;
    }>;
};
/**
 * A connection was chosen and pinned.
 */
export type ConnectionSelectedEvent = v.Infer<typeof connectionSelectedEventJSONSchema>;
/**
 * Constraints have been propagated through the graph.
 */
export type ConstraintsPropagatedEvent = {
    type: 'constraints-propagated';
    attemptNumber: number;
    connectionConstraints: Array<{
        connection: string;
        constraints: Record<string, PlannerConstraint | undefined>;
        constraintCosts: Record<string, Omit<CostEstimate, 'fanout'>>;
    }>;
};
/**
 * A complete plan was found for this attempt.
 */
export type PlanCompleteEvent = {
    type: 'plan-complete';
    attemptNumber: number;
    totalCost: number;
    flipPattern: number;
    joinStates: Array<{
        join: string;
        type: JoinType;
    }>;
    planSnapshot: PlanState;
};
/**
 * Planning attempt failed (e.g., unflippable join).
 */
export type PlanFailedEvent = v.Infer<typeof planFailedEventJSONSchema>;
/**
 * The best plan across all attempts was selected.
 */
export type BestPlanSelectedEvent = v.Infer<typeof bestPlanSelectedEventJSONSchema>;
/**
 * A node computed its cost estimate during planning.
 * Emitted by nodes during estimateCost() traversal.
 * attemptNumber is added by the debugger.
 */
export type NodeCostEvent = {
    type: 'node-cost';
    attemptNumber?: number;
    nodeType: 'connection' | 'join' | 'fan-out' | 'fan-in' | 'terminus';
    node: string;
    branchPattern: number[];
    downstreamChildSelectivity: number;
    costEstimate: Omit<CostEstimate, 'fanout'>;
    filters?: Condition | undefined;
    ordering?: Ordering | undefined;
    joinType?: JoinType | undefined;
};
/**
 * A node received constraints during constraint propagation.
 * Emitted by nodes during propagateConstraints() traversal.
 * attemptNumber is added by the debugger.
 */
export type NodeConstraintEvent = v.Infer<typeof nodeConstraintEventJSONSchema>;
/**
 * Union of all debug event types.
 */
export type PlanDebugEvent = AttemptStartEvent | ConnectionCostsEvent | ConnectionSelectedEvent | ConstraintsPropagatedEvent | PlanCompleteEvent | PlanFailedEvent | BestPlanSelectedEvent | NodeCostEvent | NodeConstraintEvent;
/**
 * Interface for objects that receive debug events during planning.
 */
export interface PlanDebugger {
    log(event: PlanDebugEvent): void;
}
/**
 * Simple accumulator debugger that stores all events.
 * Useful for tests and debugging.
 */
export declare class AccumulatorDebugger implements PlanDebugger {
    readonly events: PlanDebugEvent[];
    private currentAttempt;
    log(event: PlanDebugEvent): void;
    /**
     * Get all events of a specific type.
     */
    getEvents<T extends PlanDebugEvent['type']>(type: T): Extract<PlanDebugEvent, {
        type: T;
    }>[];
    /**
     * Format events as a human-readable string.
     */
    format(): string;
}
/**
 * Serialize an array of debug events to JSON-compatible format.
 * The fanout function is already omitted when events are created.
 * The planSnapshot is excluded as it's internal state not needed for debugging.
 */
export declare function serializePlanDebugEvents(events: PlanDebugEvent[]): PlanDebugEventJSON[];
/**
 * Format planner debug events as a human-readable string.
 * Works with JSON-serialized events (from inspector API) or native events (from AccumulatorDebugger).
 *
 * @param events - Array of planner debug events (either JSON or native format)
 * @returns Formatted string showing planning attempts, costs, and final plan selection
 *
 * @example
 * ```typescript
 * const result = await inspector.analyzeQuery(query, { joinPlans: true });
 * if (result.joinPlans) {
 *   console.log(formatPlannerEvents(result.joinPlans));
 * }
 * ```
 */
export declare function formatPlannerEvents(events: PlanDebugEventJSON[] | PlanDebugEvent[]): string;
//# sourceMappingURL=planner-debug.d.ts.map