/**
 * Execution Trace - records decisions, metrics, and errors during strategy execution.
 *
 * The trace is mutable during execution but provides immutable snapshots for export.
 * This domain-level trace is distinct from the legacy strategies/shared ExecutionTrace.
 */
import type { Decision, ExecutionTraceData, TracedError } from "./types.js";
type IdGenerator = () => string;
type Clock = () => Date;
interface ExecutionTraceOptions {
    readonly executionId?: string;
    readonly startedAt?: Date;
    readonly now?: Clock;
    readonly idGenerator?: IdGenerator;
    readonly onFallbackId?: (fallbackId: string) => void;
}
/**
 * Execution Trace - records decisions, metrics, and errors during strategy execution.
 *
 * The trace is mutable during execution but provides immutable snapshots for export.
 *
 * @example
 * ```typescript
 * const trace = new ExecutionTrace('my-strategy', '1.0.0');
 *
 * trace.recordDecision(
 *   'select-template',
 *   'Selected enterprise template based on input size',
 *   { inputSize: 1500, threshold: 1000 }
 * );
 *
 * trace.recordMetric('generation_time_ms', 250);
 *
 * try {
 *   // operation
 * } catch (error) {
 *   trace.recordError(error, { operation: 'template-render' });
 * }
 *
 * // Export for debugging
 * const markdown = trace.toMarkdown();
 * ```
 */
export declare class ExecutionTrace {
    private readonly strategyName;
    private readonly strategyVersion;
    private readonly executionId;
    private readonly startedAt;
    private completedAt;
    private readonly now;
    private readonly idGenerator;
    private readonly _decisions;
    private readonly _metrics;
    private readonly _errors;
    constructor(strategyName: string, strategyVersion: string, options?: ExecutionTraceOptions);
    /**
     * Record a decision made during execution.
     *
     * @param category - Decision category (e.g., 'validation', 'generation', 'selection')
     * @param description - Human-readable description of the decision
     * @param context - Additional context (must be JSON-serializable)
     * @returns The recorded decision
     */
    recordDecision(category: string, description: string, context?: Record<string, unknown>): Decision;
    /**
     * Record a numeric metric.
     *
     * @param name - Metric name (e.g., 'generation_time_ms', 'token_count')
     * @param value - Metric value
     */
    recordMetric(name: string, value: number): void;
    /**
     * Increment a counter metric.
     *
     * @param name - Counter name
     * @param increment - Amount to increment (default: 1)
     */
    incrementMetric(name: string, increment?: number): void;
    /**
     * Record an error with context.
     *
     * @param error - The error that occurred
     * @param context - Additional context at time of error
     */
    recordError(error: Error, context?: Record<string, unknown>): void;
    /**
     * Mark the trace as complete.
     */
    complete(): void;
    /**
     * Get all recorded decisions.
     */
    get decisions(): readonly Decision[];
    /**
     * Get all recorded metrics.
     */
    get metrics(): Readonly<Record<string, number>>;
    /**
     * Get all recorded errors.
     */
    get errors(): readonly TracedError[];
    /**
     * Get current duration in milliseconds.
     */
    get durationMs(): number;
    /**
     * Check if any errors were recorded.
     */
    get hasErrors(): boolean;
    /**
     * Get decisions filtered by category.
     */
    getDecisionsByCategory(category: string): readonly Decision[];
    /**
     * Export trace as immutable data object.
     */
    toData(): ExecutionTraceData;
    /**
     * Export trace as JSON string.
     */
    toJSON(): string;
    /**
     * Export trace as Markdown for human-readable debugging.
     */
    toMarkdown(): string;
    /**
     * Sanitize context to ensure it's JSON-serializable.
     * Circular detection is scoped to the current traversal path; shared references
     * are serialized independently rather than de-duplicated (for example, if the
     * same object is referenced by two sibling keys, each key gets its own copy).
     * This can increase trace size when large objects are referenced multiple times.
     */
    private sanitizeContext;
    private sanitizeValue;
    private cloneDecision;
    private cloneError;
    private cloneDate;
    private cloneContext;
    private isRecord;
}
export {};
//# sourceMappingURL=execution-trace.d.ts.map