/**
 * BRAIN Reasoning — causal trace through task dependency chains and code symbols.
 *
 * `reasonWhy(taskId)` walks upstream through a task's blocker chain,
 * enriching each node with related brain_decisions. Leaf tasks with
 * no further unresolved blockers are identified as root causes.
 *
 * `reasonWhySymbol(symbolId)` traces a code symbol through BRAIN edges
 * (code_reference, documents, applies_to) to brain decisions and their
 * originating tasks, returning a human-readable narrative and chain.
 *
 * @task T5390, T1069
 * @epic T5149, T1042
 */
import type { CodeReasonTrace } from '@cleocode/contracts';
import type { DataAccessor } from '../store/data-accessor.js';
import type { BrainDecisionNode } from './brain-row-types.js';
export interface BlockerNode {
    taskId: string;
    status: string;
    reason?: string;
    decisions: BrainDecisionNode[];
}
export interface CausalTrace {
    taskId: string;
    blockers: BlockerNode[];
    rootCauses: string[];
    depth: number;
}
/**
 * Build a causal trace for why a task is blocked.
 *
 * Walks upstream through `depends` fields, collecting unresolved blockers
 * and their associated brain decisions. Leaf blockers (no further unresolved
 * deps) are reported as root causes.
 */
export declare function reasonWhy(taskId: string, projectRoot: string, taskAccessor?: DataAccessor): Promise<CausalTrace>;
/**
 * Trace why a code symbol exists / is structured this way.
 *
 * Walks: symbol → reverse `code_reference`/`documents`/`applies_to` edges
 * to brain_page_nodes (observations + decisions) → those decisions'
 * `context_task_id` → tasks → `task_touches_symbol` edges to other symbols.
 *
 * Returns a typed `CodeReasonTrace` with a narrative and step chain.
 *
 * @param symbolId - Nexus node ID or symbol name (looked up in nexus.db)
 * @param projectRoot - Absolute path to project root
 * @returns Code reason trace (never throws — empty chain on error)
 */
export declare function reasonWhySymbol(symbolId: string, projectRoot: string): Promise<CodeReasonTrace>;
export interface SimilarEntry {
    id: string;
    distance: number;
    type: string;
    title: string;
    text: string;
}
/**
 * Find entries similar to a given brain.db entry.
 *
 * 1. Loads the source entry's text from brain.db.
 * 2. Calls searchSimilar() for vector-based similarity if embeddings exist.
 * 3. Falls back to FTS5 keyword search if no embeddings are available.
 * 4. Filters out the source entry itself.
 *
 * @param entryId - ID of the brain.db entry to find similar entries for
 * @param projectRoot - Project root directory
 * @param limit - Maximum results to return (default 10)
 * @returns Array of similar entries ranked by distance/relevance
 */
export declare function reasonSimilar(entryId: string, projectRoot: string, limit?: number): Promise<SimilarEntry[]>;
//# sourceMappingURL=brain-reasoning.d.ts.map