/**
 * Memory Engine Compatibility Layer — Brain.db Cognitive Memory
 *
 * Async wrappers around brain.db cognitive memory functions that return
 * EngineResult<T> format for consumption by the dispatch layer.
 *
 * After the memory domain cutover (T5241), this file contains ONLY
 * brain.db-backed operations. Manifest operations moved to
 * pipeline-manifest-compat.ts, and context injection moved to
 * sessions/context-inject.ts.
 *
 * @task T5241
 * @epic T5149
 */
import type { EngineResult } from '../engine-result.js';
import { type SearchLearningParams, type StoreLearningParams } from './learnings.js';
import { type SearchPatternParams, type StorePatternParams } from './patterns.js';
/**
 * Look up a brain.db entry by ID.
 *
 * @param entryId - Brain entry ID with type prefix (D-, P-, L-, O-, or CM-)
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult containing the typed entry data on success
 *
 * @remarks
 * Parses the ID prefix to determine the entry type (decision, pattern, learning,
 * or observation) and queries the corresponding brain.db table.
 *
 * @example
 * ```typescript
 * const result = await memoryShow('O-abc123', '/project');
 * if (result.success) console.log(result.data.type, result.data.entry);
 * ```
 */
export declare function memoryShow(entryId: string, projectRoot?: string): Promise<EngineResult>;
/**
 * Aggregate stats from brain.db across all tables.
 *
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with observation, decision, pattern, and learning counts
 *
 * @remarks
 * Queries each brain.db table for row counts and returns a combined statistics object.
 * Returns zero counts if brain.db is not initialized.
 *
 * @example
 * ```typescript
 * const result = await memoryBrainStats('/project');
 * if (result.success) console.log(result.data.observations);
 * ```
 */
export declare function memoryBrainStats(projectRoot?: string): Promise<EngineResult>;
/**
 * Search decisions in brain.db.
 *
 * By default, AGT-* agent dispatch rows are excluded from results so that
 * `cleo memory decision-find` returns only architectural/technical decisions.
 * Pass `includeAgentDispatch: true` to surface execution history as well.
 *
 * @param params - Search parameters (query, limit, includeAgentDispatch, etc.)
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with matching decision entries
 *
 * @remarks
 * Queries the brain.db decisions table with optional text filtering and pagination.
 * T1830: adds `decision_category != 'agent_dispatch'` filter by default.
 *
 * @example
 * ```typescript
 * // Architectural decisions only (default):
 * const result = await memoryDecisionFind({ query: 'auth' }, '/project');
 * // Include AGT-* dispatch rows:
 * const all = await memoryDecisionFind({ query: 'auth', includeAgentDispatch: true }, '/project');
 * ```
 */
