/**
 * Telemetry module — opt-in command telemetry for CLEO self-improvement.
 *
 * Entry point for all telemetry operations:
 *   - Recording events (buffered in-process, flushed on exit — T9051)
 *   - Querying patterns for `cleo diagnostics analyze`
 *   - Managing the anonymous ID and opt-in state
 *   - Emitting BRAIN observations from high-signal patterns
 *   - Retention / rotation (prune events older than N days — T9051)
 *
 * Telemetry is DISABLED by default. Enable with `cleo diagnostics enable`.
 * Opt-in is EXPLICIT — no data is written until the user runs that command.
 * New installs start with an absent config file, which resolves to disabled.
 *
 * @task T624
 */
/**
 * Default retention window in days.
 * Events older than this are deleted during pruning.
 */
export declare const TELEMETRY_RETENTION_DAYS = 90;
/**
 * Maximum row count before the table is pruned regardless of age.
 * Prevents unbounded growth on long-lived installs.
 */
export declare const TELEMETRY_MAX_ROWS = 50000;
/** A single telemetry event to record. */
export interface TelemetryEvent {
    /** Canonical domain (e.g. "tasks", "session"). */
    domain: string;
    /** CQRS gateway. */
    gateway: 'query' | 'mutate';
    /** Operation name (e.g. "show", "add"). */
    operation: string;
    /** Wall-clock duration in milliseconds. */
    durationMs: number;
    /** LAFS exit code (0 = success). */
    exitCode: number;
    /** Machine-readable error code (null on success). */
    errorCode?: string | null;
}
/** Aggregated stats for a single command. */
export interface CommandStats {
    /** Composed "{domain}.{operation}" command name. */
    command: string;
    /** Total invocation count. */
    count: number;
    /** Count of invocations that returned exitCode != 0. */
    failureCount: number;
    /** Failure rate as a fraction (0..1). */
    failureRate: number;
    /** Mean duration in milliseconds. */
    avgDurationMs: number;
    /** Max duration in milliseconds. */
    maxDurationMs: number;
    /** Most frequent error code, or null if no failures. */
    topErrorCode: string | null;
}
/** Aggregated diagnostics summary. */
export interface DiagnosticsReport {
    /** Period analyzed (ISO-8601 start and end). */
    period: {
        from: string;
        to: string;
    };
    /** Total events in period. */
    totalEvents: number;
    /** Top 10 commands by failure rate (min 5 invocations). */
    topFailing: CommandStats[];
    /** Top 10 slowest commands by average duration. */
    topSlow: CommandStats[];
    /** Commands invoked exactly once (potential dead ends). */
    rareCommands: string[];
    /** High-signal observations suitable for BRAIN storage. */
    observations: string[];
}
/** Global telemetry config stored in ~/.local/share/cleo/telemetry-config.json */
export interface TelemetryConfig {
    /** Whether telemetry collection is enabled. */
    enabled: boolean;
    /** Anonymous UUID stable across invocations. Generated on first enable. */
    anonymousId: string;
}
/** Return the path to the telemetry config JSON file. */
export declare function getTelemetryConfigPath(): string;
/** Load telemetry config from disk. Returns default (disabled) config if absent. */
export declare function loadTelemetryConfig(): TelemetryConfig;
/** Persist telemetry config to disk. */
export declare function saveTelemetryConfig(config: TelemetryConfig): void;
/** Return true if telemetry collection is currently enabled. */
export declare function isTelemetryEnabled(): boolean;
/**
 * Enable telemetry and generate a stable anonymous ID.
 * Idempotent — calling again preserves the existing anonymousId.
 */
export declare function enableTelemetry(): TelemetryConfig;
/**
 * Disable telemetry collection.
 * Existing data in telemetry.db is not deleted.
 */
export declare function disableTelemetry(): TelemetryConfig;
/**
 * Record one telemetry event.
 *
 * Events are buffered in-process (T9051) and flushed on process exit or when
 * the buffer reaches {@link TELEMETRY_BUFFER_MAX_EVENTS}. Fire-and-forget —
 * errors are swallowed; never blocks the calling command.
 *
 * No-op when telemetry is disabled (opt-in required per T9051 privacy posture).
 */
export declare function recordTelemetryEvent(event: TelemetryEvent): Promise<void>;
/**
 * Flush any buffered telemetry events immediately.
 *
 * Exposed for testing and for callers that need deterministic flushing
 * (e.g. the diagnostics analyze command). Not required in normal usage.
 */
export declare function flushTelemetryBuffer(): Promise<void>;
/**
 * Build a diagnostics report over the last `days` days (default 30).
 * Requires telemetry to be enabled; returns null if disabled or no data.
 */
export declare function buildDiagnosticsReport(days?: number): Promise<DiagnosticsReport | null>;
/**
 * Export all telemetry events as a JSON array.
 * Returns empty array when telemetry is disabled or DB is empty.
 */
export declare function exportTelemetryEvents(days?: number): Promise<TelemetryEvent[]>;
/**
 * Prune telemetry events older than `retentionDays` days.
 *
 * Also enforces the max-row cap: when the table exceeds
 * {@link TELEMETRY_MAX_ROWS}, the oldest rows beyond the cap are deleted.
 *
 * Call this from `cleo diagnostics analyze` (or a periodic maintenance job)
 * to prevent unbounded database growth.
 *
 * @param retentionDays - Events older than this many days are deleted.
 *   Defaults to {@link TELEMETRY_RETENTION_DAYS} (90 days).
 * @returns Number of rows deleted.
 */
export declare function pruneOldTelemetryEvents(retentionDays?: number): Promise<number>;
/**
 * Reset the in-process telemetry buffer and exit-handler registration state.
 *
 * FOR TESTING ONLY. Ensures each test starts with a clean buffer so that
 * events from previous tests do not bleed into subsequent test assertions.
 *
 * @internal
 */
export declare function resetTelemetryBufferState(): void;
export * from '../store/schema/telemetry-schema.js';
export { getTelemetryDb, getTelemetryDbPath } from './sqlite.js';
//# sourceMappingURL=index.d.ts.map