/**
 * BRAIN Retrieval Operations — 3-layer pattern (search -> timeline -> fetch).
 *
 * Provides token-efficient memory access modeled after claude-mem's
 * search/timeline/get_observations workflow:
 *
 * 1. searchBrainCompact — lightweight index (IDs + titles, ~50 tokens/hit)
 * 2. timelineBrain      — chronological context around an anchor entry
 * 3. fetchBrainEntries  — full details for a filtered set of IDs
 * 4. observeBrain       — unified save (observations table)
 *
 * Wave 2A provides the core implementations; Wave 2B wires them through
 * the dispatch layer (engine-compat -> domain handler -> CLI gateway).
 *
 * @task T5131 T5132 T5133 T5134 T5135
 * @epic T5149
 */
import type { NextDirectives } from '../mvi-helpers.js';
import type { BRAIN_OBSERVATION_SOURCE_TYPES, BRAIN_OBSERVATION_TYPES, BrainSourceConfidence } from '../store/brain-schema.js';
import type { BrainAnchor } from './brain-row-types.js';
/** Compact search hit — minimal fields for index-level results. */
export interface BrainCompactHit {
    id: string;
    type: 'decision' | 'pattern' | 'learning' | 'observation';
    title: string;
    date: string;
    relevance?: number;
    /** Progressive disclosure directives for follow-up operations. */
    _next?: NextDirectives;
}
/** Parameters for searchBrainCompact. */
export interface SearchBrainCompactParams {
    query: string;
    limit?: number;
    tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
    dateStart?: string;
    dateEnd?: string;
    /** T418: filter results to observations produced by a specific agent (Wave 8 mental models). */
    agent?: string;
    /**
     * When true (default), use Reciprocal Rank Fusion to combine FTS5 and
     * vector search results for higher recall and better ranking.
     * When false, fall back to FTS5-only search (faster, no embeddings needed).
     */
    useRRF?: boolean;
}
/** Result from searchBrainCompact. */
export interface SearchBrainCompactResult {
    results: BrainCompactHit[];
    total: number;
    tokensEstimated: number;
}
/** Parameters for timelineBrain. */
export interface TimelineBrainParams {
    anchor: string;
    depthBefore?: number;
    depthAfter?: number;
}
/** Timeline entry — compact id/type/date tuple. */
export interface TimelineNeighbor {
    id: string;
    type: string;
    date: string;
}
/** Result from timelineBrain. */
export interface TimelineBrainResult {
    anchor: BrainAnchor | null;
    before: TimelineNeighbor[];
    after: TimelineNeighbor[];
}
/** Parameters for fetchBrainEntries. */
export interface FetchBrainEntriesParams {
    ids: string[];
}
/** Fetched entry with full data. */
export interface FetchedBrainEntry {
    id: string;
    type: string;
    data: unknown;
}
/** Result from fetchBrainEntries. */
export interface FetchBrainEntriesResult {
    results: FetchedBrainEntry[];
    notFound: string[];
    tokensEstimated: number;
}
/** Observation type from schema. */
export type BrainObservationType = (typeof BRAIN_OBSERVATION_TYPES)[number];
/** Observation source type from schema. */
export type BrainObservationSourceType = (typeof BRAIN_OBSERVATION_SOURCE_TYPES)[number];
/** Parameters for observeBrain. */
export interface ObserveBrainParams {
    text: string;
    title?: string;
    type?: BrainObservationType;
    project?: string;
    sourceSessionId?: string;
    sourceType?: BrainObservationSourceType;
    /** T417: agent provenance — the name of the spawned agent producing this observation. */
    agent?: string;
    /**
     * T549 Wave 1-A: source reliability level.
     * Overrides the default routing. If omitted, routing is determined automatically:
     * - sourceType 'manual' → 'owner'
     * - sourceType 'session-debrief' → 'task-outcome'
     * - otherwise → 'agent'
     */
    sourceConfidence?: BrainSourceConfidence;
}
/** Result from observeBrain. */
export interface ObserveBrainResult {
    id: string;
    type: string;
    createdAt: string;
}
/**
 * Token-efficient compact search across BRAIN tables.
 * Returns index-level hits (~50 tokens per result).
 *
 * Delegates to searchBrain() from brain-search.ts for FTS5/LIKE search,
 * then projects results to a compact format with optional date filtering.
 *
 * @param projectRoot - Project root directory
 * @param params - Search parameters
 * @returns Compact search results with token estimate
 */
export declare function searchBrainCompact(projectRoot: string, params: SearchBrainCompactParams): Promise<SearchBrainCompactResult>;
/**
 * Get chronological context around an anchor entry.
 * Fetches the anchor's full data, then queries all 4 BRAIN tables
 * via UNION ALL to find chronological neighbors.
 *
 * @param projectRoot - Project root directory
 * @param params - Timeline parameters with anchor ID and depth
 * @returns Anchor entry data with surrounding chronological entries
 */
