/**
 * Brain graph traversal queries using recursive CTEs and native SQLite.
 *
 * Implements BFS traversal, typed neighbor lookup, 360-degree context view,
 * and aggregate statistics for the brain_page_nodes / brain_page_edges graph
 * populated by T528 + T530.
 *
 * Uses getBrainNativeDb() (DatabaseSync) for recursive CTEs that Drizzle's
 * ORM layer cannot express directly.
 *
 * @task T535
 * @epic T523
 */
import type { BrainEdgeType, BrainPageEdgeRow, BrainPageNodeRow } from '../store/brain-schema.js';
/** A node returned from a BFS traversal, annotated with its discovery depth. */
export interface TraceNode extends BrainPageNodeRow {
    /** Distance from the seed node (0 = seed itself). */
    depth: number;
}
/** A neighbor node with the edge that connects it to the queried node. */
export interface RelatedNode {
    /** The neighbour node. */
    node: BrainPageNodeRow;
    /** Edge relationship type. */
    edgeType: BrainEdgeType;
    /** Direction: 'out' (queried node is from_id) or 'in' (queried node is to_id). */
    direction: 'out' | 'in';
    /** Edge weight/confidence 0.0–1.0. */
    weight: number;
}
/** Full context for a single node: itself, incoming edges, outgoing edges, and neighbour nodes. */
export interface NodeContext {
    /** The node itself. */
    node: BrainPageNodeRow;
    /** Edges where this node is the target (in-edges). */
    inEdges: BrainPageEdgeRow[];
    /** Edges where this node is the source (out-edges). */
    outEdges: BrainPageEdgeRow[];
    /** All neighbour nodes reachable via in- or out-edges, deduplicated. */
    neighbors: RelatedNode[];
}
/** Aggregate statistics for the graph. */
export interface GraphStats {
    /** Node counts grouped by node_type. */
    nodesByType: Array<{
        nodeType: string;
        count: number;
    }>;
    /** Edge counts grouped by edge_type. */
    edgesByType: Array<{
        edgeType: string;
        count: number;
    }>;
    /** Total node count. */
    totalNodes: number;
    /** Total edge count. */
    totalEdges: number;
}
/**
 * Traverse the brain knowledge graph using BFS from a seed node.
 *
 * Uses a recursive CTE that follows edges in both directions. Nodes are
 * returned in ascending depth order, then descending quality_score. The seed
 * node itself is returned at depth 0.
 *
 * @param projectRoot - Absolute path to the project root (locates brain.db)
 * @param nodeId      - Starting node ID (format: '<type>:<source-id>')
 * @param maxDepth    - Maximum traversal depth (default 3)
 * @returns Array of nodes annotated with their discovery depth
 *
 * @example
 * ```typescript
 * const nodes = await traceBrainGraph('/project', 'decision:D-abc123', 2);
 * for (const n of nodes) console.log(n.depth, n.id, n.label);
 * ```
 */
export declare function traceBrainGraph(projectRoot: string, nodeId: string, maxDepth?: number): Promise<TraceNode[]>;
/**
 * Return the immediate (1-hop) neighbours of a node, including edge metadata.
 *
 * Follows edges in both directions. Results are sorted by edge weight
 * descending, then quality_score descending.
 *
 * @param projectRoot - Absolute path to the project root
 * @param nodeId      - Node to inspect (format: '<type>:<source-id>')
 * @param edgeType    - Optional edge type filter (e.g. 'applies_to')
 * @returns Array of neighbour nodes with edge relationship info
 *
 * @example
 * ```typescript
 * const related = await relatedBrainNodes('/project', 'decision:D-abc123', 'applies_to');
 * ```
 */
export declare function relatedBrainNodes(projectRoot: string, nodeId: string, edgeType?: string): Promise<RelatedNode[]>;
/**
 * Return a 360-degree view of a single graph node.
 *
 * Provides the node itself, all incoming edges, all outgoing edges, and the
 * full set of neighbour nodes with their edge relationships.
 *
 * @param projectRoot - Absolute path to the project root
 * @param nodeId      - Node to inspect (format: '<type>:<source-id>')
 * @returns Full context record, or null if the node does not exist
 *
 * @example
 * ```typescript
 * const ctx = await contextBrainNode('/project', 'decision:D-abc123');
 * if (ctx) {
 *   console.log(ctx.node.label, ctx.outEdges.length, 'outgoing edges');
 * }
 * ```
 */
export declare function contextBrainNode(projectRoot: string, nodeId: string): Promise<NodeContext | null>;
/**
 * Return aggregate counts for brain_page_nodes and brain_page_edges by type.
 *
 * @param projectRoot - Absolute path to the project root
 * @returns Counts by node type and edge type, plus totals
 *
 * @example
 * ```typescript
 * const stats = await graphStats('/project');
 * console.log(stats.totalNodes, stats.totalEdges);
 * ```
 */
export declare function graphStats(projectRoot: string): Promise<GraphStats>;
//# sourceMappingURL=graph-queries.d.ts.map