export declare function memoryDecisionFind(params: {
    query?: string;
    taskId?: string;
    limit?: number;
    includeAgentDispatch?: boolean;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Store a decision to brain.db.
 *
 * @param params - Decision data including title, rationale, and alternatives
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with the stored decision ID
 *
 * @remarks
 * Creates a new decision entry in brain.db with a D-prefixed ID.
 * Optionally refreshes the memory bridge after storing.
 *
 * @example
 * ```typescript
 * const result = await memoryDecisionStore({ title: 'Use SQLite', rationale: 'Embedded, fast' }, '/project');
 * ```
 */
export declare function memoryDecisionStore(params: {
    decision: string;
    rationale: string;
    alternatives?: string[];
    taskId?: string;
    sessionId?: string;
    adrPath?: string | null;
    supersedes?: string | null;
    confirmationState?: 'proposed' | 'accepted' | 'superseded';
    decidedBy?: 'owner' | 'council' | 'agent';
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Token-efficient brain search returning compact results.
 *
 * @param params - Search parameters including query string and limit
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with compact search hits (IDs and titles)
 *
 * @remarks
 * Designed for the cheapest-first retrieval pattern. Returns minimal fields
 * per hit to conserve tokens. Use memoryFetch for full entry details.
 *
 * @example
 * ```typescript
 * const result = await memoryFind({ query: 'authentication', limit: 10 }, '/project');
 * ```
 */
export declare function memoryFind(params: {
    query: string;
    limit?: number;
    tables?: string[];
    dateStart?: string;
    dateEnd?: string;
    /** T418: filter results to observations produced by a specific agent. */
    agent?: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Chronological context around a brain entry anchor.
 *
 * @param params - Timeline parameters including anchor ID and window size
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with chronologically ordered entries around the anchor
 *
 * @remarks
 * Retrieves entries before and after a given anchor ID for temporal context.
 * Useful for understanding the sequence of observations and decisions.
 *
 * @example
 * ```typescript
 * const result = await memoryTimeline({ anchorId: 'O-abc123', window: 5 }, '/project');
 * ```
 */
export declare function memoryTimeline(params: {
    anchor: string;
    depthBefore?: number;
    depthAfter?: number;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Batch fetch brain entries by IDs.
 *
 * @param params - Fetch parameters including an array of entry IDs
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with full entry details for each requested ID
 *
 * @remarks
 * Use after memoryFind to retrieve full details for specific entries.
 * Part of the 3-layer retrieval pattern: search -> filter -> fetch.
 *
 * @example
 * ```typescript
 * const result = await memoryFetch({ ids: ['O-abc123', 'D-def456'] }, '/project');
 * ```
 */
export declare function memoryFetch(params: {
    ids: string[];
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Save an observation to brain.db.
 *
 * @param params - Observation data including text, title, and optional tags
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with the stored observation ID
 *
 * @remarks
 * Creates a new observation entry in brain.db with an O-prefixed ID.
 * Optionally refreshes the memory bridge after storing.
 *
 * @example
 * ```typescript
 * const result = await memoryObserve({ text: 'Auth uses JWT', title: 'Auth discovery' }, '/project');
 * ```
 */
export declare function memoryObserve(params: {
    text: string;
    title?: string;
    type?: string;
    project?: string;
    sourceSessionId?: string;
    sourceType?: string;
    /** T417: agent provenance — name of the spawned agent producing this observation. */
    agent?: string;
    /**
     * T799: SHA-256 refs of attachments to link to this observation.
     * Passed through to `observeBrain` and stored in `attachments_json`.
     */
    attachmentRefs?: string[];
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Store a pattern to BRAIN memory.
 *
 * @param params - Pattern data including pattern string, type, and confidence
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with the stored pattern ID
 *
 * @remarks
 * Persists a detected pattern (success or failure) to brain.db for future scoring.
 *
 * @example
 * ```typescript
 * const result = await memoryPatternStore({ pattern: 'migration', type: 'success' }, '/project');
 * ```
 */
export declare function memoryPatternStore(params: StorePatternParams, projectRoot?: string): Promise<EngineResult>;
/**
 * Search patterns in BRAIN memory.
 *
 * @param params - Search parameters including query and type filter
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with matching pattern entries
 *
 * @remarks
 * Queries the brain.db patterns table with optional type filtering.
 *
 * @example
 * ```typescript
 * const result = await memoryPatternFind({ type: 'success', limit: 10 }, '/project');
 * ```
 */
export declare function memoryPatternFind(params: SearchPatternParams, projectRoot?: string): Promise<EngineResult>;
/**
 * Get pattern memory statistics.
 *
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with pattern counts by type and overall totals
 *
 * @remarks
 * Aggregates pattern data from brain.db to provide type distribution and counts.
 *
 * @example
 * ```typescript
 * const result = await memoryPatternStats('/project');
 * ```
 */
export declare function memoryPatternStats(projectRoot?: string): Promise<EngineResult>;
/**
 * Store a learning to BRAIN memory.
 *
 * @param params - Learning data including text and confidence level
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with the stored learning ID
 *
 * @remarks
 * Creates a new learning entry in brain.db with an L-prefixed ID.
 *
 * @example
 * ```typescript
 * const result = await memoryLearningStore({ text: 'Drizzle v1 requires beta flag' }, '/project');
 * ```
 */
export declare function memoryLearningStore(params: StoreLearningParams, projectRoot?: string): Promise<EngineResult>;
/**
 * Search learnings in BRAIN memory.
 *
 * @param params - Search parameters including query and limit
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with matching learning entries
 *
 * @remarks
 * Queries the brain.db learnings table with optional text filtering.
 *
 * @example
 * ```typescript
 * const result = await memoryLearningFind({ query: 'drizzle' }, '/project');
 * ```
 */
export declare function memoryLearningFind(params: SearchLearningParams, projectRoot?: string): Promise<EngineResult>;
/**
 * Get learning memory statistics.
 *
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with learning counts and confidence distribution
 *
 * @remarks
 * Aggregates learning data from brain.db to provide totals and breakdowns.
 *
 * @example
 * ```typescript
 * const result = await memoryLearningStats('/project');
 * ```
 */
export declare function memoryLearningStats(projectRoot?: string): Promise<EngineResult>;
/**
 * Find contradictory entries in brain.db.
 *
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with pairs of contradicting observations
 *
 * @remarks
 * Scans brain.db for observations that contradict each other based on
 * semantic similarity and opposing sentiment or content.
 *
 * @example
 * ```typescript
 * const result = await memoryContradictions('/project');
 * if (result.success) console.log(result.data.contradictions);
 * ```
 */
export declare function memoryContradictions(projectRoot?: string): Promise<EngineResult>;
/**
 * Find superseded entries in brain.db.
 *
 * Identifies entries that have been superseded by newer entries on the same topic.
 *
 * @param params - Superseded search parameters
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with superseded entry pairs and their replacements
 *
 * @remarks
 * Scans brain.db for entries where a newer observation or decision covers
 * the same topic, rendering the older entry obsolete.
 *
 * For brain.db, we group by:
 * - Decisions: type + contextTaskId/contextEpicId
 * - Patterns: type + context (first 100 chars for similarity)
 * - Learnings: source + applicableTypes
 * - Observations: type + project
 *
 * @example
 * ```typescript
 * const result = await memorySuperseded({ type: 'decision' }, '/project');
 * ```
 */
export declare function memorySuperseded(params?: {
    type?: string;
    project?: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Link a brain entry to a task.
 *
 * @param params - Link parameters including entryId and taskId
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult confirming the link was created
 *
 * @remarks
 * Creates an association between a brain.db entry and a task in tasks.db.
 * Used for traceability between memory entries and the work they relate to.
 *
 * @example
 * ```typescript
 * const result = await memoryLink({ entryId: 'O-abc123', taskId: 'T042' }, '/project');
 * ```
 */
export declare function memoryLink(params: {
    taskId: string;
    entryId: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Remove a link between a brain entry and a task.
 *
 * @param params - Unlink parameters including entryId and taskId
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult confirming the link was removed
 *
 * @remarks
 * Removes the association created by memoryLink. Idempotent if the link
 * does not exist.
 *
 * @example
 * ```typescript
 * const result = await memoryUnlink({ entryId: 'O-abc123', taskId: 'T042' }, '/project');
 * ```
 */
export declare function memoryUnlink(params: {
    taskId: string;
    entryId: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Add a node or edge to the PageIndex graph.
 *
 * @param params - Graph add parameters (node data or edge endpoints)
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult confirming the node or edge was added
 *
 * @remarks
 * Supports adding both nodes (concepts) and edges (relationships) to the
 * brain.db knowledge graph (PageIndex).
 *
 * @example
 * ```typescript
 * const result = await memoryGraphAdd({ type: 'node', label: 'auth', nodeType: 'concept' }, '/project');
 * ```
 */
export declare function memoryGraphAdd(params: {
    nodeId?: string;
    nodeType?: string;
    label?: string;
    metadataJson?: string;
    fromId?: string;
    toId?: string;
    edgeType?: string;
    weight?: number;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Get a node and its edges from the PageIndex graph.
 *
 * @param params - Parameters including the node ID to look up
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with the node data and its connected edges
 *
 * @remarks
 * Returns the full node record plus all edges where the node appears as
 * either source or target.
 *
 * @example
 * ```typescript
 * const result = await memoryGraphShow({ nodeId: 'auth' }, '/project');
 * ```
 */
export declare function memoryGraphShow(params: {
    nodeId: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Get neighbor nodes from the PageIndex graph.
 *
 * @param params - Parameters including the node ID and optional depth
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with neighboring nodes and connecting edges
 *
 * @remarks
 * Traverses the knowledge graph outward from a given node to find related
 * concepts within the specified depth.
 *
 * @example
 * ```typescript
 * const result = await memoryGraphNeighbors({ nodeId: 'auth', depth: 2 }, '/project');
 * ```
 */
export declare function memoryGraphNeighbors(params: {
    nodeId: string;
    edgeType?: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Causal trace through task dependency chains.
 *
 * @param params - Parameters including the entry or task ID to trace
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with the causal chain explaining why something happened
 *
 * @remarks
 * Traces backward through task dependencies and brain entries to build
 * an explanation chain for a given decision or observation.
 *
 * @example
 * ```typescript
 * const result = await memoryReasonWhy({ id: 'D-abc123' }, '/project');
 * ```
 */
export declare function memoryReasonWhy(params: {
    taskId: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Find semantically similar entries.
 *
 * @param params - Parameters including the source entry ID or query text
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with entries ranked by semantic similarity
 *
 * @remarks
 * Uses embedding vectors or text similarity to find brain entries that are
 * semantically close to the given reference.
 *
 * @example
 * ```typescript
 * const result = await memoryReasonSimilar({ id: 'O-abc123', limit: 5 }, '/project');
 * ```
 */
export declare function memoryReasonSimilar(params: {
    entryId: string;
    limit?: number;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Hybrid search across FTS5, vector, and graph.
 *
 * @param params - Search parameters including query and optional mode/limit
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with merged and ranked results from all search backends
 *
 * @remarks
 * Combines full-text search (FTS5), vector similarity, and graph traversal
 * to produce comprehensive search results with merged relevance scoring.
 *
 * @example
 * ```typescript
 * const result = await memorySearchHybrid({ query: 'authentication flow' }, '/project');
 * ```
 */
export declare function memorySearchHybrid(params: {
    query: string;
    limit?: number;
    /**
     * @deprecated Weight parameters are unused — hybrid search now uses
     * Reciprocal Rank Fusion (RRF) which is rank-based and does not require
     * per-source weights. This field is accepted but silently ignored.
     */
    ftsWeight?: number;
    /**
     * @deprecated Weight parameters are unused — hybrid search now uses
     * Reciprocal Rank Fusion (RRF) which is rank-based and does not require
     * per-source weights. This field is accepted but silently ignored.
     */
    vecWeight?: number;
    /**
     * @deprecated Weight parameters are unused — hybrid search now uses
     * Reciprocal Rank Fusion (RRF) which is rank-based and does not require
     * per-source weights. This field is accepted but silently ignored.
     */
    graphWeight?: number;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * BFS traversal of the brain knowledge graph from a seed node.
 *
 * @param params - Traversal parameters: nodeId and optional maxDepth (default 3)
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with traversal nodes annotated with depth
 *
 * @remarks
 * Uses a recursive CTE against brain_page_nodes / brain_page_edges.
 * Follows edges bidirectionally. Returns the seed node at depth 0.
 *
 * @example
 * ```typescript
 * const result = await memoryGraphTrace({ nodeId: 'decision:D-abc123', maxDepth: 2 }, '/project');
 * ```
 */
export declare function memoryGraphTrace(params: {
    nodeId: string;
    maxDepth?: number;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Return the immediate (1-hop) neighbours of a brain graph node.
 *
 * @param params - Parameters: nodeId, optional edgeType filter
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with neighbour nodes and edge metadata
 *
 * @remarks
 * Follows edges in both directions. Results include direction ('in'/'out'),
 * edge type, and weight.
 *
 * @example
 * ```typescript
 * const result = await memoryGraphRelated({ nodeId: 'decision:D-abc123', edgeType: 'applies_to' }, '/project');
 * ```
 */
export declare function memoryGraphRelated(params: {
    nodeId: string;
    edgeType?: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Return a 360-degree context view of a single brain graph node.
 *
 * @param params - Parameters: nodeId
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with the node, all edges, and neighbouring nodes
 *
 * @remarks
 * Includes the node itself, in-edges, out-edges, and all immediately
 * reachable neighbour nodes with their edge relationships.
 *
 * @example
 * ```typescript
 * const result = await memoryGraphContext({ nodeId: 'decision:D-abc123' }, '/project');
 * ```
 */
export declare function memoryGraphContext(params: {
    nodeId: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Return aggregate statistics for the brain knowledge graph.
 *
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult with node counts by type, edge counts by type, and totals
 *
 * @example
 * ```typescript
 * const result = await memoryGraphStatsFull('/project');
 * ```
 */
export declare function memoryGraphStatsFull(projectRoot?: string): Promise<EngineResult>;
/**
 * Remove a node or edge from the PageIndex graph.
 *
 * @param params - Parameters specifying the node or edge to remove
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult confirming the removal
 *
 * @remarks
 * Removes a node (and its connected edges) or a specific edge from the
 * brain.db knowledge graph.
 *
 * @example
 * ```typescript
 * const result = await memoryGraphRemove({ type: 'node', nodeId: 'stale-concept' }, '/project');
 * ```
 */
export declare function memoryGraphRemove(params: {
    nodeId?: string;
    fromId?: string;
    toId?: string;
    edgeType?: string;
}, projectRoot?: string): Promise<EngineResult>;
/**
 * Return the BRAIN memory quality dashboard report.
 *
 * Aggregates retrieval log, usage log, and all four typed tables to produce
 * a MemoryQualityReport with tier distribution, top/never-retrieved entries,
 * quality score distribution, and noise ratio.
 *
 * @param projectRoot - Optional project root path; defaults to resolved root
 * @returns EngineResult containing a MemoryQualityReport object
 *
 * @example
 * ```typescript
 * const result = await memoryQualityReport('/project');
 * if (result.success) console.log(result.data.noiseRatio);
 * ```
 */
export declare function memoryQualityReport(projectRoot?: string): Promise<EngineResult>;
//# sourceMappingURL=engine-compat.d.ts.map