/**
 * Brain noise detector — T1262 memory-doctor (read-only, parallel to E1).
 *
 * Inspects `.cleo/brain.db` for known noise patterns without modifying any
 * data. The detector is a prerequisite for the W7 shadow-write sweep
 * (T1147 / v2026.4.132) and the M7 assert-clean gate that guards Sentient v1
 * activation (T1148 / v2026.4.133).
 *
 * **Read-only contract** — this module MUST NOT write to brain.db or any
 * other persistent store. All operations are SELECT-only. The sweep
 * (mutation) phase ships in T1147 W7 under a shadow-write envelope.
 *
 * ## Noise pattern catalogue
 *
 * | Pattern | Description | Detectable via |
 * |---------|-------------|----------------|
 * | `duplicate-content` | Entries with identical `content` hash across different IDs | SHA-256 content comparison |
 * | `missing-type` | Entries where `type` is NULL or empty string | NULL/empty check |
 * | `missing-provenance` | Entries where `provenance` is NULL (unverified source) | NULL check |
 * | `orphan-edge` | Brain graph edges pointing to non-existent nodes | JOIN gap |
 * | `low-confidence` | `confidence < 0.1` entries (near-zero signal, likely noise) | threshold check |
 * | `stale-unverified` | Unverified entries older than 90 days with zero retrieval count | age + retrieval join |
 *
 * @module memory/brain-doctor
 * @task T1262 memory-doctor detector (E1-parallel, read-only)
 * @task T1258 E1 canonical naming refactor
 * @see T1147 W7 for the mutator sweep that acts on these findings
 * @see T1148 W8 M7 gate — `cleo memory doctor --assert-clean` must exit 0 before Sentient v1
 */
/** A single detected noise entry. */
export interface BrainNoiseEntry {
    /** Noise pattern identifier. */
    pattern: NoisePattern;
    /** Number of brain entries matching this pattern. */
    count: number;
    /** Sample entry IDs (up to 5) for human inspection. */
    sampleIds: string[];
    /** Human-readable description of the pattern. */
    description: string;
}
/** Union of known noise pattern identifiers. */
export type NoisePattern = 'duplicate-content' | 'missing-type' | 'missing-provenance' | 'orphan-edge' | 'low-confidence' | 'stale-unverified';
/**
 * Auto-extract pipeline health metrics surfaced in `cleo doctor brain` (T1903).
 *
 * Pulled from the live brain.db — reflects the current state, not a historical
 * run. Shows whether the promotion pipeline is producing learnings at a healthy rate.
 */
export interface AutoExtractHealth {
    /** Total rows in brain_observations (valid only). */
    observationCount: number;
    /** Total rows in brain_learnings (valid only). */
    learningCount: number;
    /** Pending promotion_log rows (not yet fulfilled). */
    pendingPromotions: number;
    /** Fulfilled promotion_log rows (successfully converted to typed entries). */
    fulfilledPromotions: number;
    /** Ratio of learnings to observations (0–1). Values below 0.01 indicate a broken pipeline. */
    extractionRatio: number;
    /** Most recent consolidation event timestamp, or null if none. */
    lastConsolidationAt: string | null;
    /** Whether the extraction pipeline appears healthy (ratio > 0.01 OR no observations). */
    healthy: boolean;
}
/** Result of a brain noise scan. */
export interface BrainDoctorResult {
    /**
     * Total number of brain entries scanned.
     * Covers all typed tables: observations, decisions, patterns, learnings.
     */
    totalScanned: number;
    /** All detected noise entries, grouped by pattern. */
    findings: BrainNoiseEntry[];
    /**
     * `true` when zero noise patterns were detected across all tables.
     * This is the condition checked by `cleo memory doctor --assert-clean`.
     */
    isClean: boolean;
    /** ISO 8601 timestamp when the scan completed. */
    scannedAt: string;
    /**
     * Auto-extract pipeline health (T1903).
     * Shows whether observations are being promoted to learnings at a healthy rate.
     */
    autoExtractHealth?: AutoExtractHealth;
    /**
     * Provenance distribution counts (T1897).
     * Shows how many observations have each origin value (manual, auto-extract, etc.)
     * and how many have been ground-truth verified via validated_at.
     */
    provenanceDistribution?: ProvenanceDistribution;
}
/** Provenance distribution in brain_observations (T1897). */
export interface ProvenanceDistribution {
    /** Total observations (valid only). */
    total: number;
    /** Count by origin value (null = legacy rows without origin). */
    byOrigin: Record<string, number>;
    /** Count with validated_at set (ground-truth verified). */
    verifiedCount: number;
    /** Count with provenance_chain set (derived rows). */
    derivedCount: number;
}
/**
 * Run a read-only noise scan over `.cleo/brain.db` and return a structured
 * findings report.
 *
 * This function is intentionally side-effect-free: it opens brain.db in
 * read-only mode (via `getBrainNativeDb`) and only runs SELECT queries.
 * The caller bears responsibility for surfacing or acting on the findings.
 *
 * @param projectRoot - Absolute path to the CLEO project root.
 * @returns A {@link BrainDoctorResult} describing all detected noise.
 *
 * @example
 * ```typescript
 * const result = await scanBrainNoise('/mnt/projects/cleocode');
 * if (!result.isClean) {
 *   console.warn(`Brain noise detected: ${result.findings.length} patterns`);
 *   for (const f of result.findings) {
 *     console.warn(`  ${f.pattern}: ${f.count} entries — ${f.description}`);
 *   }
 * }
 * ```
 *
 * @task T1262
 */
export declare function scanBrainNoise(projectRoot: string): Promise<BrainDoctorResult>;
//# sourceMappingURL=brain-doctor.d.ts.map