export declare function timelineBrain(projectRoot: string, params: TimelineBrainParams): Promise<TimelineBrainResult>;
/**
 * Batch-fetch full details by IDs.
 * Groups IDs by prefix to query the correct tables via BrainDataAccessor.
 *
 * @param projectRoot - Project root directory
 * @param params - Fetch parameters with IDs
 * @returns Full entry data for each found ID, plus not-found list
 */
export declare function fetchBrainEntries(projectRoot: string, params: FetchBrainEntriesParams): Promise<FetchBrainEntriesResult>;
/**
 * Save an observation to the BRAIN observations table.
 * Replaces the external claude-mem save_observation pattern.
 *
 * Auto-classifies type from text if not provided. Generates a
 * unique ID with O- prefix + base36 timestamp.
 *
 * @param projectRoot - Project root directory
 * @param params - Observation data
 * @returns Created observation ID, type, and timestamp
 */
export declare function observeBrain(projectRoot: string, params: ObserveBrainParams): Promise<ObserveBrainResult>;
/** Result from populateEmbeddings backfill. */
export interface PopulateEmbeddingsResult {
    processed: number;
    skipped: number;
    errors: number;
}
/**
 * Options for the embedding backfill pipeline.
 *
 * @example
 * ```ts
 * await populateEmbeddings(root, {
 *   batchSize: 25,
 *   onProgress: (current, total) => console.log(`${current}/${total}`),
 * });
 * ```
 */
export interface PopulateEmbeddingsOptions {
    /** Maximum items processed per batch cycle. Defaults to 50. */
    batchSize?: number;
    /**
     * Progress callback invoked after each observation is attempted.
     * `current` is the 1-based count of observations attempted so far;
     * `total` is the full count of observations that need embeddings.
     */
    onProgress?: (current: number, total: number) => void;
}
/**
 * Backfill embeddings for existing observations that lack them.
 *
 * Iterates through observations not yet in brain_embeddings and
 * generates vectors using the registered embedding provider.
 * Processes in batches to avoid memory pressure.
 *
 * An optional {@link PopulateEmbeddingsOptions.onProgress} callback is called
 * after each observation is attempted, enabling callers to report progress.
 *
 * @param projectRoot - Project root directory
 * @param options - Optional batch size and progress callback
 * @returns Count of processed, skipped, and errored observations
 *
 * @epic T134
 * @task T142
 */
export declare function populateEmbeddings(projectRoot: string, options?: PopulateEmbeddingsOptions): Promise<PopulateEmbeddingsResult>;
/** Options for budget-aware retrieval. */
export interface BudgetedRetrievalOptions {
    /** Filter by cognitive types (semantic / episodic / procedural). */
    types?: Array<'semantic' | 'episodic' | 'procedural'>;
    /** Filter by memory tiers (short / medium / long). */
    tiers?: Array<'short' | 'medium' | 'long'>;
    /** When true, only return verified entries. Default: false. */
    verified?: boolean;
}
/** A single entry returned by budget-aware retrieval. */
export interface BudgetedEntry {
    id: string;
    type: string;
    title: string;
    text: string;
    /** Fused relevance score: FTS50% + vector40% + graph10% × qualityScore. */
    score: number;
    /** Estimated token cost for this entry (~chars/4). */
    tokensEstimated: number;
    /** Memory tier for this entry. */
    memoryTier?: string;
    /** Cognitive type for this entry. */
    memoryType?: string;
}
/** Result from retrieveWithBudget. */
export interface BudgetedResult {
    entries: BudgetedEntry[];
    /** Total tokens consumed by returned entries. */
    tokensUsed: number;
    /** Tokens remaining from the original budget. */
    tokensRemaining: number;
    /** Number of entries excluded due to budget constraints. */
    excluded: number;
}
/**
 * Budget-aware hybrid retrieval combining FTS5, vector KNN, and graph neighbor scores.
 *
 * Strategy (parallel where possible):
 *   A. FTS5 BM25 search (always)  — keyword precision (50% weight)
 *   B. Vector KNN search (optional) — semantic recall (40% weight, skipped if no embeddings)
 *   C. Graph neighbors (optional) — associative context (10% weight, skipped if graph empty)
 *
 * Score fusion: final = (fts*0.50 + vec*0.40 + graph*0.10) × qualityScore
 * Recency boost: +0.05 for entries updated in last 7 days.
 * Type priority: procedural entries get +0.10 (always-useful rules).
 *
 * Budget enforcement:
 *   - Rank top-50 candidates by fused score.
 *   - Walk list, accumulate token cost (≈ textLen/4), stop at budget.
 *   - Episodic entries dropped first when budget is tight.
 *
 * Citation tracking: increments citationCount for returned entries in background (setImmediate).
 *
 * @param projectRoot - Project root directory
 * @param query - Text to search for
 * @param tokenBudget - Maximum tokens to spend on results (default 500)
 * @param options - Optional filters (types, tiers, verified)
 * @returns Retrieved entries within budget with token accounting
 */
export declare function retrieveWithBudget(projectRoot: string, query: string, tokenBudget?: number, options?: BudgetedRetrievalOptions): Promise<BudgetedResult>;
//# sourceMappingURL=brain-retrieval.d.ts.map