/**
 * Decision cross-link module for CLEO BRAIN.
 *
 * Extracts file paths and symbol names referenced in a decision's text and
 * rationale, then creates `affects` edges from the decision graph node to
 * matching `file` / `symbol` nodes in brain_page_nodes.  This implements
 * the cross-substrate edge described in
 * docs/plans/brain-synaptic-visualization-research.md §3.2.
 *
 * All database operations are best-effort — they never throw or block the
 * caller.  Nodes for referenced files / symbols are upserted on demand so
 * the graph remains consistent even when the target has not yet been
 * independently indexed.
 *
 * @task T626
 * @epic T626
 */
import type { DatabaseSync } from 'node:sqlite';
import type { DecisionCodeEvidenceLink, DecisionCodeEvidenceOptions, DecisionCodeEvidenceResult } from '@cleocode/contracts';
/** A reference extracted from a decision or rationale string. */
export interface ExtractedRef {
    /** Raw text that matched. */
    raw: string;
    /** Resolved graph node ID: 'file:<path>' or 'symbol:<name>'. */
    nodeId: string;
    /** Discriminated node type. */
    nodeType: 'file' | 'symbol';
    /** Human-readable label for the graph node. */
    label: string;
}
/**
 * Extract file-path and symbol references from free-form text.
 *
 * Symbols shorter than 4 characters or matching common English stop-words
 * are filtered to reduce noise.
 *
 * @param text - Decision text and/or rationale to scan.
 * @returns Deduplicated array of extracted references.
 */
export declare function extractReferencedSymbols(text: string): ExtractedRef[];
/**
 * Create `affects` edges from a decision graph node to every referenced
 * file / symbol node.
 *
 * For each reference:
 *  1. Upsert the target node (file or symbol) so the graph stays consistent.
 *  2. Insert an `applies_to` edge from `decision:<id>` to the target node.
 *
 * All writes are best-effort via {@link upsertGraphNode} and
 * {@link addGraphEdge} — failures are swallowed internally.
 *
 * @param projectRoot - Absolute path to the project root directory.
 * @param decisionId  - The decision ID (e.g. `D001`).
 * @param refs        - Extracted references returned by {@link extractReferencedSymbols}.
 */
export declare function linkDecisionToTargets(projectRoot: string, decisionId: string, refs: ExtractedRef[]): Promise<void>;
/**
 * Extract file/symbol references from a decision and create `applies_to`
 * edges in the brain graph.  Combines {@link extractReferencedSymbols} and
 * {@link linkDecisionToTargets} in one call.
 *
 * This is the function wired into {@link storeDecision} after a new decision
 * is saved. storeDecision AWAITS it (T13565): a fire-and-forget call outlived
 * the decision write and could re-bind the brain domain on a fresh connection
 * mid-teardown, stalling the next writer for the full busy_timeout. The
 * function still swallows every error internally, so awaiting never surfaces
 * a failure to the decision write path.
 *
 * @param projectRoot  - Absolute path to the project root directory.
 * @param decisionId   - The saved decision ID (e.g. `D001`).
 * @param decisionText - Full decision text.
 * @param rationale    - Full rationale text.
 */
export declare function autoCrossLinkDecision(projectRoot: string, decisionId: string, decisionText: string, rationale: string): Promise<void>;
/**
 * Decode explicit decision provenance for inspectable link projections.
 * @param provenance - Stored edge provenance; legacy strings are not treated as sourced evidence.
 * @returns Validated provenance or null for legacy/malformed metadata.
 * @remarks Parsing alone does not establish current freshness; use the current-state checker as well.
 * @example
 * ```ts
 * const evidence = readDecisionCodeEvidence(edge.provenance);
 * ```
 */
export declare function readDecisionCodeEvidence(provenance: string | null): DecisionCodeEvidenceLink | null;
/**
 * Check stored decision relationships against current sources without deleting history.
 * @param db - Canonical project brain handle sharing the Nexus graph store.
 * @param provenance - Serialized edge provenance, including legacy provenance strings.
 * @returns False for stale sourced links; legacy links remain explicitly unverified by consumers.
 * @remarks Generation, canonical decision authority/content, and target file hashes are checked.
 * @example
 * ```ts
 * const current = isCurrentDecisionCodeEvidence(db, edge.provenance);
 * ```
 */
export declare function isCurrentDecisionCodeEvidence(db: DatabaseSync, provenance: string | null): boolean;
/**
 * Assess or backfill explicit decision-to-task-to-file and named-symbol relationships.
 * @param projectRoot - Canonical project identity root, independent of configured source roots.
 * @param decisionId - Canonical accepted decision ID, with or without the decision prefix.
 * @param options - Explicit symbol targets and optional deterministic persistence.
 * @returns Source-bearing links and actionable unresolved findings; repeated backfills apply zero changes.
 * @remarks File evidence targets file nodes only. Historical edge provenance is retained before refresh.
 * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
 * @example
 * ```ts
 * const report = await linkDecisionToCodeEvidence(projectRoot, 'D001', { apply: true });
 * ```
 */
export declare function linkDecisionToCodeEvidence(projectRoot: string, decisionId: string, options?: DecisionCodeEvidenceOptions): Promise<DecisionCodeEvidenceResult>;
//# sourceMappingURL=decision-cross-link.d.ts.map