import type { ContextPackExecutionSlice, ContextPackRuntimeGenerationAnswerContract, CompiledContextPack, ContextPackClaim, ContextPackCoverage, ContextPackEvidenceClass, ContextPackExpandableRef, ContextPackNode, ContextRepresentationType, ContextPackRetrievalStrategy, ContextPackSelectionDiagnostics, ContextPackSliceMetadata, ContextPackTaskContract, ContextPackTaskKind } from '../contracts/context-pack.js';
import type { ContextPackRetrievalPlanDetail } from '../contracts/retrieval-plan.js';
import type { ContextPackRecoveryPlan } from '../contracts/context-recovery.js';
import type { TaskIntentKind } from '../contracts/task-intent.js';
import { KnowledgeGraph } from '../contracts/graph.js';
import { type SourceDomain } from '../shared/source-discovery.js';
import type { RetrievalGateDecision, RetrievalLevel } from '../contracts/retrieval-gate.js';
import { type RetrievalStageObserver } from './retrieve/pipeline.js';
export { tokenizeLabel, tokenizeQuestion } from './retrieve/pipeline.js';
export declare const DEFAULT_RETRIEVE_SNIPPET_BUDGET = 3000;
export declare const DEFAULT_RETRIEVE_TOP_N_WITH_SNIPPET = 8;
export declare const DEFAULT_RETRIEVE_STDIO_OUTPUT_TOKENS = 4000;
export interface RetrieveOptions {
    question: string;
    budget: number;
    taskKind?: ContextPackTaskKind;
    taskIntent?: TaskIntentKind;
    community?: number;
    fileType?: string;
    semantic?: boolean;
    semanticModel?: string;
    rerank?: boolean;
    rerankerModel?: string;
    /** Project root used to resolve the optional transformers package when the
     *  server itself runs from elsewhere (npx cache, global install). */
    projectRoot?: string;
    /** #75 manual override for the retrieval gate. When set (0-5), the gate
     *  bypasses heuristic classification and emits a decision with reason
     *  'manual override' at the supplied level. Caller-side surface for the
     *  acceptance criterion that the gate be overridable via CLI/MCP. */
    retrievalLevel?: RetrievalLevel;
    retrievalStrategy?: ContextPackRetrievalStrategy;
    snippetBudget?: number;
    topNWithSnippet?: number;
    /** Source-safe stage timing/count observer; never receives prompts, paths, labels, or snippets. */
    onStageDiagnostic?: RetrievalStageObserver;
}
export interface RetrieveSnippetOptions {
    snippetBudget?: number;
    topNWithSnippet?: number;
}
export interface RetrieveStdioOptions extends RetrieveSnippetOptions {
    maxOutputTokens?: number;
}
export interface RetrieveMatchedNode {
    node_id?: string;
    label: string;
    source_file: string;
    line_number: number;
    node_kind?: string;
    framework?: string | undefined;
    framework_role?: string | undefined;
    framework_boost?: number;
    source_domain?: SourceDomain;
    file_type: string;
    snippet: string | null;
    snippet_line_number?: number;
    snippet_scope?: 'symbol' | 'source_file';
    snippet_truncated?: boolean;
    match_score: number;
    relevance_band: 'direct' | 'related' | 'peripheral';
    community: number | null;
    community_label: string | null;
    evidence_class?: ContextPackEvidenceClass;
    representation_type?: ContextRepresentationType;
    representation_reason?: string;
}
export interface RetrieveRelationship {
    from_id?: string;
    from: string;
    to_id?: string;
    to: string;
    relation: string;
}
export interface RetrieveCommunityContext {
    id: number;
    label: string;
    node_count: number;
}
export interface RetrieveResult {
    question: string;
    token_count: number;
    matched_nodes: RetrieveMatchedNode[];
    relationships: RetrieveRelationship[];
    community_context: RetrieveCommunityContext[];
    graph_signals: {
        god_nodes: string[];
        bridge_nodes: string[];
    };
    task_contract?: ContextPackTaskContract;
    claims?: ContextPackClaim[];
    expandable?: ContextPackExpandableRef[];
    coverage?: ContextPackCoverage;
    selection_diagnostics?: ContextPackSelectionDiagnostics;
    retrieval_gate?: RetrievalGateDecision;
    retrieval_strategy?: ContextPackRetrievalStrategy;
    retrieval_plan?: ContextPackRetrievalPlanDetail;
    recovery?: ContextPackRecoveryPlan;
    snippet_budget_tokens_used?: number;
    snippet_budget_tokens_remaining?: number;
    slice?: ContextPackSliceMetadata;
    execution_slice?: ContextPackExecutionSlice;
    answer_contract?: ContextPackRuntimeGenerationAnswerContract;
}
export interface CompactRetrieveMatchedNode extends Omit<RetrieveMatchedNode, 'community_label' | 'file_type' | 'framework_boost' | 'snippet_truncated'> {
    file_type?: string;
    snippet_truncated: boolean;
}
export interface CompactRetrieveResult extends Omit<RetrieveResult, 'matched_nodes' | 'snippet_budget_tokens_used' | 'snippet_budget_tokens_remaining'> {
    matched_nodes: CompactRetrieveMatchedNode[];
    shared_file_type?: string;
    snippet_budget_tokens_used: number;
    snippet_budget_tokens_remaining: number;
}
export interface StdioRetrieveResult extends CompactRetrieveResult {
    claims?: ContextPackClaim[];
    expandable?: ContextPackExpandableRef[];
    coverage?: ContextPackCoverage;
}
export declare function scoreNode(questionTokens: readonly string[], labelTokens: readonly string[], tokenWeights?: ReadonlyMap<string, number>, averageFieldLength?: number): number;
export declare function tokenWeightsForQuestion(graph: KnowledgeGraph, questionTokens: readonly string[]): Map<string, number>;
export declare function estimateRetrieveEntryTokens(label: string, sourceFile: string, lineNumber: number, snippet: string | null): number;
export declare function withRetrieveSnippetBudget(result: RetrieveResult, options?: RetrieveSnippetOptions): RetrieveResult;
export declare function readSnippet(sourceFile: string, lineNumber: number, options?: {
    derived?: boolean;
    fileCache?: Map<string, string[] | null>;
}): string | null;
export interface QueryEvidenceSnippet {
    snippet: string;
    lineNumber: number;
    scope: 'symbol' | 'source_file';
}
interface QueryEvidenceSnippetOptions {
    question: string;
    label: string;
    sourceLocation?: string | null;
    fileNodeLike?: boolean;
    derived?: boolean;
    fileCache?: Map<string, string[] | null>;
}
/**
 * Selects compact, query-bearing evidence from a symbol range. When a small
 * helper is the only graph anchor for an anonymous workflow, it may select a
 * better excerpt from the same source file and marks that scope explicitly.
 */
export declare function readQueryEvidenceSnippet(sourceFile: string, lineNumber: number, options: QueryEvidenceSnippetOptions): QueryEvidenceSnippet | null;
export declare function collectRelationships(graph: KnowledgeGraph, includedIds: ReadonlySet<string>): RetrieveRelationship[];
export declare function reciprocalRankFuse(rankings: ReadonlyArray<readonly string[]>, options?: {
    rankConstant?: number;
    weights?: readonly number[];
}): Map<string, number>;
/**
 * Build the full CompiledContextPack representation of a RetrieveResult.
 * Exported in v0.15 so the context-pack diagnostics scorer (#78) can
 * compute structural quality signals against the same shape the compact
 * stdio response is derived from.
 */
export declare function contextPackFromRetrieveResult(result: RetrieveResult): CompiledContextPack<ContextPackNode, RetrieveRelationship, RetrieveCommunityContext>;
export declare function retrieveContext(graph: KnowledgeGraph, options: RetrieveOptions): RetrieveResult;
export declare function retrieveContextAsync(graph: KnowledgeGraph, options: RetrieveOptions): Promise<RetrieveResult>;
export declare function compactRetrieveResult(result: RetrieveResult, options?: RetrieveSnippetOptions): CompactRetrieveResult;
export declare function compactRetrieveResultForStdio(result: RetrieveResult, options?: RetrieveStdioOptions): StdioRetrieveResult;