@rce-mcp/retrieval-core 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,13 +1,16 @@
 import { createHash, randomUUID } from "node:crypto";
-import { buildQueryCacheKey } from "@rce-mcp/data-plane";
+import { buildQueryCacheKey, tokenizeForRanking } from "@rce-mcp/data-plane";
 import { InMemoryQueryCache } from "@rce-mcp/data-plane";
 import { getObservability } from "@rce-mcp/observability";
 import { buildChunksForFile, getChunkingParserAvailabilitySnapshot } from "./chunking.js";
 const MAX_FILE_SIZE_BYTES = 1_000_000;
 const MAX_CHUNKS_PER_FILE = 300;
-const TARGET_CHUNK_TOKENS = 220;
-const CHUNK_OVERLAP_TOKENS = 40;
+const DEFAULT_TARGET_CHUNK_TOKENS = 420;
+const DEFAULT_CHUNK_OVERLAP_TOKENS = 90;
 const MAX_TOP_K = 20;
+const DEFAULT_INTERNAL_CANDIDATE_DEPTH = 100;
+const MIN_INTERNAL_CANDIDATE_DEPTH = 20;
+const MAX_INTERNAL_CANDIDATE_DEPTH = 200;
 const MAX_CONTEXT_BUDGET_TOKENS = 12_000;
 export const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_BASE_URL = "https://router.tumuer.me/v1";
 export const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-4B";
@@ -15,6 +18,17 @@ export const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_DIMENSIONS = 2560;
 export const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_TIMEOUT_MS = 10_000;
 export const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_BATCH_SIZE = 64;
 export const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_MAX_RETRIES = 2;
+export const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_TRANSIENT_403_MAX_RETRIES = 4;
+export const DEFAULT_OPENAI_COMPATIBLE_RERANKER_BASE_URL = "https://router.tumuer.me/v1";
+export const DEFAULT_OPENAI_COMPATIBLE_RERANKER_MODEL = "Qwen/Qwen3-Reranker-4B";
+export const DEFAULT_OPENAI_COMPATIBLE_RERANKER_TIMEOUT_MS = 2_500;
+export const DEFAULT_SEARCH_RERANKER_TOP_N = 30;
+export const DEFAULT_PROVIDER_MAX_REQUESTS_PER_MINUTE = 90;
+export const DEFAULT_PROVIDER_LIMIT_INDEX_MAX_WAIT_MS = 120_000;
+export const DEFAULT_PROVIDER_LIMIT_QUERY_MAX_WAIT_MS = 1_000;
+export const DEFAULT_PROVIDER_LIMIT_RERANK_MAX_WAIT_MS = 500;
+export const DEFAULT_CLAUDE_ENHANCER_MODEL = "claude-3-5-sonnet-latest";
+const DEFAULT_CLAUDE_ENHANCER_MAX_TURNS = 3;
 const DEFAULT_CANDIDATE_SCORE_WEIGHTS = {
     lexical_weight: 0.6,
     vector_weight: 0.4,
@@ -52,6 +66,10 @@ export const BASELINE_RETRIEVAL_SCORING_CONFIG = {
         negation_avoid_tests_penalty: 0.35,
         negation_avoid_examples_penalty: 0.3,
         negation_avoid_archive_penalty: 0.35,
+        security_trace_meta_penalty: 0.22,
+        literal_path_boost: 0.3,
+        literal_snippet_boost: 0.18,
+        literal_max_boost: 0.5,
         min_total_bias: -0.45,
         max_total_bias: 0.35
     },
@@ -60,7 +78,16 @@ export const BASELINE_RETRIEVAL_SCORING_CONFIG = {
         max_chunks_per_path_default: 2,
         max_chunks_per_path_file_lookup: 1,
         same_directory_penalty: 0,
-        same_extension_penalty: 0
+        same_extension_penalty: 0,
+        merge_overlapping_chunks_enabled: true,
+        merge_gap_lines: 6,
+        merge_max_span_lines: 220,
+        smart_cutoff_enabled: false,
+        smart_cutoff_min_k: 2,
+        smart_cutoff_max_k: 8,
+        smart_cutoff_min_score: 0.25,
+        smart_cutoff_top_ratio: 0.5,
+        smart_cutoff_delta_abs: 0.25
     }
 };
 export const CONSERVATIVE_RETRIEVAL_SCORING_CONFIG = {
@@ -99,6 +126,10 @@ export const CONSERVATIVE_RETRIEVAL_SCORING_CONFIG = {
         negation_avoid_tests_penalty: 0.2,
         negation_avoid_examples_penalty: 0.16,
         negation_avoid_archive_penalty: 0.2,
+        security_trace_meta_penalty: 0.14,
+        literal_path_boost: 0.18,
+        literal_snippet_boost: 0.1,
+        literal_max_boost: 0.28,
         min_total_bias: -0.25,
         max_total_bias: 0.2
     },
@@ -107,7 +138,16 @@ export const CONSERVATIVE_RETRIEVAL_SCORING_CONFIG = {
         max_chunks_per_path_default: 2,
         max_chunks_per_path_file_lookup: 1,
         same_directory_penalty: 0,
-        same_extension_penalty: 0
+        same_extension_penalty: 0,
+        merge_overlapping_chunks_enabled: true,
+        merge_gap_lines: 6,
+        merge_max_span_lines: 220,
+        smart_cutoff_enabled: false,
+        smart_cutoff_min_k: 2,
+        smart_cutoff_max_k: 8,
+        smart_cutoff_min_score: 0.25,
+        smart_cutoff_top_ratio: 0.5,
+        smart_cutoff_delta_abs: 0.25
     }
 };
 export const DEFAULT_RETRIEVAL_ENHANCER_CONFIG = {
@@ -115,11 +155,42 @@ export const DEFAULT_RETRIEVAL_ENHANCER_CONFIG = {
     max_candidates_pre_rerank: 4,
     rerank_timeout_ms: 40
 };
+export const DEFAULT_RETRIEVAL_ENHANCER_GENERATION_CONFIG = {
+    timeout_ms: 18_000,
+    max_retries: 1,
+    tool_mode: "read_only",
+    max_context_snippets: 6
+};
 export const DEFAULT_RETRIEVAL_CHUNKING_CONFIG = {
     strategy: "sliding",
     fallback_strategy: "sliding",
+    target_chunk_tokens: DEFAULT_TARGET_CHUNK_TOKENS,
+    chunk_overlap_tokens: DEFAULT_CHUNK_OVERLAP_TOKENS,
+    budget_tokenizer: "ranking",
+    boundary_strictness: "legacy",
     parse_timeout_ms: 80,
-    enabled_languages: ["typescript", "javascript", "python", "go"]
+    enabled_languages: ["typescript", "javascript", "python", "go"],
+    recursive_semantic_chunking_enabled: false,
+    semantic_merge_gap_lines: 6,
+    semantic_merge_max_span_lines: 220,
+    comment_forward_absorb_enabled: true,
+    embedding_context_prefix_enabled: true
+};
+export const DEFAULT_RETRIEVAL_CONTEXT_PACKING_CONFIG = {
+    enabled: false,
+    max_spans_per_result: 3,
+    max_gap_lines: 120,
+    max_snippet_chars: 3_200,
+    enhancer_snippet_char_limit: 2_200
+};
+export const DEFAULT_RETRIEVAL_SNIPPET_INTEGRITY_CONFIG = {
+    enabled: false,
+    target_languages: ["typescript", "tsx", "javascript", "jsx"],
+    max_contiguous_gap_lines: 6,
+    marker_template_version: "v1",
+    repair_enabled: false,
+    repair_max_envelope_lines: 260,
+    repair_max_snippet_chars: 3_600
 };
 const BUILTIN_RETRIEVAL_SCORING_PROFILES = {
     baseline: BASELINE_RETRIEVAL_SCORING_CONFIG,
@@ -172,6 +243,36 @@ function validateScoringConfig(config) {
     if (rerank.same_extension_penalty < 0) {
         throw new Error("invalid retrieval scoring config: rerank.same_extension_penalty must be >= 0");
     }
+    if (typeof rerank.merge_overlapping_chunks_enabled !== "boolean") {
+        throw new Error("invalid retrieval scoring config: rerank.merge_overlapping_chunks_enabled must be boolean");
+    }
+    if (!Number.isInteger(rerank.merge_gap_lines) || rerank.merge_gap_lines < 0) {
+        throw new Error("invalid retrieval scoring config: rerank.merge_gap_lines must be an integer >= 0");
+    }
+    if (!Number.isInteger(rerank.merge_max_span_lines) || rerank.merge_max_span_lines <= 0) {
+        throw new Error("invalid retrieval scoring config: rerank.merge_max_span_lines must be a positive integer");
+    }
+    if (typeof rerank.smart_cutoff_enabled !== "boolean") {
+        throw new Error("invalid retrieval scoring config: rerank.smart_cutoff_enabled must be boolean");
+    }
+    if (!Number.isInteger(rerank.smart_cutoff_min_k) || rerank.smart_cutoff_min_k <= 0) {
+        throw new Error("invalid retrieval scoring config: rerank.smart_cutoff_min_k must be a positive integer");
+    }
+    if (!Number.isInteger(rerank.smart_cutoff_max_k) || rerank.smart_cutoff_max_k <= 0) {
+        throw new Error("invalid retrieval scoring config: rerank.smart_cutoff_max_k must be a positive integer");
+    }
+    if (rerank.smart_cutoff_max_k < rerank.smart_cutoff_min_k) {
+        throw new Error("invalid retrieval scoring config: rerank.smart_cutoff_max_k must be >= smart_cutoff_min_k");
+    }
+    assertFiniteNumber(rerank.smart_cutoff_min_score, "rerank.smart_cutoff_min_score");
+    assertFiniteNumber(rerank.smart_cutoff_top_ratio, "rerank.smart_cutoff_top_ratio");
+    assertFiniteNumber(rerank.smart_cutoff_delta_abs, "rerank.smart_cutoff_delta_abs");
+    if (rerank.smart_cutoff_top_ratio <= 0 || rerank.smart_cutoff_top_ratio > 1) {
+        throw new Error("invalid retrieval scoring config: rerank.smart_cutoff_top_ratio must be in (0, 1]");
+    }
+    if (rerank.smart_cutoff_delta_abs < 0) {
+        throw new Error("invalid retrieval scoring config: rerank.smart_cutoff_delta_abs must be >= 0");
+    }
 }
 export function resolveRetrievalScoringProfile(profile_id) {
     const normalized = (profile_id ?? "baseline").trim().toLowerCase();
@@ -225,6 +326,28 @@ export function mergeRetrievalEnhancerConfig(base, overrides) {
     validateEnhancerConfig(next);
     return next;
 }
+function validateEnhancerGenerationConfig(config) {
+    if (!Number.isInteger(config.timeout_ms) || config.timeout_ms <= 0) {
+        throw new Error("invalid retrieval enhancer generation config: timeout_ms must be a positive integer");
+    }
+    if (!Number.isInteger(config.max_retries) || config.max_retries < 0) {
+        throw new Error("invalid retrieval enhancer generation config: max_retries must be a non-negative integer");
+    }
+    if (config.tool_mode !== "none" && config.tool_mode !== "read_only") {
+        throw new Error("invalid retrieval enhancer generation config: tool_mode must be none|read_only");
+    }
+    if (!Number.isInteger(config.max_context_snippets) || config.max_context_snippets <= 0) {
+        throw new Error("invalid retrieval enhancer generation config: max_context_snippets must be a positive integer");
+    }
+}
+export function mergeRetrievalEnhancerGenerationConfig(base, overrides) {
+    const next = {
+        ...base,
+        ...(overrides ?? {})
+    };
+    validateEnhancerGenerationConfig(next);
+    return next;
+}
 function normalizeChunkingLanguageList(value) {
     const deduped = new Set();
     for (const language of value) {
@@ -243,9 +366,24 @@ function validateChunkingConfig(config) {
     if (config.fallback_strategy !== "sliding") {
         throw new Error("invalid retrieval chunking config: fallback_strategy must be sliding");
     }
+    if (!Number.isInteger(config.target_chunk_tokens) || config.target_chunk_tokens <= 0) {
+        throw new Error("invalid retrieval chunking config: target_chunk_tokens must be a positive integer");
+    }
+    if (!Number.isInteger(config.chunk_overlap_tokens) || config.chunk_overlap_tokens <= 0) {
+        throw new Error("invalid retrieval chunking config: chunk_overlap_tokens must be a positive integer");
+    }
+    if (config.chunk_overlap_tokens >= config.target_chunk_tokens) {
+        throw new Error("invalid retrieval chunking config: chunk_overlap_tokens must be less than target_chunk_tokens");
+    }
     if (!Number.isInteger(config.parse_timeout_ms) || config.parse_timeout_ms <= 0) {
         throw new Error("invalid retrieval chunking config: parse_timeout_ms must be a positive integer");
     }
+    if (config.budget_tokenizer !== "ranking" && config.budget_tokenizer !== "lightweight") {
+        throw new Error("invalid retrieval chunking config: budget_tokenizer must be ranking|lightweight");
+    }
+    if (config.boundary_strictness !== "legacy" && config.boundary_strictness !== "semantic_js_ts") {
+        throw new Error("invalid retrieval chunking config: boundary_strictness must be legacy|semantic_js_ts");
+    }
     if (!Array.isArray(config.enabled_languages) || config.enabled_languages.length === 0) {
         throw new Error("invalid retrieval chunking config: enabled_languages must include at least one language");
     }
@@ -254,6 +392,21 @@ function validateChunkingConfig(config) {
             throw new Error("invalid retrieval chunking config: enabled_languages must contain non-empty strings");
         }
     }
+    if (typeof config.recursive_semantic_chunking_enabled !== "boolean") {
+        throw new Error("invalid retrieval chunking config: recursive_semantic_chunking_enabled must be boolean");
+    }
+    if (!Number.isInteger(config.semantic_merge_gap_lines) || config.semantic_merge_gap_lines < 0) {
+        throw new Error("invalid retrieval chunking config: semantic_merge_gap_lines must be a non-negative integer");
+    }
+    if (!Number.isInteger(config.semantic_merge_max_span_lines) || config.semantic_merge_max_span_lines <= 0) {
+        throw new Error("invalid retrieval chunking config: semantic_merge_max_span_lines must be a positive integer");
+    }
+    if (typeof config.comment_forward_absorb_enabled !== "boolean") {
+        throw new Error("invalid retrieval chunking config: comment_forward_absorb_enabled must be boolean");
+    }
+    if (typeof config.embedding_context_prefix_enabled !== "boolean") {
+        throw new Error("invalid retrieval chunking config: embedding_context_prefix_enabled must be boolean");
+    }
 }
 export function mergeRetrievalChunkingConfig(base, overrides) {
     const next = {
@@ -264,6 +417,98 @@ export function mergeRetrievalChunkingConfig(base, overrides) {
     validateChunkingConfig(next);
     return next;
 }
+function validateContextPackingConfig(config) {
+    if (typeof config.enabled !== "boolean") {
+        throw new Error("invalid retrieval context packing config: enabled must be boolean");
+    }
+    if (!Number.isInteger(config.max_spans_per_result) || config.max_spans_per_result <= 0) {
+        throw new Error("invalid retrieval context packing config: max_spans_per_result must be a positive integer");
+    }
+    if (!Number.isInteger(config.max_gap_lines) || config.max_gap_lines < 0) {
+        throw new Error("invalid retrieval context packing config: max_gap_lines must be a non-negative integer");
+    }
+    if (!Number.isInteger(config.max_snippet_chars) || config.max_snippet_chars <= 0) {
+        throw new Error("invalid retrieval context packing config: max_snippet_chars must be a positive integer");
+    }
+    if (!Number.isInteger(config.enhancer_snippet_char_limit) || config.enhancer_snippet_char_limit <= 0) {
+        throw new Error("invalid retrieval context packing config: enhancer_snippet_char_limit must be a positive integer");
+    }
+}
+export function mergeRetrievalContextPackingConfig(base, overrides) {
+    const next = {
+        ...base,
+        ...(overrides ?? {})
+    };
+    validateContextPackingConfig(next);
+    return next;
+}
+function normalizeSnippetIntegrityLanguage(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "typescript" || normalized === "ts" || normalized === "mts" || normalized === "cts") {
+        return "typescript";
+    }
+    if (normalized === "tsx") {
+        return "tsx";
+    }
+    if (normalized === "javascript" || normalized === "js" || normalized === "mjs" || normalized === "cjs") {
+        return "javascript";
+    }
+    if (normalized === "jsx") {
+        return "jsx";
+    }
+    return undefined;
+}
+function normalizeSnippetIntegrityLanguageList(value) {
+    const deduped = new Set();
+    for (const language of value) {
+        const raw = language.trim().toLowerCase();
+        if (raw.length === 0) {
+            continue;
+        }
+        deduped.add(normalizeSnippetIntegrityLanguage(raw) ?? raw);
+    }
+    return [...deduped];
+}
+function validateSnippetIntegrityConfig(config) {
+    if (typeof config.enabled !== "boolean") {
+        throw new Error("invalid retrieval snippet integrity config: enabled must be boolean");
+    }
+    if (!Array.isArray(config.target_languages) || config.target_languages.length === 0) {
+        throw new Error("invalid retrieval snippet integrity config: target_languages must include at least one language");
+    }
+    for (const language of config.target_languages) {
+        if (typeof language !== "string" || language.trim().length === 0) {
+            throw new Error("invalid retrieval snippet integrity config: target_languages must contain non-empty strings");
+        }
+        if (!normalizeSnippetIntegrityLanguage(language)) {
+            throw new Error("invalid retrieval snippet integrity config: unsupported target language");
+        }
+    }
+    if (!Number.isInteger(config.max_contiguous_gap_lines) || config.max_contiguous_gap_lines < 0) {
+        throw new Error("invalid retrieval snippet integrity config: max_contiguous_gap_lines must be a non-negative integer");
+    }
+    if (config.marker_template_version !== "v1") {
+        throw new Error("invalid retrieval snippet integrity config: marker_template_version must be v1");
+    }
+    if (typeof config.repair_enabled !== "boolean") {
+        throw new Error("invalid retrieval snippet integrity config: repair_enabled must be boolean");
+    }
+    if (!Number.isInteger(config.repair_max_envelope_lines) || config.repair_max_envelope_lines <= 0) {
+        throw new Error("invalid retrieval snippet integrity config: repair_max_envelope_lines must be a positive integer");
+    }
+    if (!Number.isInteger(config.repair_max_snippet_chars) || config.repair_max_snippet_chars <= 0) {
+        throw new Error("invalid retrieval snippet integrity config: repair_max_snippet_chars must be a positive integer");
+    }
+}
+export function mergeRetrievalSnippetIntegrityConfig(base, overrides) {
+    const next = {
+        ...base,
+        ...(overrides ?? {}),
+        target_languages: normalizeSnippetIntegrityLanguageList(overrides?.target_languages ?? base.target_languages)
+    };
+    validateSnippetIntegrityConfig(next);
+    return next;
+}
 function stableSerialize(value) {
     if (Array.isArray(value)) {
         return `[${value.map((entry) => stableSerialize(entry)).join(",")}]`;
@@ -277,10 +522,14 @@ function stableSerialize(value) {
 function scoringConfigChecksum(config) {
     return sha256(stableSerialize(config)).slice(0, 12);
 }
+function clampInternalCandidateDepth(value) {
+    const raw = Number.isFinite(value) ? Math.trunc(value ?? DEFAULT_INTERNAL_CANDIDATE_DEPTH) : DEFAULT_INTERNAL_CANDIDATE_DEPTH;
+    return Math.max(MIN_INTERNAL_CANDIDATE_DEPTH, Math.min(MAX_INTERNAL_CANDIDATE_DEPTH, raw));
+}
 const REASON_STRINGS = [
     "semantic match",
-    "exact symbol match",
-    "path and token overlap",
+    "exact literal match",
+    "path token overlap",
     "recently modified relevant module"
 ];
 export class RetrievalError extends Error {
@@ -293,10 +542,26 @@ export class RetrievalError extends Error {
 class EmbeddingProviderRequestError extends Error {
     reason;
     retryable;
-    constructor(reason, retryable, message) {
+    retry_after_ms;
+    constructor(reason, retryable, message, retry_after_ms) {
         super(message);
         this.reason = reason;
         this.retryable = retryable;
+        this.retry_after_ms = retry_after_ms;
+    }
+}
+class RerankerProviderRequestError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+class EnhancerProviderRequestError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
     }
 }
 const SECRET_PATTERNS = [
@@ -341,42 +606,21 @@ function singularizeToken(token) {
     }
     return undefined;
 }
-function tokenize(text) {
-    const coarseTokens = text
-        .split(/[^a-z0-9_./-]+/)
-        .map((token) => token.trim())
+function tokenizeLightweight(text) {
+    return text
+        .normalize("NFKC")
+        .split(/[^A-Za-z0-9_]+/)
+        .map((token) => token.trim().toLowerCase())
         .filter(Boolean);
-    const expandedTokens = new Set();
-    const addToken = (value) => {
-        const normalized = value.trim().toLowerCase();
-        if (!normalized) {
-            return;
-        }
-        expandedTokens.add(normalized);
-        const singular = singularizeToken(normalized);
-        if (singular) {
-            expandedTokens.add(singular);
-        }
-        const plural = pluralizeToken(normalized);
-        if (plural) {
-            expandedTokens.add(plural);
-        }
-    };
-    for (const token of coarseTokens) {
-        addToken(token);
-        for (const part of token.split(/[./_-]+/).filter(Boolean)) {
-            addToken(part);
-            const camelSplit = part
-                .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-                .split(/\s+/)
-                .map((segment) => segment.trim().toLowerCase())
-                .filter(Boolean);
-            for (const segment of camelSplit) {
-                addToken(segment);
-            }
-        }
+}
+function tokenize(text) {
+    return tokenizeForRanking(text);
+}
+function chunkBudgetTokenize(text, mode) {
+    if (mode === "lightweight") {
+        return tokenizeLightweight(text);
     }
-    return [...expandedTokens];
+    return tokenize(text);
 }
 function lexicalScore(query, haystack) {
     const q = new Set(tokenize(query));
@@ -419,17 +663,101 @@ function looksLowInformation(snippet) {
     return /^(.)\1+$/.test(noWhitespace);
 }
 function chooseReason(input) {
+    if (input.literal_match) {
+        return "exact literal match";
+    }
     if (input.path_match) {
-        return "exact symbol match";
+        return "path token overlap";
     }
     if (input.recency_boosted) {
         return "recently modified relevant module";
     }
     if (input.lexical > 0.3) {
-        return "path and token overlap";
+        return "path token overlap";
     }
     return "semantic match";
 }
+function isExactLiteralReason(reason) {
+    return reason === "exact literal match" || reason === "exact symbol match";
+}
+function extractSearchLiterals(query) {
+    const literals = [];
+    const seen = new Set();
+    const addLiteral = (raw) => {
+        const cleaned = raw.trim().replace(/^[`"'([{]+|[`"')\]}:;,.]+$/g, "");
+        const normalized = cleaned.toLowerCase();
+        if (!normalized || seen.has(normalized)) {
+            return;
+        }
+        if (normalized.length < 3) {
+            return;
+        }
+        const looksEnvLiteral = /^[A-Z0-9]+(?:_[A-Z0-9]+){2,}$/.test(cleaned);
+        const looksPathOrFileLiteral = /[/.]/.test(cleaned);
+        const looksCamelLiteral = /[a-z][A-Z]/.test(cleaned) || /[A-Z][a-z]+[A-Z]/.test(cleaned);
+        const looksHyphenLiteral = cleaned.includes("-");
+        const isSpecificLiteral = looksEnvLiteral || looksPathOrFileLiteral || looksCamelLiteral || looksHyphenLiteral;
+        if (!isSpecificLiteral) {
+            return;
+        }
+        seen.add(normalized);
+        literals.push(normalized);
+    };
+    for (const symbol of extractLikelyCodeSymbols(query, 24)) {
+        addLiteral(symbol);
+    }
+    for (const pathSymbol of extractPathLikeSymbols(query)) {
+        addLiteral(pathSymbol);
+        const leaf = normalizePath(pathSymbol).split("/").pop();
+        if (leaf) {
+            addLiteral(leaf);
+        }
+    }
+    for (const envMatch of query.matchAll(/\bRCE_[A-Z0-9_]{4,}\b/g)) {
+        addLiteral(envMatch[0] ?? "");
+    }
+    for (const fileName of query.matchAll(/\b[A-Za-z0-9_.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|json|md)\b/g)) {
+        addLiteral(fileName[0] ?? "");
+    }
+    return literals.slice(0, 24);
+}
+function applyLiteralBoost(input) {
+    if (input.literals.length === 0) {
+        return {
+            boost: 0,
+            matched: false,
+            path_matches: 0,
+            snippet_matches: 0
+        };
+    }
+    const normalizedPath = input.path.toLowerCase();
+    const normalizedSnippet = input.snippet.toLowerCase();
+    const pathBias = input.path_bias;
+    let boost = 0;
+    let pathMatches = 0;
+    let snippetMatches = 0;
+    for (const literal of input.literals) {
+        if (normalizedPath.includes(literal)) {
+            boost += pathBias.literal_path_boost;
+            pathMatches += 1;
+            continue;
+        }
+        if (normalizedSnippet.includes(literal)) {
+            boost += pathBias.literal_snippet_boost;
+            snippetMatches += 1;
+        }
+        if (boost >= pathBias.literal_max_boost) {
+            break;
+        }
+    }
+    const clampedBoost = Math.min(pathBias.literal_max_boost, boost);
+    return {
+        boost: clampedBoost,
+        matched: clampedBoost > 0,
+        path_matches: pathMatches,
+        snippet_matches: snippetMatches
+    };
+}
 const DOC_INTENT_TOKENS = new Set([
     "adr",
     "architecture",
@@ -483,6 +811,22 @@ const UI_COMPONENT_TOKENS = new Set(["component", "layout", "react", "tsx", "ui"
 const FILE_LOOKUP_TOKENS = new Set(["entrypoint", "file", "locate", "path", "where", "which"]);
 const TEST_INTENT_TOKENS = new Set(["assert", "coverage", "e2e", "integration", "spec", "test", "tests", "unit"]);
 const EXAMPLE_INTENT_TOKENS = new Set(["demo", "example", "examples", "sample", "tutorial"]);
+const SECURITY_TRACE_INTENT_TOKENS = new Set([
+    "auth",
+    "authorization",
+    "binding",
+    "config",
+    "enforce",
+    "mcp",
+    "project_root_path",
+    "security",
+    "session",
+    "stdio",
+    "tenant",
+    "token",
+    "workspace",
+    "workspace_id"
+]);
 const SOURCE_PATH_PREFIXES = ["src/", "app/", "apps/", "crates/", "internal/", "lib/", "package/", "packages/"];
 const LOW_PRIORITY_PATH_PREFIXES = [
     ".next/",
@@ -543,6 +887,20 @@ function hasTestIntent(tokens) {
 function hasExampleIntent(tokens) {
     return tokens.some((token) => EXAMPLE_INTENT_TOKENS.has(token));
 }
+function hasSecurityTraceIntent(tokens, queryText) {
+    if (tokens.some((token) => SECURITY_TRACE_INTENT_TOKENS.has(token))) {
+        return true;
+    }
+    return /\btenant_id\b|\bworkspace_id\b|\bproject_root_path\b|\bRCE_[A-Z0-9_]{4,}\b/.test(queryText);
+}
+function isGuidanceOrMetaPath(path) {
+    const normalized = path.toLowerCase();
+    return (normalized.endsWith("mcp-tool-guidance.ts") ||
+        normalized.includes("/guidance/") ||
+        normalized.includes("/meta/") ||
+        normalized.includes("/_meta/") ||
+        normalized.includes("tool-guidance"));
+}
 function pathQualityBias(path, queryTokens, config, queryText) {
     const normalizedPath = path.toLowerCase();
     const docIntent = hasDocIntent(queryTokens);
@@ -553,6 +911,7 @@ function pathQualityBias(path, queryTokens, config, queryText) {
     const uiComponentIntent = hasUiComponentIntent(queryTokens);
     const testIntent = hasTestIntent(queryTokens);
     const exampleIntent = hasExampleIntent(queryTokens);
+    const securityTraceIntent = hasSecurityTraceIntent(queryTokens, queryText ?? queryTokens.join(" "));
     let bias = 0;
     const pathBias = config.path_bias;
     const isSourcePath = SOURCE_PATH_PREFIXES.some((prefix) => normalizedPath.startsWith(prefix) || normalizedPath.includes(`/${prefix}`));
@@ -616,6 +975,9 @@ function pathQualityBias(path, queryTokens, config, queryText) {
     if (docsPreferred && isSourcePath) {
         bias -= pathBias.doc_intent_source_penalty;
     }
+    if (securityTraceIntent && !docsPreferred && isGuidanceOrMetaPath(normalizedPath)) {
+        bias -= pathBias.security_trace_meta_penalty;
+    }
     if (workspaceManifestIntent && normalizedPath === "cargo.toml") {
         bias += pathBias.workspace_manifest_root_boost;
     }
@@ -681,13 +1043,19 @@ function buildChunks(file, chunkingConfig) {
         config: {
             strategy: chunkingConfig.strategy,
             fallback_strategy: chunkingConfig.fallback_strategy,
-            target_chunk_tokens: TARGET_CHUNK_TOKENS,
-            chunk_overlap_tokens: CHUNK_OVERLAP_TOKENS,
+            target_chunk_tokens: chunkingConfig.target_chunk_tokens,
+            chunk_overlap_tokens: chunkingConfig.chunk_overlap_tokens,
+            budget_tokenizer: chunkingConfig.budget_tokenizer,
+            boundary_strictness: chunkingConfig.boundary_strictness,
             max_chunks_per_file: MAX_CHUNKS_PER_FILE,
             parse_timeout_ms: chunkingConfig.parse_timeout_ms,
-            enabled_languages: chunkingConfig.enabled_languages
+            enabled_languages: chunkingConfig.enabled_languages,
+            recursive_semantic_chunking_enabled: chunkingConfig.recursive_semantic_chunking_enabled,
+            semantic_merge_gap_lines: chunkingConfig.semantic_merge_gap_lines,
+            semantic_merge_max_span_lines: chunkingConfig.semantic_merge_max_span_lines,
+            comment_forward_absorb_enabled: chunkingConfig.comment_forward_absorb_enabled
         },
-        tokenize
+        tokenize: (text) => chunkBudgetTokenize(text, chunkingConfig.budget_tokenizer)
     });
     return {
         chunks: chunkingResult.chunks.map((chunk) => ({
@@ -705,9 +1073,27 @@ function buildChunks(file, chunkingConfig) {
         parse_latency_ms: chunkingResult.parse_latency_ms,
         language_aware_attempt_latency_ms: chunkingResult.language_aware_attempt_latency_ms,
         fallback_path_latency_ms: chunkingResult.fallback_path_latency_ms,
-        language: chunkingResult.language
+        language: chunkingResult.language,
+        recursive_semantic_chunking_used: chunkingResult.recursive_semantic_chunking_used
     };
 }
+function buildChunkEmbeddingText(chunk, config, embeddingProviderId) {
+    const isDeterministicProvider = embeddingProviderId.trim().toLowerCase() === "deterministic";
+    if (!config.embedding_context_prefix_enabled || isDeterministicProvider) {
+        return chunk.snippet;
+    }
+    const normalizedPath = normalizePath(chunk.path);
+    const pathParts = normalizedPath.split("/").filter(Boolean);
+    const contextPath = pathParts.length > 2 ? pathParts.slice(-2).join("/") : normalizedPath;
+    const symbol = detectSnippetSymbolName(chunk.snippet);
+    const linesLabel = `${chunk.start_line}-${chunk.end_line}`;
+    const symbolLabel = symbol ? ` > ${symbol}` : "";
+    const prefix = `${contextPath}:${linesLabel}${symbolLabel}`;
+    return `${prefix}\n${chunk.snippet}`;
+}
+function buildChunkEmbeddingTexts(chunks, config, embeddingProviderId) {
+    return chunks.map((chunk) => buildChunkEmbeddingText(chunk, config, embeddingProviderId));
+}
 function pseudoEmbedding(input, dimensions = 24) {
     const safeDimensions = Math.max(1, dimensions);
     let source = sha256(input);
@@ -732,6 +1118,138 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+export class ProviderRateLimitExceededError extends Error {
+    retry_after_ms;
+    constructor(message, retry_after_ms) {
+        super(message);
+        this.retry_after_ms = retry_after_ms;
+    }
+}
+export class LocalProviderRequestLimiter {
+    mode = "local";
+    buckets = new Map();
+    now;
+    sleeper;
+    constructor(options) {
+        this.now = options?.now ?? (() => Date.now());
+        this.sleeper = options?.sleeper ?? sleep;
+    }
+    async acquire(input) {
+        if (!Number.isInteger(input.max_requests_per_minute) || input.max_requests_per_minute <= 0) {
+            throw new Error("provider limiter requires max_requests_per_minute to be a positive integer");
+        }
+        if (!Number.isInteger(input.max_wait_ms) || input.max_wait_ms < 0) {
+            throw new Error("provider limiter requires max_wait_ms to be a non-negative integer");
+        }
+        const refillPerMs = input.max_requests_per_minute / 60_000;
+        let waitedMs = 0;
+        const deadline = this.now() + input.max_wait_ms;
+        while (true) {
+            const nowMs = this.now();
+            let bucket = this.buckets.get(input.scope);
+            if (!bucket) {
+                bucket = {
+                    tokens: input.max_requests_per_minute,
+                    last_refill_ms: nowMs
+                };
+                this.buckets.set(input.scope, bucket);
+            }
+            if (nowMs > bucket.last_refill_ms) {
+                const elapsedMs = nowMs - bucket.last_refill_ms;
+                bucket.tokens = Math.min(input.max_requests_per_minute, bucket.tokens + elapsedMs * refillPerMs);
+                bucket.last_refill_ms = nowMs;
+            }
+            if (bucket.tokens >= 1) {
+                bucket.tokens -= 1;
+                return { wait_ms: waitedMs };
+            }
+            const retryAfterMs = Math.max(1, Math.ceil((1 - bucket.tokens) / refillPerMs));
+            const remainingMs = deadline - nowMs;
+            if (remainingMs <= 0 || retryAfterMs > remainingMs) {
+                throw new ProviderRateLimitExceededError(`provider request rate limit exceeded for scope "${input.scope}"`, Math.max(1, retryAfterMs));
+            }
+            const sleepMs = Math.max(1, Math.min(retryAfterMs, remainingMs));
+            await this.sleeper(sleepMs);
+            waitedMs += sleepMs;
+        }
+    }
+}
+const REDIS_PROVIDER_LIMITER_SCRIPT = `
+local key = KEYS[1]
+local limit = tonumber(ARGV[1])
+local window_ms = tonumber(ARGV[2])
+local count = redis.call("INCR", key)
+if count == 1 then
+  redis.call("PEXPIRE", key, window_ms)
+end
+if count <= limit then
+  return {1, 0}
+end
+local ttl = redis.call("PTTL", key)
+if ttl < 0 then
+  ttl = window_ms
+end
+return {0, ttl}
+`;
+export class RedisProviderRequestLimiter {
+    mode = "redis";
+    redis;
+    keyPrefix;
+    windowMs;
+    now;
+    sleeper;
+    constructor(options) {
+        if (!options.redis || typeof options.redis.eval !== "function") {
+            throw new Error("invalid redis provider limiter config: redis client with eval() is required");
+        }
+        this.redis = options.redis;
+        this.keyPrefix = options.key_prefix?.trim() || "rce:provider_rate_limit";
+        this.windowMs = options.window_ms ?? 60_000;
+        this.now = options.now ?? (() => Date.now());
+        this.sleeper = options.sleeper ?? sleep;
+        if (!Number.isInteger(this.windowMs) || this.windowMs <= 0) {
+            throw new Error("invalid redis provider limiter config: window_ms must be a positive integer");
+        }
+    }
+    async acquire(input) {
+        if (!Number.isInteger(input.max_requests_per_minute) || input.max_requests_per_minute <= 0) {
+            throw new Error("provider limiter requires max_requests_per_minute to be a positive integer");
+        }
+        if (!Number.isInteger(input.max_wait_ms) || input.max_wait_ms < 0) {
+            throw new Error("provider limiter requires max_wait_ms to be a non-negative integer");
+        }
+        let waitedMs = 0;
+        const deadline = this.now() + input.max_wait_ms;
+        while (true) {
+            const attempt = await this.reserveAttempt(input.scope, input.max_requests_per_minute);
+            if (attempt.allowed) {
+                return { wait_ms: waitedMs };
+            }
+            const nowMs = this.now();
+            const remainingMs = deadline - nowMs;
+            const retryAfterMs = Math.max(1, attempt.retry_after_ms);
+            if (remainingMs <= 0 || retryAfterMs > remainingMs) {
+                throw new ProviderRateLimitExceededError(`provider request rate limit exceeded for scope "${input.scope}"`, retryAfterMs);
+            }
+            const sleepMs = Math.max(1, Math.min(retryAfterMs, remainingMs));
+            await this.sleeper(sleepMs);
+            waitedMs += sleepMs;
+        }
+    }
+    async reserveAttempt(scope, maxRequestsPerMinute) {
+        const key = `${this.keyPrefix}:${scope}`;
+        const raw = await this.redis.eval(REDIS_PROVIDER_LIMITER_SCRIPT, 1, key, maxRequestsPerMinute, this.windowMs);
+        if (Array.isArray(raw)) {
+            const allowed = Number(raw[0] ?? 0) === 1;
+            const retryAfterMs = Number(raw[1] ?? 0);
+            return {
+                allowed,
+                retry_after_ms: Number.isFinite(retryAfterMs) ? Math.max(0, Math.trunc(retryAfterMs)) : this.windowMs
+            };
+        }
+        throw new Error("redis provider limiter returned unexpected eval() payload");
+    }
+}
 export class DeterministicEmbeddingProvider {
     dimensions;
     model;
@@ -762,6 +1280,12 @@ export class OpenAICompatibleEmbeddingProvider {
     timeoutMs;
     batchSize;
     maxRetries;
+    transientForbiddenMaxRetries;
+    requestLimiter;
+    requestLimitScope;
+    maxRequestsPerMinute;
+    indexMaxWaitMs;
+    queryMaxWaitMs;
     observability;
     constructor(options) {
         const baseUrl = options.base_url.trim().replace(/\/+$/, "");
@@ -780,6 +1304,17 @@ export class OpenAICompatibleEmbeddingProvider {
         this.timeoutMs = options.timeout_ms ?? DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_TIMEOUT_MS;
         this.batchSize = options.batch_size ?? DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_BATCH_SIZE;
         this.maxRetries = options.max_retries ?? DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_MAX_RETRIES;
+        this.transientForbiddenMaxRetries =
+            options.transient_forbidden_max_retries ?? DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_TRANSIENT_403_MAX_RETRIES;
+        this.requestLimiter = options.request_limiter;
+        this.requestLimitScope = resolveProviderLimiterScope({
+            provider: "openai_compatible",
+            apiKey,
+            overrideScopeId: options.request_limit_scope_id
+        });
+        this.maxRequestsPerMinute = options.max_requests_per_minute ?? DEFAULT_PROVIDER_MAX_REQUESTS_PER_MINUTE;
+        this.indexMaxWaitMs = options.index_max_wait_ms ?? DEFAULT_PROVIDER_LIMIT_INDEX_MAX_WAIT_MS;
+        this.queryMaxWaitMs = options.query_max_wait_ms ?? DEFAULT_PROVIDER_LIMIT_QUERY_MAX_WAIT_MS;
         this.observability = options.observability ?? getObservability("retrieval-core");
         if (!Number.isInteger(this.dimensions) || this.dimensions <= 0) {
             throw new Error("invalid openai-compatible embedding config: dimensions must be a positive integer");
@@ -793,6 +1328,18 @@ export class OpenAICompatibleEmbeddingProvider {
         if (!Number.isInteger(this.maxRetries) || this.maxRetries < 0) {
             throw new Error("invalid openai-compatible embedding config: max_retries must be a non-negative integer");
         }
+        if (!Number.isInteger(this.transientForbiddenMaxRetries) || this.transientForbiddenMaxRetries < 0) {
+            throw new Error("invalid openai-compatible embedding config: transient_forbidden_max_retries must be a non-negative integer");
+        }
+        if (!Number.isInteger(this.maxRequestsPerMinute) || this.maxRequestsPerMinute <= 0) {
+            throw new Error("invalid openai-compatible embedding config: max_requests_per_minute must be a positive integer");
+        }
+        if (!Number.isInteger(this.indexMaxWaitMs) || this.indexMaxWaitMs < 0) {
+            throw new Error("invalid openai-compatible embedding config: index_max_wait_ms must be a non-negative integer");
+        }
+        if (!Number.isInteger(this.queryMaxWaitMs) || this.queryMaxWaitMs < 0) {
+            throw new Error("invalid openai-compatible embedding config: query_max_wait_ms must be a non-negative integer");
+        }
     }
     describe() {
         return {
@@ -819,11 +1366,12 @@ export class OpenAICompatibleEmbeddingProvider {
             model: this.model,
             purpose
         };
-        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+        let attempt = 0;
+        while (true) {
             const startedAt = Date.now();
             this.observability.metrics.increment("retrieval_embedding_provider_requests_total", 1, labels);
             try {
-                return await this.embedBatchOnce(texts);
+                return await this.embedBatchOnce(texts, purpose);
             }
             catch (error) {
                 const failure = this.toProviderFailure(error);
@@ -831,30 +1379,69 @@ export class OpenAICompatibleEmbeddingProvider {
                     ...labels,
                     reason: failure.reason
                 });
-                const shouldRetry = failure.retryable && attempt < this.maxRetries;
+                const maxRetriesForFailure = this.maxRetriesForReason(failure.reason);
+                const shouldRetry = failure.retryable && attempt < maxRetriesForFailure;
                 this.observability.logger.warn("embedding provider request failed", {
                     provider: "openai_compatible",
                     model: this.model,
                     purpose,
                     reason: failure.reason,
+                    provider_message: failure.message,
                     retryable: failure.retryable,
                     retrying: shouldRetry,
                     attempt: attempt + 1,
-                    max_attempts: this.maxRetries + 1
+                    max_attempts: maxRetriesForFailure + 1,
+                    retry_after_ms: failure.retry_after_ms
                 });
                 if (shouldRetry) {
-                    await sleep(this.retryDelayMs(attempt));
+                    await sleep(this.retryDelayMs(attempt, failure));
+                    attempt += 1;
                     continue;
                 }
+                if (failure.reason === "client_rate_limited" || failure.reason === "rate_limited") {
+                    throw new RetrievalError("RATE_LIMITED", `embedding provider rate limited; ${failure.message}`);
+                }
                 throw new RetrievalError("UPSTREAM_FAILURE", `embedding provider request failed (${failure.reason}); ${failure.message}`);
             }
             finally {
                 this.observability.metrics.observe("retrieval_embedding_provider_latency_ms", Date.now() - startedAt, labels);
             }
         }
-        throw new RetrievalError("UPSTREAM_FAILURE", "embedding provider retries exhausted");
     }
-    async embedBatchOnce(texts) {
+    async enforceRequestLimit(purpose) {
+        if (!this.requestLimiter) {
+            return;
+        }
+        const maxWaitMs = purpose === "index" ? this.indexMaxWaitMs : this.queryMaxWaitMs;
+        const labels = {
+            provider: "openai_compatible",
+            model: this.model,
+            purpose,
+            limiter_mode: this.requestLimiter.mode ?? "custom"
+        };
+        try {
+            const acquired = await this.requestLimiter.acquire({
+                scope: this.requestLimitScope,
+                max_requests_per_minute: this.maxRequestsPerMinute,
+                max_wait_ms: maxWaitMs
+            });
+            this.observability.metrics.observe("retrieval_provider_limiter_wait_ms", acquired.wait_ms, labels);
+            this.observability.metrics.increment("retrieval_provider_requests_shaped_total", 1, labels);
+        }
+        catch (error) {
+            this.observability.metrics.increment("retrieval_provider_limiter_block_total", 1, {
+                ...labels,
+                reason: "wait_timeout"
+            });
+            if (error instanceof ProviderRateLimitExceededError) {
+                const retryable = purpose === "index";
+                throw new EmbeddingProviderRequestError("client_rate_limited", retryable, `${error.message}; retry_after_ms=${error.retry_after_ms}`, error.retry_after_ms);
+            }
+            throw error;
+        }
+    }
+    async embedBatchOnce(texts, purpose) {
+        await this.enforceRequestLimit(purpose);
         const controller = new AbortController();
         const timeoutId = setTimeout(() => {
             controller.abort();
@@ -887,13 +1474,18 @@ export class OpenAICompatibleEmbeddingProvider {
         if (!response.ok) {
             const details = await safeResponseText(response);
             if (response.status === 429) {
-                throw new EmbeddingProviderRequestError("rate_limited", true, `HTTP 429 ${details}`.trim());
+                throw new EmbeddingProviderRequestError("rate_limited", true, `HTTP 429 ${details}`.trim(), parseRetryAfterMs(response.headers.get("retry-after")));
             }
             if (response.status >= 500) {
                 throw new EmbeddingProviderRequestError("http_5xx", true, `HTTP ${response.status} ${details}`.trim());
             }
-            if (response.status === 401 || response.status === 403) {
-                throw new EmbeddingProviderRequestError("auth_error", false, `HTTP ${response.status} ${details}`.trim());
+            if (response.status === 401) {
+                throw new EmbeddingProviderRequestError("auth_error", false, `HTTP 401 ${details}`.trim());
+            }
+            if (response.status === 403) {
+                const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+                const retryable = this.isTransientForbidden(details, retryAfterMs);
+                throw new EmbeddingProviderRequestError(retryable ? "forbidden_transient" : "auth_error", retryable, `HTTP 403 ${details}`.trim(), retryAfterMs);
             }
             if (response.status === 404) {
                 throw new EmbeddingProviderRequestError("endpoint_not_found", false, `HTTP 404 ${details}`.trim());
@@ -945,16 +1537,81 @@ export class OpenAICompatibleEmbeddingProvider {
         }
         return vectors;
     }
-    retryDelayMs(attempt) {
-        const base = 100 * (attempt + 1);
-        const jitter = Math.floor(Math.random() * 75);
-        return base + jitter;
+    maxRetriesForReason(reason) {
+        if (reason === "forbidden_transient") {
+            return Math.max(this.maxRetries, this.transientForbiddenMaxRetries);
+        }
+        return this.maxRetries;
+    }
+    retryDelayMs(attempt, failure) {
+        const baseBackoffMs = failure.reason === "forbidden_transient"
+            ? Math.min(2_500, 250 * 2 ** attempt)
+            : 100 * (attempt + 1);
+        const jitterMs = failure.reason === "forbidden_transient" ? Math.floor(Math.random() * 150) : Math.floor(Math.random() * 75);
+        const computedDelayMs = baseBackoffMs + jitterMs;
+        if (failure.retry_after_ms === undefined) {
+            return computedDelayMs;
+        }
+        return Math.max(computedDelayMs, Math.max(1, failure.retry_after_ms));
+    }
+    isTransientForbidden(details, retryAfterMs) {
+        if (retryAfterMs !== undefined) {
+            return true;
+        }
+        const normalized = details.trim().toLowerCase();
+        if (normalized.length === 0) {
+            return false;
+        }
+        const transientSignals = [
+            "rate limit",
+            "too many requests",
+            "temporar",
+            "try again",
+            "upstream",
+            "timeout",
+            "busy",
+            "capacity",
+            "bad_response_status_code"
+        ];
+        if (transientSignals.some((signal) => normalized.includes(signal))) {
+            return true;
+        }
+        const hardFailureSignals = [
+            "invalid api key",
+            "incorrect api key",
+            "authentication",
+            "unauthorized",
+            "insufficient permissions",
+            "insufficient scope",
+            "permission denied",
+            "organization not found",
+            "account disabled",
+            "insufficient quota",
+            "quota exceeded",
+            "billing",
+            "credit",
+            "payment required",
+            "model not found",
+            "unknown model",
+            "unsupported model",
+            "not allowed"
+        ];
+        if (hardFailureSignals.some((signal) => normalized.includes(signal))) {
+            return false;
+        }
+        return false;
     }
     toProviderFailure(error) {
         if (error instanceof EmbeddingProviderRequestError) {
             return error;
         }
+        if (error instanceof ProviderRateLimitExceededError) {
+            return new EmbeddingProviderRequestError("client_rate_limited", false, `${error.message}; retry_after_ms=${error.retry_after_ms}`);
+        }
         if (error instanceof RetrievalError) {
+            if (error.code === "RATE_LIMITED") {
+                return new EmbeddingProviderRequestError("client_rate_limited", false, error.message);
+            }
             return new EmbeddingProviderRequestError("upstream_failure", false, error.message);
         }
         if (error instanceof Error) {
@@ -963,45 +1620,910 @@ export class OpenAICompatibleEmbeddingProvider {
         return new EmbeddingProviderRequestError("unknown_error", false, String(error));
     }
 }
-async function safeResponseText(response) {
-    try {
-        const text = await response.text();
-        return text.slice(0, 512);
-    }
-    catch {
-        return "";
+export class OpenAICompatibleRerankerProvider {
+    endpoint;
+    apiKey;
+    model;
+    timeoutMs;
+    requestLimiter;
+    requestLimitScope;
+    maxRequestsPerMinute;
+    rerankMaxWaitMs;
+    observability;
+    constructor(options) {
+        const baseUrl = options.base_url.trim().replace(/\/+$/, "");
+        if (baseUrl.length === 0) {
+            throw new Error("invalid openai-compatible reranker config: base_url must be non-empty");
+        }
+        const apiKey = options.api_key.trim();
+        if (apiKey.length === 0) {
+            throw new Error("invalid openai-compatible reranker config: api_key must be non-empty");
+        }
+        this.endpoint = `${baseUrl}/rerank`;
+        this.apiKey = apiKey;
+        this.model = options.model?.trim() || DEFAULT_OPENAI_COMPATIBLE_RERANKER_MODEL;
+        this.timeoutMs = options.timeout_ms ?? DEFAULT_OPENAI_COMPATIBLE_RERANKER_TIMEOUT_MS;
+        this.requestLimiter = options.request_limiter;
+        this.requestLimitScope = resolveProviderLimiterScope({
+            provider: "openai_compatible",
+            apiKey,
+            overrideScopeId: options.request_limit_scope_id
+        });
+        this.maxRequestsPerMinute = options.max_requests_per_minute ?? DEFAULT_PROVIDER_MAX_REQUESTS_PER_MINUTE;
+        this.rerankMaxWaitMs = options.rerank_max_wait_ms ?? DEFAULT_PROVIDER_LIMIT_RERANK_MAX_WAIT_MS;
+        this.observability = options.observability ?? getObservability("retrieval-core");
+        if (!Number.isInteger(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new Error("invalid openai-compatible reranker config: timeout_ms must be a positive integer");
+        }
+        if (!Number.isInteger(this.maxRequestsPerMinute) || this.maxRequestsPerMinute <= 0) {
+            throw new Error("invalid openai-compatible reranker config: max_requests_per_minute must be a positive integer");
+        }
+        if (!Number.isInteger(this.rerankMaxWaitMs) || this.rerankMaxWaitMs < 0) {
+            throw new Error("invalid openai-compatible reranker config: rerank_max_wait_ms must be a non-negative integer");
+        }
     }
-}
-function resolveEmbeddingDescriptor(provider) {
-    const described = provider.describe?.();
-    if (!described) {
+    describe() {
         return {
-            provider: "custom",
-            dimensions: 24
+            provider: "openai_compatible",
+            model: this.model
         };
     }
-    return {
-        provider: described.provider,
-        ...(described.model ? { model: described.model } : {}),
-        dimensions: described.dimensions,
-        ...(described.version ? { version: described.version } : {})
-    };
-}
-function normalizeEmbeddingDescriptor(descriptor) {
-    const provider = descriptor.provider.trim();
-    if (provider.length === 0) {
-        throw new Error("invalid embedding descriptor: provider must be non-empty");
-    }
-    if (!Number.isInteger(descriptor.dimensions) || descriptor.dimensions <= 0) {
-        throw new Error("invalid embedding descriptor: dimensions must be a positive integer");
-    }
-    return {
-        provider: provider.toLowerCase(),
-        ...(descriptor.model ? { model: descriptor.model.trim() } : {}),
+    async rerank(input) {
+        if (input.documents.length === 0) {
+            return [];
+        }
+        await this.enforceRequestLimit();
+        const topN = Math.max(1, Math.min(input.top_n, input.documents.length));
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            controller.abort();
+        }, this.timeoutMs);
+        let response;
+        try {
+            response = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${this.apiKey}`,
+                    "content-type": "application/json"
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    query: input.query,
+                    documents: input.documents,
+                    top_n: topN
+                }),
+                signal: controller.signal
+            });
+        }
+        catch (error) {
+            if (error && typeof error === "object" && "name" in error && error.name === "AbortError") {
+                throw new RerankerProviderRequestError("timeout", `request timed out after ${this.timeoutMs}ms`);
+            }
+            throw new RerankerProviderRequestError("network_error", error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const details = await safeResponseText(response);
+            if (response.status === 429) {
+                throw new RerankerProviderRequestError("rate_limited", `HTTP 429 ${details}`.trim());
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new RerankerProviderRequestError("auth_error", `HTTP ${response.status} ${details}`.trim());
+            }
+            if (response.status === 404) {
+                throw new RerankerProviderRequestError("endpoint_not_found", `HTTP 404 ${details}`.trim());
+            }
+            if (response.status >= 500) {
+                throw new RerankerProviderRequestError("http_5xx", `HTTP ${response.status} ${details}`.trim());
+            }
+            throw new RerankerProviderRequestError("http_4xx", `HTTP ${response.status} ${details}`.trim());
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            throw new RerankerProviderRequestError("invalid_json", "provider returned non-JSON response");
+        }
+        if (!payload || typeof payload !== "object") {
+            throw new RerankerProviderRequestError("invalid_response", "provider response must be an object");
+        }
+        const maybeResults = "results" in payload ? payload.results : payload.data;
+        if (!Array.isArray(maybeResults)) {
+            throw new RerankerProviderRequestError("invalid_response", "provider response missing results array");
+        }
+        const output = [];
+        for (const row of maybeResults) {
+            if (!row || typeof row !== "object") {
+                throw new RerankerProviderRequestError("invalid_response", "rerank row must be an object");
+            }
+            const rawIndex = row.index;
+            if (!Number.isInteger(rawIndex)) {
+                throw new RerankerProviderRequestError("invalid_response", "rerank row index must be an integer");
+            }
+            const index = rawIndex;
+            if (index < 0 || index >= input.documents.length) {
+                throw new RerankerProviderRequestError("invalid_response", "rerank row index out of range");
+            }
+            const rawScore = row.relevance_score ?? row.score;
+            if (typeof rawScore !== "number" || !Number.isFinite(rawScore)) {
+                throw new RerankerProviderRequestError("invalid_response", "rerank row score must be finite");
+            }
+            output.push({
+                index,
+                relevance_score: rawScore
+            });
+        }
+        const seen = new Set();
+        const ordered = [...output]
+            .sort((a, b) => b.relevance_score - a.relevance_score || a.index - b.index)
+            .filter((row) => {
+            if (seen.has(row.index)) {
+                return false;
+            }
+            seen.add(row.index);
+            return true;
+        })
+            .slice(0, topN);
+        if (ordered.length === 0) {
+            throw new RerankerProviderRequestError("invalid_response", "provider returned zero rerank results");
+        }
+        return ordered;
+    }
+    async enforceRequestLimit() {
+        if (!this.requestLimiter) {
+            return;
+        }
+        const labels = {
+            provider: "openai_compatible",
+            model: this.model,
+            purpose: "rerank",
+            limiter_mode: this.requestLimiter.mode ?? "custom"
+        };
+        try {
+            const acquired = await this.requestLimiter.acquire({
+                scope: this.requestLimitScope,
+                max_requests_per_minute: this.maxRequestsPerMinute,
+                max_wait_ms: this.rerankMaxWaitMs
+            });
+            this.observability.metrics.observe("retrieval_provider_limiter_wait_ms", acquired.wait_ms, labels);
+            this.observability.metrics.increment("retrieval_provider_requests_shaped_total", 1, labels);
+        }
+        catch (error) {
+            this.observability.metrics.increment("retrieval_provider_limiter_block_total", 1, {
+                ...labels,
+                reason: "wait_timeout"
+            });
+            if (error instanceof ProviderRateLimitExceededError) {
+                throw new RerankerProviderRequestError("rate_limited", `${error.message}; retry_after_ms=${error.retry_after_ms}`);
+            }
+            throw error;
+        }
+    }
+}
+function buildClaudeEnhancerSystemInstruction(language, style) {
+    const languageRule = language === "zh"
+        ? "Output language must be Simplified Chinese."
+        : language === "es"
+            ? "Output language must be Spanish."
+            : "Output language must be English.";
+    const styleRule = style === "lean"
+        ? "Style is lean: keep the response compact (roughly 90-180 words), avoid extra headings, and include only essential steps."
+        : style === "deep"
+            ? "Style is deep: provide comprehensive but grounded guidance (roughly 260-420 words) with concrete constraints, edge cases, and validation."
+            : "Style is standard: provide balanced depth (roughly 160-300 words) with clear scope, steps, and validation.";
+    return [
+        "You are a high-precision prompt enhancement agent for software engineering tasks.",
+        languageRule,
+        styleRule,
+        "Return plain text only: the final enhanced prompt.",
+        "Do not include markdown code fences.",
+        "Preserve user intent exactly; do not add unrelated features.",
+        "Do not invent file paths or symbols that are not present in provided context.",
+        "Produce concise execution-ready prompts, not long generic templates.",
+        "Prefer practical sections only: objective, scoped constraints, codebase anchors, implementation steps, validation.",
+        "Use concrete file/symbol anchors when context exists.",
+        "Avoid repeating generic process advice, broad deliverables lists, or organizational boilerplate."
+    ].join(" ");
+}
+function normalizeEnhancerContextPath(path) {
+    return normalizePath(path).toLowerCase();
+}
+function looksLikeEnhancerConventionsFile(path) {
+    const normalized = normalizeEnhancerContextPath(path);
+    return (normalized === "agents.md" ||
+        normalized.endsWith("/agents.md") ||
+        normalized === "claude.md" ||
+        normalized.endsWith("/claude.md") ||
+        normalized === "readme.md" ||
+        normalized.endsWith("/readme.md") ||
+        normalized === "contributing.md" ||
+        normalized.endsWith("/contributing.md"));
+}
+function extractProjectConventionsFromEnhancerContext(snippets) {
+    const candidateSnippets = snippets.filter((snippet) => looksLikeEnhancerConventionsFile(snippet.path));
+    if (candidateSnippets.length === 0) {
+        return [];
+    }
+    const signalPattern = /\b(always|never|must|should|avoid|prefer|preserve|keep|strict|isolation|tenant|workspace|contract|schema|backward|compatibility|regression|test|typecheck|bun)\b/i;
+    const out = [];
+    const seen = new Set();
+    for (const snippet of candidateSnippets) {
+        const lines = snippet.snippet.split(/\r?\n/u);
+        for (const rawLine of lines) {
+            const cleaned = rawLine
+                .replace(/^\s*[-*+]\s+/u, "")
+                .replace(/^\s*\d+\.\s+/u, "")
+                .trim();
+            if (cleaned.length < 16 || cleaned.length > 180) {
+                continue;
+            }
+            if (!signalPattern.test(cleaned)) {
+                continue;
+            }
+            if (/^(import|export|const|let|var|if|for|while|return)\b/i.test(cleaned)) {
+                continue;
+            }
+            const normalized = cleaned.toLowerCase();
+            if (seen.has(normalized)) {
+                continue;
+            }
+            seen.add(normalized);
+            out.push(cleaned);
+            if (out.length >= 8) {
+                return out;
+            }
+        }
+    }
+    return out;
+}
+function extractEnhancerNonNegotiables(input) {
+    const combined = `${input.prompt}\n${input.history.map((entry) => entry.content).join("\n")}`;
+    const lower = combined.toLowerCase();
+    const out = [];
+    const add = (value) => {
+        if (!out.includes(value)) {
+            out.push(value);
+        }
+    };
+    if (/keep (?:behavior|behaviour) stable|preserve (?:existing )?(?:behavior|behaviour)|backward.?compat|no breaking changes|without breaking/i.test(lower)) {
+        add("Preserve existing behavior and avoid breaking API/contract semantics.");
+    }
+    if (/regression tests?|add tests?|test coverage|boundary tests?/i.test(lower)) {
+        add("Include regression tests for any changed behavior.");
+    }
+    if (/tenant|workspace|authorization|auth boundaries?|scope enforcement|isolation/i.test(lower)) {
+        add("Maintain strict tenant/workspace isolation and authorization boundaries.");
+    }
+    if (/no docs|avoid docs|exclude docs/i.test(lower)) {
+        add("Do not prioritize documentation-only changes unless explicitly requested.");
+    }
+    if (/no refactor|minimal changes?|smallest safe change/i.test(lower)) {
+        add("Prefer the smallest safe change set.");
+    }
+    return out.slice(0, 6);
+}
+function buildEnhancerOutputContract(input) {
+    const isConceptual = input.query_intent === "conceptual";
+    if (input.style === "lean") {
+        if (input.intent === "tests") {
+            return {
+                target_style: "lean_test_plan",
+                max_words: input.has_context ? 220 : 170,
+                preferred_sections: ["Goal", "Key test cases", "Validation"],
+                avoid_patterns: ["long checklists", "broad architecture proposals", "generic deliverables blocks"]
+            };
+        }
+        if (input.intent === "docs" || isConceptual) {
+            return {
+                target_style: "lean_spec",
+                max_words: input.has_context ? 220 : 170,
+                preferred_sections: ["Goal", "Scope", "Validation"],
+                avoid_patterns: ["verbose outlines", "boilerplate context blocks", "generic process advice"]
+            };
+        }
+        return {
+            target_style: "lean_implementation_plan",
+            max_words: input.has_context ? 230 : 180,
+            preferred_sections: ["Goal", "Constraints", "Action steps", "Validation"],
+            avoid_patterns: ["deep background sections", "broad deliverables lists", "repeated boilerplate"]
+        };
+    }
+    if (input.style === "deep") {
+        if (input.intent === "tests") {
+            return {
+                target_style: "deep_test_plan",
+                max_words: input.has_context ? 420 : 340,
+                preferred_sections: ["Goal", "Behavior under test", "Test matrix", "Edge cases", "Validation"],
+                avoid_patterns: ["vague test advice", "non-test deliverables", "ungrounded file guesses"]
+            };
+        }
+        if (input.intent === "docs" || isConceptual) {
+            return {
+                target_style: "deep_spec",
+                max_words: input.has_context ? 420 : 340,
+                preferred_sections: ["Goal", "Scope", "Relevant sources", "Proposed outline", "Risks", "Validation"],
+                avoid_patterns: ["implementation-only checklists", "generic organizational boilerplate", "speculation"]
+            };
+        }
+        return {
+            target_style: "deep_implementation_plan",
+            max_words: input.has_context ? 420 : 360,
+            preferred_sections: [
+                "Goal",
+                "Scope and constraints",
+                "Codebase anchors",
+                "Implementation plan",
+                "Edge cases",
+                "Validation"
+            ],
+            avoid_patterns: ["security theater", "repeated compliance boilerplate", "invented file/symbol references"]
+        };
+    }
+    if (input.intent === "docs" || isConceptual) {
+        return {
+            target_style: "concise_spec",
+            max_words: input.has_context ? 320 : 260,
+            preferred_sections: ["Goal", "Scope", "Relevant sources", "Proposed outline", "Validation"],
+            avoid_patterns: ["long implementation checklists", "generic deliverables sections", "repeated boilerplate"]
+        };
+    }
+    if (input.intent === "tests") {
+        return {
+            target_style: "test_plan",
+            max_words: input.has_context ? 320 : 260,
+            preferred_sections: ["Goal", "Behavior under test", "Test matrix", "Implementation notes", "Validation"],
+            avoid_patterns: ["broad architecture rewrites", "non-test deliverables", "generic process bullets"]
+        };
+    }
+    return {
+        target_style: "implementation_plan",
+        max_words: input.has_context ? 360 : 300,
+        preferred_sections: ["Goal", "Scope and constraints", "Codebase anchors", "Implementation plan", "Validation"],
+        avoid_patterns: ["broad security theater", "repeated compliance boilerplate", "vague deliverables lists"]
+    };
+}
+function buildClaudeEnhancerUserPayload(input) {
+    const projectConventions = extractProjectConventionsFromEnhancerContext(input.context_snippets);
+    const outputContract = buildEnhancerOutputContract({
+        style: input.style_resolved,
+        intent: input.intent,
+        query_intent: input.query_intent,
+        has_context: input.context_refs.length > 0
+    });
+    const nonNegotiables = extractEnhancerNonNegotiables({
+        prompt: input.request.prompt,
+        history: input.request.conversation_history
+    });
+    const payload = {
+        trace_id: input.trace_id,
+        tenant_id: input.tenant_id,
+        workspace_id: input.workspace_id ?? "none",
+        tool_mode: input.tool_mode,
+        style_requested: input.style_requested,
+        style_resolved: input.style_resolved,
+        intent: input.intent,
+        query_intent: input.query_intent,
+        language: input.language,
+        original_prompt: input.request.prompt,
+        conversation_history: input.request.conversation_history,
+        context_refs: input.context_refs,
+        context_snippets: input.context_snippets.map((snippet) => ({
+            path: snippet.path,
+            start_line: snippet.start_line,
+            end_line: snippet.end_line,
+            reason: snippet.reason,
+            score: Number(snippet.score.toFixed(4)),
+            snippet: snippet.snippet
+        })),
+        output_contract: outputContract,
+        non_negotiables: nonNegotiables,
+        project_conventions: projectConventions
+    };
+    return [
+        "Enhance the following request into a concise, implementation-ready prompt.",
+        "Prioritize user intent fidelity, concrete repo anchors, and verifiable validation steps.",
+        "Honor the requested enhancement style while avoiding invented details.",
+        "Input JSON:",
+        JSON.stringify(payload, null, 2)
+    ].join("\n");
+}
+function removeEnhancerCodeFences(text) {
+    return text.trim().replace(/^```(?:json|markdown|md)?\s*/iu, "").replace(/\s*```$/u, "").trim();
+}
+function normalizeProviderEnhancedPrompt(text) {
+    let normalized = removeEnhancerCodeFences(text).replace(/\r\n/g, "\n");
+    normalized = normalized
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/u, ""))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    if (!normalized) {
+        return normalized;
+    }
+    try {
+        const payload = JSON.parse(normalized);
+        if (payload && typeof payload === "object" && typeof payload.enhanced_prompt === "string") {
+            return payload.enhanced_prompt.trim();
+        }
+    }
+    catch {
+        return normalized;
+    }
+    return normalized;
+}
+let cachedClaudeAgentSdkQueryFn;
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+async function loadClaudeAgentSdkQueryFn() {
+    if (cachedClaudeAgentSdkQueryFn) {
+        return cachedClaudeAgentSdkQueryFn;
+    }
+    const moduleNames = ["@anthropic-ai/claude-agent-sdk", "@anthropic-ai/claude-code"];
+    let lastError;
+    for (const moduleName of moduleNames) {
+        try {
+            const sdkModule = (await import(moduleName));
+            if (typeof sdkModule.query === "function") {
+                cachedClaudeAgentSdkQueryFn = sdkModule.query;
+                return cachedClaudeAgentSdkQueryFn;
+            }
+            lastError = new Error(`${moduleName} does not export query()`);
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    const reason = lastError instanceof Error ? lastError.message : String(lastError ?? "unknown error");
+    throw new EnhancerProviderRequestError("upstream_error", `claude agent sdk is not available; install @anthropic-ai/claude-agent-sdk (${reason})`);
+}
+function extractTextFromClaudeMessageContent(content) {
+    if (typeof content === "string") {
+        const trimmed = content.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    if (!Array.isArray(content)) {
+        return undefined;
+    }
+    const parts = [];
+    for (const item of content) {
+        if (!isRecord(item)) {
+            continue;
+        }
+        const text = item.text;
+        if (typeof text !== "string") {
+            continue;
+        }
+        const trimmed = text.trim();
+        if (trimmed.length > 0) {
+            parts.push(trimmed);
+        }
+    }
+    if (parts.length === 0) {
+        return undefined;
+    }
+    return parts.join("\n");
+}
+function extractTextFromClaudeSdkMessage(message) {
+    if (!isRecord(message)) {
+        return undefined;
+    }
+    if (typeof message.summary === "string") {
+        const trimmed = message.summary.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    if (typeof message.result === "string") {
+        const trimmed = message.result.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    if (typeof message.text === "string") {
+        const trimmed = message.text.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    const directContent = extractTextFromClaudeMessageContent(message.content);
+    if (directContent) {
+        return directContent;
+    }
+    if (isRecord(message.message)) {
+        if (typeof message.message.text === "string") {
+            const trimmed = message.message.text.trim();
+            if (trimmed.length > 0) {
+                return trimmed;
+            }
+        }
+        const nestedContent = extractTextFromClaudeMessageContent(message.message.content);
+        if (nestedContent) {
+            return nestedContent;
+        }
+    }
+    return undefined;
+}
+function extractTextChunkFromClaudeSdkStreamEvent(message) {
+    if (!isRecord(message) || message.type !== "stream_event") {
+        return undefined;
+    }
+    const event = message.event;
+    if (!isRecord(event)) {
+        return undefined;
+    }
+    if (event.type === "content_block_start") {
+        const contentBlock = event.content_block;
+        if (isRecord(contentBlock) && typeof contentBlock.text === "string") {
+            return contentBlock.text;
+        }
+    }
+    if (event.type === "content_block_delta") {
+        const delta = event.delta;
+        if (!isRecord(delta)) {
+            return undefined;
+        }
+        if (typeof delta.text === "string") {
+            return delta.text;
+        }
+    }
+    return undefined;
+}
+function extractStructuredOutputFromClaudeSdkMessage(message) {
+    if (!isRecord(message)) {
+        return undefined;
+    }
+    const structuredOutput = message.structured_output;
+    if (!isRecord(structuredOutput)) {
+        return undefined;
+    }
+    const enhancedPrompt = structuredOutput.enhanced_prompt;
+    if (typeof enhancedPrompt !== "string" || enhancedPrompt.trim().length === 0) {
+        return undefined;
+    }
+    return {
+        enhanced_prompt: enhancedPrompt.trim()
+    };
+}
+function extractResultFailureFromClaudeSdkMessage(message) {
+    if (!isRecord(message) || message.type !== "result") {
+        return undefined;
+    }
+    const subtype = message.subtype;
+    if (typeof subtype !== "string" || subtype === "success") {
+        return undefined;
+    }
+    const rawErrors = Array.isArray(message.errors) ? message.errors : [];
+    const errors = rawErrors
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return {
+        subtype,
+        errors
+    };
+}
+function describeClaudeSdkMessage(message) {
+    if (!isRecord(message)) {
+        return typeof message;
+    }
+    const type = typeof message.type === "string" ? message.type : "unknown";
+    const subtype = typeof message.subtype === "string" ? message.subtype : undefined;
+    return subtype ? `${type}:${subtype}` : type;
+}
+function classifyEnhancerProviderError(error) {
+    if (error instanceof EnhancerProviderRequestError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        const message = error.message || "unknown enhancer provider error";
+        if (/(timeout|timed out|abort)/i.test(message)) {
+            return new EnhancerProviderRequestError("timeout", message);
+        }
+        if (/(rate.?limit|too many requests|429)/i.test(message)) {
+            return new EnhancerProviderRequestError("rate_limited", message);
+        }
+        if (/(no such file|not found|ENOENT)/i.test(message) && /claude/i.test(message)) {
+            return new EnhancerProviderRequestError("upstream_error", `claude code executable not found: ${message}`);
+        }
+        return new EnhancerProviderRequestError("upstream_error", message);
+    }
+    return new EnhancerProviderRequestError("upstream_error", String(error));
+}
+export class ClaudeAgentEnhancerProvider {
+    apiKey;
+    model;
+    maxTokens;
+    baseUrl;
+    pathToClaudeCodeExecutable;
+    permissionMode;
+    constructor(options) {
+        const apiKey = options.api_key.trim();
+        if (apiKey.length === 0) {
+            throw new Error("invalid claude enhancer config: api_key must be non-empty");
+        }
+        const model = options.model?.trim() ?? DEFAULT_CLAUDE_ENHANCER_MODEL;
+        if (model.length === 0) {
+            throw new Error("invalid claude enhancer config: model must be non-empty");
+        }
+        const maxTokens = options.max_tokens ?? 1_200;
+        if (!Number.isInteger(maxTokens) || maxTokens <= 0) {
+            throw new Error("invalid claude enhancer config: max_tokens must be a positive integer");
+        }
+        const permissionMode = options.permission_mode ?? "default";
+        if (permissionMode !== "default" &&
+            permissionMode !== "acceptEdits" &&
+            permissionMode !== "bypassPermissions" &&
+            permissionMode !== "plan") {
+            throw new Error("invalid claude enhancer config: permission_mode must be default|acceptEdits|bypassPermissions|plan");
+        }
+        this.apiKey = apiKey;
+        this.model = model;
+        this.maxTokens = maxTokens;
+        this.baseUrl = options.base_url?.trim();
+        const executablePath = options.path_to_claude_code_executable?.trim();
+        this.pathToClaudeCodeExecutable = executablePath && executablePath.length > 0 ? executablePath : undefined;
+        this.permissionMode = permissionMode;
+    }
+    describe() {
+        return {
+            provider: "claude_agent",
+            model: this.model
+        };
+    }
+    async generate(input) {
+        const query = await loadClaudeAgentSdkQueryFn();
+        const prompt = buildClaudeEnhancerUserPayload(input);
+        const abortController = new AbortController();
+        const upstreamAbortSignal = input.abort_signal;
+        const upstreamAbortHandler = () => {
+            abortController.abort();
+        };
+        if (upstreamAbortSignal) {
+            if (upstreamAbortSignal.aborted) {
+                abortController.abort();
+            }
+            else {
+                upstreamAbortSignal.addEventListener("abort", upstreamAbortHandler, { once: true });
+            }
+        }
+        const options = {
+            model: this.model,
+            maxThinkingTokens: this.maxTokens,
+            maxTurns: DEFAULT_CLAUDE_ENHANCER_MAX_TURNS,
+            includePartialMessages: true,
+            thinking: {
+                type: "disabled"
+            },
+            permissionMode: this.permissionMode,
+            systemPrompt: buildClaudeEnhancerSystemInstruction(input.language, input.style_resolved),
+            // Enhancer already receives scoped context snippets; keep Claude Code tools disabled to avoid long tool loops.
+            tools: [],
+            allowedTools: [],
+            env: {
+                ANTHROPIC_API_KEY: this.apiKey,
+                ...(this.baseUrl ? { ANTHROPIC_BASE_URL: this.baseUrl } : {})
+            },
+            abortController,
+            ...(this.pathToClaudeCodeExecutable ? { pathToClaudeCodeExecutable: this.pathToClaudeCodeExecutable } : {}),
+            ...(input.request.project_root_path ? { cwd: input.request.project_root_path } : {})
+        };
+        let structured;
+        let lastText;
+        const streamTextParts = [];
+        const seenMessageKinds = new Set();
+        let maxTurnsFailure;
+        try {
+            for await (const message of query({ prompt, options })) {
+                input.on_progress?.();
+                seenMessageKinds.add(describeClaudeSdkMessage(message));
+                const partialChunk = extractTextChunkFromClaudeSdkStreamEvent(message);
+                if (typeof partialChunk === "string" && partialChunk.length > 0) {
+                    streamTextParts.push(partialChunk);
+                }
+                const resultFailure = extractResultFailureFromClaudeSdkMessage(message);
+                if (resultFailure) {
+                    if (resultFailure.subtype === "error_max_turns") {
+                        maxTurnsFailure = resultFailure;
+                        continue;
+                    }
+                    const details = resultFailure.errors.length > 0 ? `: ${resultFailure.errors.join(" | ")}` : "";
+                    throw new EnhancerProviderRequestError("upstream_error", `claude agent sdk result error (${resultFailure.subtype})${details}`);
+                }
+                const maybeStructured = extractStructuredOutputFromClaudeSdkMessage(message);
+                if (maybeStructured) {
+                    structured = maybeStructured;
+                }
+                const maybeText = extractTextFromClaudeSdkMessage(message);
+                if (maybeText) {
+                    lastText = maybeText;
+                }
+                if (isRecord(message) && message.type === "assistant" && typeof message.error === "string") {
+                    throw new EnhancerProviderRequestError("upstream_error", `claude agent sdk assistant error: ${message.error}`);
+                }
+            }
+        }
+        catch (error) {
+            throw classifyEnhancerProviderError(error);
+        }
+        finally {
+            if (upstreamAbortSignal) {
+                upstreamAbortSignal.removeEventListener("abort", upstreamAbortHandler);
+            }
+        }
+        if (structured) {
+            return structured;
+        }
+        if (!lastText && streamTextParts.length > 0) {
+            lastText = streamTextParts.join("").trim();
+        }
+        if (maxTurnsFailure && !lastText) {
+            const details = maxTurnsFailure.errors.length > 0 ? `: ${maxTurnsFailure.errors.join(" | ")}` : "";
+            throw new EnhancerProviderRequestError("upstream_error", `claude agent sdk hit max turns before returning output${details}`);
+        }
+        if (!lastText) {
+            const seenKinds = [...seenMessageKinds].join(", ") || "none";
+            throw new EnhancerProviderRequestError("invalid_response", `claude agent sdk returned no text output (messages=${seenKinds})`);
+        }
+        return { enhanced_prompt: normalizeProviderEnhancedPrompt(lastText) };
+    }
+}
+async function safeResponseText(response) {
+    try {
+        const text = await response.text();
+        return text.slice(0, 512);
+    }
+    catch {
+        return "";
+    }
+}
+function parseRetryAfterMs(headerValue) {
+    if (!headerValue) {
+        return undefined;
+    }
+    const trimmed = headerValue.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.ceil(seconds * 1000);
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - Date.now());
+    }
+    return undefined;
+}
+function resolveProviderLimiterScope(input) {
+    const override = input.overrideScopeId?.trim();
+    if (override) {
+        return `provider:${input.provider}|credential:${override}`;
+    }
+    return `provider:${input.provider}|credential:${sha256(input.apiKey).slice(0, 16)}`;
+}
+function resolveEmbeddingDescriptor(provider) {
+    const described = provider.describe?.();
+    if (!described) {
+        return {
+            provider: "custom",
+            dimensions: 24
+        };
+    }
+    return {
+        provider: described.provider,
+        ...(described.model ? { model: described.model } : {}),
+        dimensions: described.dimensions,
+        ...(described.version ? { version: described.version } : {})
+    };
+}
+function resolveRerankerDescriptor(provider) {
+    const described = provider.describe?.();
+    if (!described) {
+        return {
+            provider: "custom"
+        };
+    }
+    return {
+        provider: described.provider,
+        ...(described.model ? { model: described.model } : {})
+    };
+}
+function resolveEnhancerProviderDescriptor(provider) {
+    const described = provider.describe?.();
+    if (!described) {
+        return {
+            provider: "custom"
+        };
+    }
+    return {
+        provider: described.provider,
+        ...(described.model ? { model: described.model } : {})
+    };
+}
+function normalizeEmbeddingDescriptor(descriptor) {
+    const provider = descriptor.provider.trim();
+    if (provider.length === 0) {
+        throw new Error("invalid embedding descriptor: provider must be non-empty");
+    }
+    if (!Number.isInteger(descriptor.dimensions) || descriptor.dimensions <= 0) {
+        throw new Error("invalid embedding descriptor: dimensions must be a positive integer");
+    }
+    return {
+        provider: provider.toLowerCase(),
+        ...(descriptor.model ? { model: descriptor.model.trim() } : {}),
         dimensions: descriptor.dimensions,
         ...(descriptor.version ? { version: descriptor.version.trim() } : {})
     };
 }
+function normalizeRerankerDescriptor(descriptor) {
+    const provider = descriptor.provider.trim().toLowerCase();
+    if (provider.length === 0) {
+        throw new Error("invalid reranker descriptor: provider must be non-empty");
+    }
+    const model = descriptor.model?.trim();
+    return {
+        provider,
+        ...(model ? { model } : {})
+    };
+}
+function normalizeEnhancerProviderDescriptor(descriptor) {
+    const provider = descriptor.provider.trim().toLowerCase();
+    if (provider.length === 0) {
+        throw new Error("invalid enhancer descriptor: provider must be non-empty");
+    }
+    const model = descriptor.model?.trim();
+    return {
+        provider,
+        ...(model ? { model } : {})
+    };
+}
+function buildRerankerDocument(candidate) {
+    return `${candidate.path}\n${candidate.snippet}`;
+}
+function classifyRerankerFailureReason(error) {
+    if (error instanceof RerankerProviderRequestError) {
+        if (error.reason === "timeout") {
+            return "timeout";
+        }
+        if (error.reason === "rate_limited") {
+            return "rate_limited";
+        }
+        if (error.reason === "invalid_json" || error.reason === "invalid_response") {
+            return "schema_error";
+        }
+        return "upstream_error";
+    }
+    if (error instanceof Error) {
+        if (/(rate.?limit|too many requests|429)/i.test(error.message)) {
+            return "rate_limited";
+        }
+        if (/(timeout|timed out)/i.test(error.message)) {
+            return "timeout";
+        }
+        return "upstream_error";
+    }
+    return "upstream_error";
+}
+function classifyEnhancerGenerationFailureReason(error) {
+    if (error instanceof EnhancerProviderRequestError) {
+        return error.reason;
+    }
+    if (error instanceof Error) {
+        if (/(timeout|timed out)/i.test(error.message)) {
+            return "timeout";
+        }
+        if (/(rate.?limit|too many requests|429)/i.test(error.message)) {
+            return "rate_limited";
+        }
+        return "upstream_error";
+    }
+    return "upstream_error";
+}
 function classifyIntent(prompt) {
     const p = prompt.toLowerCase();
     if (/fix|bug|error|crash|regression/.test(p)) {
@@ -1021,6 +2543,38 @@ function classifyIntent(prompt) {
     }
     return "unknown";
 }
+function resolveEnhancerPromptStyle(input) {
+    const requested = input.requested ?? "standard";
+    if (requested !== "auto") {
+        return {
+            requested,
+            resolved: requested
+        };
+    }
+    const combined = `${input.prompt}\n${input.history.map((entry) => entry.content).join("\n")}`.trim();
+    const words = tokenize(combined);
+    const isShort = words.length <= 18 && input.history.length <= 1;
+    const asksConcise = /\b(concise|brief|short|minimal|quick)\b/i.test(combined);
+    const asksDepth = /\b(detailed|comprehensive|thorough|step-by-step|checklist)\b/i.test(combined);
+    const highRisk = /\b(security|auth|authorization|tenant|workspace|migration|data loss|rollback|incident|compliance|backward)\b/i.test(combined);
+    const complexityScore = Number(input.has_context) + Number(words.length >= 32) + Number(input.history.length >= 3);
+    if (asksConcise || (isShort && !highRisk && !asksDepth)) {
+        return {
+            requested,
+            resolved: "lean"
+        };
+    }
+    if (asksDepth || highRisk || complexityScore >= 2 || input.query_intent === "symbol-heavy" || input.intent === "tests") {
+        return {
+            requested,
+            resolved: "deep"
+        };
+    }
+    return {
+        requested,
+        resolved: "standard"
+    };
+}
 function detectDominantLanguage(prompt, history) {
     const latestUser = [...history].reverse().find((m) => m.role === "user")?.content ?? prompt;
     const sample = `${prompt}\n${latestUser}`.toLowerCase();
@@ -1464,7 +3018,7 @@ function buildEnhancerRetrievalQuery(prompt, history, options) {
         query_intent: queryIntent
     };
 }
-const ENHANCER_LOW_CONFIDENCE_WARNING = "Low retrieval confidence; narrowed context refs and added clarification questions.";
+const ENHANCER_LOW_CONFIDENCE_WARNING = "Low retrieval confidence; narrowed context refs.";
 const ENHANCER_CONFIDENCE_OVERLAP_STOPWORDS = new Set([
     "a",
     "about",
@@ -1612,38 +3166,725 @@ function isRiskyEnhancerPath(path, intent) {
     }
     return isDocsLikePath(path) || isTestLikePath(path) || isExampleLikePath(path);
 }
-function applyEnhancerIntentPathFiltering(results, input) {
-    if (results.length === 0) {
-        return [];
+function applyEnhancerIntentPathFiltering(results, input) {
+    if (results.length === 0) {
+        return [];
+    }
+    const preferred = results.filter((result) => !isRiskyEnhancerPath(result.path, input.intent) && !shouldAvoidPathFromNegation(result.path, input.negative_preferences));
+    if (preferred.length > 0) {
+        return preferred;
+    }
+    if (input.strict_impl_only_filtering) {
+        const implOnly = results.filter((result) => !isDocsLikePath(result.path) &&
+            !isTestLikePath(result.path) &&
+            !isExampleLikePath(result.path) &&
+            !isArchiveLikePath(result.path));
+        if (implOnly.length > 0) {
+            return implOnly;
+        }
+    }
+    const tolerated = results.filter((result) => !shouldAvoidPathFromNegation(result.path, input.negative_preferences));
+    return tolerated.length > 0 ? tolerated : results;
+}
+function compareSearchResults(a, b) {
+    const scoreDiff = b.score - a.score;
+    if (Math.abs(scoreDiff) > 1e-9) {
+        return scoreDiff;
+    }
+    if (a.path !== b.path) {
+        return a.path.localeCompare(b.path);
+    }
+    if (a.start_line !== b.start_line) {
+        return a.start_line - b.start_line;
+    }
+    return a.end_line - b.end_line;
+}
+function compareSearchResultsByLineRange(a, b) {
+    if (a.start_line !== b.start_line) {
+        return a.start_line - b.start_line;
+    }
+    if (a.end_line !== b.end_line) {
+        return a.end_line - b.end_line;
+    }
+    return compareSearchResults(a, b);
+}
+function mergeSnippetCluster(cluster, mergedStartLine, mergedEndLine) {
+    const byRelevance = [...cluster].sort(compareSearchResults);
+    const primary = byRelevance[0];
+    if (!primary) {
+        return "";
+    }
+    const lineMap = new Map();
+    for (let rank = 0; rank < byRelevance.length; rank += 1) {
+        const candidate = byRelevance[rank];
+        if (!candidate) {
+            continue;
+        }
+        const lines = candidate.snippet.replace(/\r\n/g, "\n").split("\n");
+        const expectedLineCount = Math.max(1, candidate.end_line - candidate.start_line + 1);
+        const maxLines = Math.min(lines.length, expectedLineCount);
+        for (let offset = 0; offset < maxLines; offset += 1) {
+            const lineNumber = candidate.start_line + offset;
+            if (lineNumber < mergedStartLine || lineNumber > mergedEndLine) {
+                continue;
+            }
+            const text = lines[offset];
+            if (typeof text !== "string") {
+                continue;
+            }
+            const existing = lineMap.get(lineNumber);
+            if (!existing || candidate.score > existing.score + 1e-9 || (Math.abs(candidate.score - existing.score) <= 1e-9 && rank < existing.rank)) {
+                lineMap.set(lineNumber, { text, score: candidate.score, rank });
+            }
+        }
+    }
+    const mergedLines = [];
+    let missingLines = 0;
+    for (let line = mergedStartLine; line <= mergedEndLine; line += 1) {
+        const entry = lineMap.get(line);
+        if (!entry) {
+            missingLines += 1;
+            mergedLines.push("");
+            continue;
+        }
+        mergedLines.push(entry.text);
+    }
+    const totalLines = Math.max(1, mergedEndLine - mergedStartLine + 1);
+    const maxMissingLines = Math.max(2, Math.floor(totalLines * 0.2));
+    if (missingLines > maxMissingLines) {
+        return primary.snippet;
+    }
+    return mergedLines.join("\n");
+}
+function mergeCandidateCluster(cluster) {
+    if (cluster.length === 0) {
+        throw new Error("mergeCandidateCluster requires at least one candidate");
+    }
+    if (cluster.length === 1) {
+        return cluster[0];
+    }
+    const byRelevance = [...cluster].sort(compareSearchResults);
+    const primary = byRelevance[0];
+    const mergedStartLine = Math.min(...cluster.map((candidate) => candidate.start_line));
+    const mergedEndLine = Math.max(...cluster.map((candidate) => candidate.end_line));
+    const stitchedSnippet = mergeSnippetCluster(cluster, mergedStartLine, mergedEndLine);
+    return {
+        ...primary,
+        start_line: mergedStartLine,
+        end_line: mergedEndLine,
+        snippet: stitchedSnippet.length > 0 ? stitchedSnippet : primary.snippet
+    };
+}
+const HEAVY_LINE_RANGE_OVERLAP_RATIO = 0.2;
+function lineRangeLength(startLine, endLine) {
+    return Math.max(1, endLine - startLine + 1);
+}
+function lineRangeOverlapLength(aStartLine, aEndLine, bStartLine, bEndLine) {
+    const start = Math.max(aStartLine, bStartLine);
+    const end = Math.min(aEndLine, bEndLine);
+    if (end < start) {
+        return 0;
+    }
+    return end - start + 1;
+}
+function isHeavilyOverlappingLineRange(candidate, selectedRanges) {
+    for (const selected of selectedRanges) {
+        const overlapLength = lineRangeOverlapLength(selected.start_line, selected.end_line, candidate.start_line, candidate.end_line);
+        if (overlapLength <= 0) {
+            continue;
+        }
+        const smallerRange = Math.min(lineRangeLength(selected.start_line, selected.end_line), lineRangeLength(candidate.start_line, candidate.end_line));
+        const overlapRatio = overlapLength / Math.max(1, smallerRange);
+        if (overlapRatio >= HEAVY_LINE_RANGE_OVERLAP_RATIO) {
+            return true;
+        }
+    }
+    return false;
+}
+function mergeLineSpans(spans) {
+    if (spans.length <= 1) {
+        return [...spans];
+    }
+    const ordered = [...spans]
+        .filter((span) => span.end_line >= span.start_line)
+        .sort((a, b) => a.start_line - b.start_line || a.end_line - b.end_line);
+    const merged = [];
+    for (const span of ordered) {
+        const last = merged[merged.length - 1];
+        if (!last || span.start_line > last.end_line + 1) {
+            merged.push({ ...span });
+            continue;
+        }
+        last.end_line = Math.max(last.end_line, span.end_line);
+    }
+    return merged;
+}
+function lineRangeGap(anchor, candidate) {
+    if (candidate.start_line > anchor.end_line) {
+        return candidate.start_line - anchor.end_line - 1;
+    }
+    if (anchor.start_line > candidate.end_line) {
+        return anchor.start_line - candidate.end_line - 1;
+    }
+    return 0;
+}
+function buildPreferredLineMap(candidates) {
+    const byRelevance = [...candidates].sort(compareSearchResults);
+    const lineMap = new Map();
+    for (let rank = 0; rank < byRelevance.length; rank += 1) {
+        const candidate = byRelevance[rank];
+        if (!candidate) {
+            continue;
+        }
+        const lines = candidate.snippet.replace(/\r\n/g, "\n").split("\n");
+        const expectedLineCount = Math.max(1, candidate.end_line - candidate.start_line + 1);
+        const maxLines = Math.min(lines.length, expectedLineCount);
+        for (let offset = 0; offset < maxLines; offset += 1) {
+            const lineNumber = candidate.start_line + offset;
+            const text = lines[offset];
+            if (typeof text !== "string") {
+                continue;
+            }
+            const existing = lineMap.get(lineNumber);
+            if (!existing || candidate.score > existing.score + 1e-9 || (Math.abs(candidate.score - existing.score) <= 1e-9 && rank < existing.rank)) {
+                lineMap.set(lineNumber, { text, score: candidate.score, rank });
+            }
+        }
+    }
+    return new Map([...lineMap.entries()].map(([line, value]) => [line, value.text]));
+}
+function clipSnippetToMaxChars(snippet, maxChars) {
+    if (snippet.length <= maxChars) {
+        return snippet;
+    }
+    const clipped = snippet.slice(0, Math.max(0, maxChars));
+    const lastNewline = clipped.lastIndexOf("\n");
+    if (lastNewline > 80) {
+        return clipped.slice(0, lastNewline).trimEnd();
+    }
+    return clipped.trimEnd();
+}
+function snippetIntegrityLanguageFromPath(path) {
+    const extension = fileExtension(path);
+    if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
+        return "typescript";
+    }
+    if (extension === ".tsx") {
+        return "tsx";
+    }
+    if (extension === ".js" || extension === ".mjs" || extension === ".cjs") {
+        return "javascript";
+    }
+    if (extension === ".jsx") {
+        return "jsx";
+    }
+    return undefined;
+}
+function firstNonEmptyLine(snippet) {
+    const lines = snippet.replace(/\r\n/g, "\n").split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    return "";
+}
+function lastNonEmptyLine(snippet) {
+    const lines = snippet.replace(/\r\n/g, "\n").split("\n");
+    for (let idx = lines.length - 1; idx >= 0; idx -= 1) {
+        const trimmed = (lines[idx] ?? "").trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    return "";
+}
+function curlyBraceDelta(snippet) {
+    let opens = 0;
+    let closes = 0;
+    for (const char of snippet) {
+        if (char === "{") {
+            opens += 1;
+            continue;
+        }
+        if (char === "}") {
+            closes += 1;
+        }
+    }
+    return opens - closes;
+}
+function looksLikeDeclarationStart(line) {
+    if (line.length === 0) {
+        return false;
+    }
+    if (line.startsWith("@")) {
+        return true;
+    }
+    return (/^(?:export\s+)?(?:async\s+)?function\s+[A-Za-z_$][\w$]*\s*\(/u.test(line) ||
+        /^(?:export\s+)?(?:default\s+)?class\s+[A-Za-z_$][\w$]*/u.test(line) ||
+        /^(?:export\s+)?(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=/u.test(line) ||
+        /^(?:public|private|protected|static|readonly|async)\s+[A-Za-z_$][\w$]*\s*\(/u.test(line) ||
+        /^(?:[A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{/u.test(line));
+}
+function looksLikeSnippetTerminalBoundary(line) {
+    if (line.length === 0) {
+        return false;
+    }
+    return (line.endsWith("}") ||
+        line.endsWith("};") ||
+        line.endsWith(");") ||
+        line.endsWith("]") ||
+        line.endsWith("];"));
+}
+function detectSnippetSymbolName(snippet) {
+    const lines = snippet.replace(/\r\n/g, "\n").split("\n").slice(0, 40);
+    const patterns = [
+        /^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/u,
+        /^(?:export\s+)?(?:default\s+)?class\s+([A-Za-z_$][\w$]*)\b/u,
+        /^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>/u,
+        /^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?[A-Za-z_$][\w$]*\s*=>/u,
+        /^(?:public|private|protected|static|readonly|async)\s+([A-Za-z_$][\w$]*)\s*\(/u,
+        /^([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{/u
+    ];
+    const disallowed = new Set(["if", "for", "while", "switch", "catch", "return"]);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        for (const pattern of patterns) {
+            const match = trimmed.match(pattern);
+            const symbol = match?.[1];
+            if (symbol && !disallowed.has(symbol)) {
+                return symbol;
+            }
+        }
+    }
+    return undefined;
+}
+function shouldAnnotateSnippetAsTruncated(result, omittedBefore, omittedAfter) {
+    if (omittedBefore <= 0 && omittedAfter <= 0) {
+        return false;
+    }
+    const firstLine = firstNonEmptyLine(result.snippet);
+    const lastLine = lastNonEmptyLine(result.snippet);
+    if (omittedBefore > 0 && !looksLikeDeclarationStart(firstLine)) {
+        return true;
+    }
+    if (omittedAfter > 0) {
+        if (curlyBraceDelta(result.snippet) > 0) {
+            return true;
+        }
+        if (!looksLikeSnippetTerminalBoundary(lastLine)) {
+            return true;
+        }
+    }
+    return omittedBefore > 0 && omittedAfter > 0;
+}
+function estimateContiguousEnvelope(input) {
+    let start = input.anchor.start_line;
+    let end = input.anchor.end_line;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const candidate of input.candidates) {
+            const gap = lineRangeGap({ start_line: start, end_line: end }, candidate);
+            if (gap > input.maxGapLines) {
+                continue;
+            }
+            const nextStart = Math.min(start, candidate.start_line);
+            const nextEnd = Math.max(end, candidate.end_line);
+            if (nextStart !== start || nextEnd !== end) {
+                start = nextStart;
+                end = nextEnd;
+                changed = true;
+            }
+        }
+    }
+    return { start_line: start, end_line: end };
+}
+function repairSnippetFromEnvelope(input) {
+    const envelopeSpan = input.envelope.end_line - input.envelope.start_line + 1;
+    if (envelopeSpan > input.config.repair_max_envelope_lines) {
+        return { reason: "envelope_cap_exceeded", clipped: false };
+    }
+    const envelopeCandidates = input.samePathCandidates
+        .filter((candidate) => candidate.end_line >= input.envelope.start_line && candidate.start_line <= input.envelope.end_line)
+        .sort(compareSearchResultsByLineRange);
+    if (envelopeCandidates.length === 0) {
+        return { reason: "no_envelope_candidates", clipped: false };
+    }
+    const lineMap = buildPreferredLineMap(envelopeCandidates);
+    const renderedLines = [];
+    let missingLines = 0;
+    for (let line = input.envelope.start_line; line <= input.envelope.end_line; line += 1) {
+        const text = lineMap.get(line);
+        if (typeof text !== "string") {
+            missingLines += 1;
+            renderedLines.push("");
+            continue;
+        }
+        renderedLines.push(text);
+    }
+    const maxMissingLines = Math.max(2, Math.floor(envelopeSpan * 0.2));
+    if (missingLines > maxMissingLines) {
+        return { reason: "missing_line_density_too_high", clipped: false };
+    }
+    const clippedLines = [];
+    let usedChars = 0;
+    let clipped = false;
+    for (let index = 0; index < renderedLines.length; index += 1) {
+        const line = renderedLines[index] ?? "";
+        const additionalChars = index === 0 ? line.length : line.length + 1;
+        if (clippedLines.length > 0 && usedChars + additionalChars > input.config.repair_max_snippet_chars) {
+            clipped = true;
+            break;
+        }
+        if (clippedLines.length === 0 && line.length > input.config.repair_max_snippet_chars) {
+            const clippedLine = line.slice(0, input.config.repair_max_snippet_chars);
+            if (clippedLine.length === 0) {
+                return { reason: "snippet_char_cap_exceeded", clipped: false };
+            }
+            clippedLines.push(clippedLine);
+            usedChars = clippedLine.length;
+            clipped = true;
+            break;
+        }
+        clippedLines.push(line);
+        usedChars += additionalChars;
+    }
+    if (clippedLines.length === 0) {
+        return { reason: "snippet_char_cap_exceeded", clipped: false };
+    }
+    const repairedSnippet = clippedLines.join("\n").trimEnd();
+    if (repairedSnippet.length === 0) {
+        return { reason: "empty_repaired_snippet", clipped: false };
+    }
+    const repairedEndLine = input.envelope.start_line + clippedLines.length - 1;
+    return {
+        repaired: {
+            ...input.anchor,
+            start_line: input.envelope.start_line,
+            end_line: repairedEndLine,
+            snippet: repairedSnippet
+        },
+        clipped
+    };
+}
+function buildSnippetTruncationMarker(input) {
+    const estimatedTotalLines = Math.max(1, input.envelope_end_line - input.envelope_start_line + 1);
+    const omittedBefore = Math.max(0, input.result.start_line - input.envelope_start_line);
+    const omittedAfter = Math.max(0, input.envelope_end_line - input.result.end_line);
+    return `// [truncated:${input.marker_template_version} symbol=${input.symbolName ?? "unknown"} estimated_span=${input.envelope_start_line}-${input.envelope_end_line} estimated_total_lines=${estimatedTotalLines} omitted_before=${omittedBefore} omitted_after=${omittedAfter} through_line=${input.result.end_line}]`;
+}
+function annotateSearchResultsWithSnippetIntegrity(input) {
+    if (!input.config.enabled || input.selected.length === 0) {
+        return [...input.selected];
+    }
+    const enabledLanguages = new Set(normalizeSnippetIntegrityLanguageList(input.config.target_languages));
+    if (enabledLanguages.size === 0) {
+        return [...input.selected];
+    }
+    const sourceByPath = new Map();
+    for (const candidate of input.sourceCandidates) {
+        const rows = sourceByPath.get(candidate.path);
+        if (rows) {
+            rows.push(candidate);
+        }
+        else {
+            sourceByPath.set(candidate.path, [candidate]);
+        }
+    }
+    return input.selected.map((result) => {
+        const language = snippetIntegrityLanguageFromPath(result.path);
+        if (!language || !enabledLanguages.has(language)) {
+            return result;
+        }
+        const samePath = sourceByPath.get(result.path) ?? [result];
+        if (samePath.length <= 1) {
+            return result;
+        }
+        const envelope = estimateContiguousEnvelope({
+            anchor: result,
+            candidates: samePath,
+            maxGapLines: input.config.max_contiguous_gap_lines
+        });
+        const originalOmittedBefore = Math.max(0, result.start_line - envelope.start_line);
+        const originalOmittedAfter = Math.max(0, envelope.end_line - result.end_line);
+        const originalLooksTruncated = shouldAnnotateSnippetAsTruncated(result, originalOmittedBefore, originalOmittedAfter);
+        if (!originalLooksTruncated) {
+            return result;
+        }
+        const envelopeCandidates = samePath
+            .filter((candidate) => candidate.end_line >= envelope.start_line && candidate.start_line <= envelope.end_line)
+            .sort(compareSearchResultsByLineRange);
+        let assembled = result;
+        if (input.config.repair_enabled) {
+            input.observability.metrics.increment("retrieval_snippet_repair_attempt_total", 1, {
+                retrieval_profile_id: input.retrievalProfileId,
+                language
+            });
+            const repairOutcome = repairSnippetFromEnvelope({
+                anchor: result,
+                envelope,
+                samePathCandidates: samePath,
+                config: input.config
+            });
+            if (repairOutcome.repaired) {
+                assembled = repairOutcome.repaired;
+                input.observability.metrics.increment("retrieval_snippet_repair_success_total", 1, {
+                    retrieval_profile_id: input.retrievalProfileId,
+                    language,
+                    clipped: repairOutcome.clipped ? "true" : "false"
+                });
+                input.observability.logger.info("snippet integrity repair decision", {
+                    retrieval_profile_id: input.retrievalProfileId,
+                    path: result.path,
+                    language,
+                    envelope_start_line: envelope.start_line,
+                    envelope_end_line: envelope.end_line,
+                    envelope_span_lines: envelope.end_line - envelope.start_line + 1,
+                    status: "repaired",
+                    clipped: repairOutcome.clipped
+                });
+            }
+            else {
+                input.observability.logger.info("snippet integrity repair decision", {
+                    retrieval_profile_id: input.retrievalProfileId,
+                    path: result.path,
+                    language,
+                    envelope_start_line: envelope.start_line,
+                    envelope_end_line: envelope.end_line,
+                    envelope_span_lines: envelope.end_line - envelope.start_line + 1,
+                    status: "repair_skipped",
+                    reason: repairOutcome.reason ?? "unknown"
+                });
+            }
+        }
+        const omittedBefore = Math.max(0, assembled.start_line - envelope.start_line);
+        const omittedAfter = Math.max(0, envelope.end_line - assembled.end_line);
+        if (!shouldAnnotateSnippetAsTruncated(assembled, omittedBefore, omittedAfter)) {
+            return assembled;
+        }
+        let symbolName = detectSnippetSymbolName(assembled.snippet);
+        if (!symbolName) {
+            for (const candidate of envelopeCandidates) {
+                symbolName = detectSnippetSymbolName(candidate.snippet);
+                if (symbolName) {
+                    break;
+                }
+            }
+        }
+        const marker = buildSnippetTruncationMarker({
+            result: assembled,
+            symbolName,
+            envelope_start_line: envelope.start_line,
+            envelope_end_line: envelope.end_line,
+            marker_template_version: input.config.marker_template_version
+        });
+        input.observability.metrics.increment("retrieval_snippet_repair_fallback_marker_total", 1, {
+            retrieval_profile_id: input.retrievalProfileId,
+            language
+        });
+        input.observability.metrics.increment("retrieval_snippet_truncation_marker_total", 1, {
+            retrieval_profile_id: input.retrievalProfileId,
+            language,
+            symbol_detected: symbolName ? "true" : "false",
+            marker_template_version: input.config.marker_template_version
+        });
+        input.observability.metrics.observe("retrieval_snippet_omitted_after_lines", omittedAfter, {
+            retrieval_profile_id: input.retrievalProfileId,
+            language
+        });
+        const baseSnippet = assembled.snippet.trimEnd();
+        return {
+            ...assembled,
+            snippet: baseSnippet.length > 0 ? `${baseSnippet}\n${marker}` : marker
+        };
+    });
+}
+function packSearchResultsWithContext(input) {
+    if (!input.config.enabled || input.selected.length === 0) {
+        return [...input.selected];
+    }
+    const sourceByPath = new Map();
+    for (const candidate of input.sourceCandidates) {
+        const rows = sourceByPath.get(candidate.path);
+        if (rows) {
+            rows.push(candidate);
+        }
+        else {
+            sourceByPath.set(candidate.path, [candidate]);
+        }
+    }
+    return input.selected.map((anchor) => {
+        const samePath = sourceByPath.get(anchor.path) ?? [anchor];
+        if (samePath.length <= 1 || input.config.max_spans_per_result <= 1) {
+            return anchor;
+        }
+        const anchorRange = { start_line: anchor.start_line, end_line: anchor.end_line };
+        const candidates = samePath
+            .filter((candidate) => !(candidate.start_line === anchor.start_line && candidate.end_line === anchor.end_line) &&
+            !isHeavilyOverlappingLineRange(candidate, [anchorRange]) &&
+            lineRangeGap(anchorRange, candidate) <= input.config.max_gap_lines)
+            .sort((a, b) => {
+            const relevanceDiff = compareSearchResults(a, b);
+            if (relevanceDiff !== 0) {
+                return relevanceDiff;
+            }
+            return lineRangeGap(anchorRange, a) - lineRangeGap(anchorRange, b);
+        });
+        const spans = [{ ...anchorRange }];
+        for (const candidate of candidates) {
+            if (spans.length >= input.config.max_spans_per_result) {
+                break;
+            }
+            const nextSpan = { start_line: candidate.start_line, end_line: candidate.end_line };
+            const nextEnvelope = mergeLineSpans([...spans, nextSpan]);
+            if (nextEnvelope.some((span, idx) => idx > 0 && span.start_line - (nextEnvelope[idx - 1]?.end_line ?? span.start_line) - 1 > input.config.max_gap_lines)) {
+                continue;
+            }
+            spans.push(nextSpan);
+        }
+        const mergedSpans = mergeLineSpans(spans);
+        if (mergedSpans.length <= 1) {
+            return anchor;
+        }
+        const lineMap = buildPreferredLineMap([anchor, ...samePath]);
+        const renderedLines = [];
+        let contentLineCount = 0;
+        let elisionCount = 0;
+        for (let index = 0; index < mergedSpans.length; index += 1) {
+            const span = mergedSpans[index];
+            if (!span) {
+                continue;
+            }
+            if (index > 0) {
+                const previous = mergedSpans[index - 1];
+                if (previous && span.start_line - previous.end_line > 0) {
+                    renderedLines.push("...");
+                    elisionCount += 1;
+                }
+            }
+            for (let line = span.start_line; line <= span.end_line; line += 1) {
+                renderedLines.push(lineMap.get(line) ?? "");
+                contentLineCount += 1;
+            }
+        }
+        if (renderedLines.length === 0) {
+            return anchor;
+        }
+        const elisionDensity = elisionCount / Math.max(1, contentLineCount + elisionCount);
+        if (elisionDensity > 0.25) {
+            return anchor;
+        }
+        const packedSnippet = clipSnippetToMaxChars(renderedLines.join("\n"), input.config.max_snippet_chars);
+        if (packedSnippet.length === 0) {
+            return anchor;
+        }
+        const packedStart = mergedSpans[0]?.start_line ?? anchor.start_line;
+        const packedEnd = mergedSpans[mergedSpans.length - 1]?.end_line ?? anchor.end_line;
+        return {
+            ...anchor,
+            start_line: packedStart,
+            end_line: packedEnd,
+            snippet: packedSnippet,
+            reason: `${anchor.reason} + contextual spans`
+        };
+    });
+}
+function mergeOverlappingCandidates(candidates, config) {
+    if (!config.merge_overlapping_chunks_enabled || candidates.length <= 1) {
+        return [...candidates];
     }
-    const preferred = results.filter((result) => !isRiskyEnhancerPath(result.path, input.intent) && !shouldAvoidPathFromNegation(result.path, input.negative_preferences));
-    if (preferred.length > 0) {
-        return preferred;
+    const byPath = new Map();
+    for (const candidate of candidates) {
+        const group = byPath.get(candidate.path);
+        if (group) {
+            group.push(candidate);
+        }
+        else {
+            byPath.set(candidate.path, [candidate]);
+        }
     }
-    if (input.strict_impl_only_filtering) {
-        const implOnly = results.filter((result) => !isDocsLikePath(result.path) &&
-            !isTestLikePath(result.path) &&
-            !isExampleLikePath(result.path) &&
-            !isArchiveLikePath(result.path));
-        if (implOnly.length > 0) {
-            return implOnly;
+    const merged = [];
+    for (const group of byPath.values()) {
+        const ordered = [...group].sort(compareSearchResultsByLineRange);
+        let cluster = [];
+        let clusterStart = 0;
+        let clusterEnd = 0;
+        const flush = () => {
+            if (cluster.length === 0) {
+                return;
+            }
+            merged.push(mergeCandidateCluster(cluster));
+            cluster = [];
+        };
+        for (const candidate of ordered) {
+            if (cluster.length === 0) {
+                cluster = [candidate];
+                clusterStart = candidate.start_line;
+                clusterEnd = candidate.end_line;
+                continue;
+            }
+            const nextStart = Math.min(clusterStart, candidate.start_line);
+            const nextEnd = Math.max(clusterEnd, candidate.end_line);
+            const nextSpan = nextEnd - nextStart + 1;
+            const gapLines = Math.max(0, candidate.start_line - clusterEnd - 1);
+            const canMerge = gapLines <= config.merge_gap_lines && nextSpan <= config.merge_max_span_lines;
+            if (!canMerge) {
+                flush();
+                cluster = [candidate];
+                clusterStart = candidate.start_line;
+                clusterEnd = candidate.end_line;
+                continue;
+            }
+            cluster.push(candidate);
+            clusterStart = nextStart;
+            clusterEnd = nextEnd;
         }
+        flush();
     }
-    const tolerated = results.filter((result) => !shouldAvoidPathFromNegation(result.path, input.negative_preferences));
-    return tolerated.length > 0 ? tolerated : results;
+    return merged.sort(compareSearchResults);
 }
-function compareSearchResults(a, b) {
-    const scoreDiff = b.score - a.score;
-    if (Math.abs(scoreDiff) > 1e-9) {
-        return scoreDiff;
-    }
-    if (a.path !== b.path) {
-        return a.path.localeCompare(b.path);
-    }
-    if (a.start_line !== b.start_line) {
-        return a.start_line - b.start_line;
+function applySmartCutoffCandidates(candidates, config) {
+    if (!config.smart_cutoff_enabled || candidates.length === 0) {
+        return [...candidates];
+    }
+    const ordered = [...candidates].sort(compareSearchResults);
+    const minK = Math.max(1, config.smart_cutoff_min_k);
+    const maxK = Math.max(minK, config.smart_cutoff_max_k);
+    const topScore = ordered[0]?.score ?? Number.NEGATIVE_INFINITY;
+    const kept = [];
+    for (let index = 0; index < ordered.length; index += 1) {
+        const candidate = ordered[index];
+        if (!candidate) {
+            continue;
+        }
+        if (kept.length >= maxK) {
+            break;
+        }
+        if (kept.length < minK) {
+            kept.push(candidate);
+            continue;
+        }
+        if (candidate.score < config.smart_cutoff_min_score) {
+            break;
+        }
+        if (candidate.score < topScore * config.smart_cutoff_top_ratio) {
+            break;
+        }
+        const previous = ordered[index - 1];
+        if (previous && previous.score - candidate.score > config.smart_cutoff_delta_abs) {
+            break;
+        }
+        kept.push(candidate);
     }
-    return a.end_line - b.end_line;
+    return kept;
+}
+export function __applySmartCutoffCandidatesForTests(input) {
+    return applySmartCutoffCandidates(input.candidates, input.config);
 }
 function dedupeEnhancerCandidatesByPath(results) {
     const byPath = new Map();
@@ -1701,7 +3942,7 @@ function hasStrongEnhancerAnchorMatch(input) {
     const topScore = top[0]?.score ?? 0;
     const runnerUpScore = top[1]?.score ?? Number.NEGATIVE_INFINITY;
     const strongScoreMargin = top.length === 1 || topScore - runnerUpScore >= 0.08;
-    const hasTopExactSymbolMatch = top.some((result) => result.reason === "exact symbol match");
+    const hasTopExactSymbolMatch = top.some((result) => isExactLiteralReason(result.reason));
     if (hasTopExactSymbolMatch && strongScoreMargin && topScore >= 0.55) {
         return true;
     }
@@ -1792,7 +4033,7 @@ function evaluateEnhancerConfidence(input) {
     if (diversityStrength < confidenceThreshold) {
         failedSignals.push("path_diversity");
     }
-    const strongSymbolOrPathSignal = top.some((result) => result.reason === "exact symbol match") && topOverlap >= 0.16;
+    const strongSymbolOrPathSignal = top.some((result) => isExactLiteralReason(result.reason)) && topOverlap >= 0.16;
     const lowConfidence = !strongSymbolOrPathSignal && confidenceScore + 0.01 < confidenceThreshold;
     return {
         score_spread: scoreSpread,
@@ -1810,7 +4051,7 @@ function rankEnhancerResultsForConfidence(input) {
     const anchorScore = (result) => {
         const normalizedPath = normalizePath(result.path).toLowerCase();
         const normalizedSnippet = result.snippet.toLowerCase();
-        let score = result.reason === "exact symbol match" ? 2 : 0;
+        let score = isExactLiteralReason(result.reason) ? 2 : 0;
         for (const anchor of anchors) {
             if (normalizedPath.includes(anchor)) {
                 score += 2;
@@ -1869,6 +4110,7 @@ async function runWithTimeout(input) {
                 return;
             }
             settled = true;
+            input.on_timeout?.();
             reject(new Error(`timeout_after_${input.timeout_ms}ms`));
         }, input.timeout_ms);
         Promise.resolve()
@@ -1891,50 +4133,67 @@ async function runWithTimeout(input) {
         });
     });
 }
+async function runWithInactivityTimeout(input) {
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const abortController = new AbortController();
+        let timer;
+        const onTimeout = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            abortController.abort();
+            reject(new Error(`timeout_after_${input.timeout_ms}ms`));
+        };
+        const touch = () => {
+            if (settled) {
+                return;
+            }
+            if (timer) {
+                clearTimeout(timer);
+            }
+            timer = setTimeout(onTimeout, input.timeout_ms);
+        };
+        touch();
+        Promise.resolve()
+            .then(() => input.fn({
+            touch,
+            signal: abortController.signal
+        }))
+            .then((value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            resolve(value);
+        })
+            .catch((error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            reject(error);
+        });
+    });
+}
 function deterministicEnhancerFallbackRanking(input) {
     const preferred = input.results.filter((result) => !isRiskyEnhancerPath(result.path, input.intent) && !shouldAvoidPathFromNegation(result.path, input.negative_preferences));
     const tolerated = input.results.filter((result) => !preferred.includes(result) && !shouldAvoidPathFromNegation(result.path, input.negative_preferences));
     const avoided = input.results.filter((result) => !preferred.includes(result) && !tolerated.includes(result));
     return [...preferred, ...tolerated, ...avoided];
 }
-function localizeLowConfidenceQuestion(input) {
-    if (input.kind === "symbol") {
-        if (input.language === "es") {
-            return input.symbol
-                ? `¿Puedes confirmar si el cambio debe centrarse en el símbolo "${input.symbol}"?`
-                : "¿Qué función, clase o archivo exacto debe modificarse primero?";
-        }
-        if (input.language === "zh") {
-            return input.symbol
-                ? `请确认这次改动是否应优先围绕符号“${input.symbol}”展开？`
-                : "请明确首先要修改的函数、类或文件路径。";
-        }
-        return input.symbol
-            ? `Can you confirm whether "${input.symbol}" is the primary symbol to change?`
-            : "Which exact function, class, or file should be edited first?";
-    }
-    if (input.kind === "source_priority") {
-        if (input.language === "es") {
-            return "¿Debemos priorizar archivos de implementación en src/lib y dejar docs/tests/examples fuera de alcance?";
-        }
-        if (input.language === "zh") {
-            return "是否应优先修改 src/lib 下的实现代码，并排除 docs/tests/examples？";
-        }
-        return "Should we prioritize runtime implementation files (src/lib) and exclude docs/tests/examples from scope?";
-    }
-    if (input.language === "es") {
-        return "¿Cuál es el alcance mínimo y el comportamiento que no debe cambiar?";
-    }
-    if (input.language === "zh") {
-        return "这次改动的最小范围是什么？哪些行为必须保持不变？";
-    }
-    return "What is the minimal scope, and which behavior must remain unchanged?";
-}
-function trimToContextBudget(results) {
+function trimToContextBudget(results, budgetTokenizerMode) {
     let total = 0;
     const out = [];
     for (const result of results) {
-        total += tokenize(result.snippet).length;
+        total += chunkBudgetTokenize(result.snippet, budgetTokenizerMode).length;
         if (total > MAX_CONTEXT_BUDGET_TOKENS) {
             break;
         }
@@ -1950,89 +4209,190 @@ function formatEnhancedPrompt(input) {
     };
     const likelyFiles = input.refs.length > 0 ? input.refs.map((r) => `- ${r.path}:${r.start_line}`).join("\n") : emptyRefsByLanguage[input.language];
     if (input.language === "zh") {
+        if (input.style === "lean") {
+            return [
+                "目标",
+                input.original_prompt,
+                "",
+                "约束",
+                "- 保持现有行为与合约兼容。",
+                "- 优先最小且安全的改动。",
+                "",
+                "行动步骤",
+                "- 先确认当前行为与目标范围。",
+                "- 在必要位置完成最小实现并补充回归测试。",
+                "",
+                "验证",
+                "- 运行相关测试并确认无回归。"
+            ].join("\n");
+        }
+        if (input.style === "deep") {
+            return [
+                "目标",
+                input.original_prompt,
+                "",
+                "范围与约束",
+                "- 保持现有行为与 API/合约语义稳定。",
+                "- 仅在必要边界内调整实现，避免扩散改动。",
+                "- 发现风险路径时优先失败安全（deny-by-default）。",
+                "",
+                "代码锚点",
+                likelyFiles,
+                "",
+                "实施步骤",
+                "- 基线确认：先验证当前行为与关键路径。",
+                "- 变更实现：对关键分支做最小、安全、可回退的改动。",
+                "- 回归测试：覆盖正向、跨边界、异常与空输入场景。",
+                "",
+                "边界情况",
+                "- 缺失上下文、无索引或空结果时，保持行为可解释且可回退。",
+                "- 异步/并发路径中避免上下文泄漏与跨租户访问。",
+                "",
+                "验证",
+                "- 运行 typecheck 与目标测试集；确认关键路径稳定无回归。"
+            ].join("\n");
+        }
         return [
             "目标",
             input.original_prompt,
             "",
-            "当前状态",
-            `- 识别意图: ${input.intent}`,
-            "",
             "约束",
             "- 保持 v1 合约兼容和严格校验。",
             "",
-            "可能涉及的文件",
+            "代码锚点",
             likelyFiles,
             "",
             "实现清单",
             "- 在改动前确认请求/响应合约。",
             "- 最小化改动并保持 tenant/workspace 隔离。",
             "",
-            "边界情况",
-            "- Workspace 没有可用索引。",
-            "- 搜索过滤后结果为空。",
-            "",
             "验证与测试",
             "- 运行 typecheck 和合约/工具测试。",
-            "",
-            "完成定义",
-            "- 测试通过且行为符合 v1 规范。"
         ].join("\n");
     }
     if (input.language === "es") {
+        if (input.style === "lean") {
+            return [
+                "Objetivo",
+                input.original_prompt,
+                "",
+                "Restricciones",
+                "- Mantener compatibilidad de comportamiento y contratos.",
+                "- Priorizar cambios mínimos y seguros.",
+                "",
+                "Pasos",
+                "- Confirmar alcance y comportamiento actual antes de editar.",
+                "- Implementar el cambio mínimo necesario y añadir regresiones.",
+                "",
+                "Validación",
+                "- Ejecutar pruebas relevantes y confirmar que no hay regresiones."
+            ].join("\n");
+        }
+        if (input.style === "deep") {
+            return [
+                "Objetivo",
+                input.original_prompt,
+                "",
+                "Alcance y restricciones",
+                "- Preservar comportamiento existente y contratos/API vigentes.",
+                "- Limitar cambios al alcance mínimo necesario.",
+                "- Aplicar defaults de seguridad (deny-by-default) cuando aplique.",
+                "",
+                "Anclas del código",
+                likelyFiles,
+                "",
+                "Plan de implementación",
+                "- Establecer línea base del comportamiento actual.",
+                "- Aplicar cambios mínimos y reversibles en rutas críticas.",
+                "- Añadir pruebas de regresión para casos positivos, negativos y límites.",
+                "",
+                "Casos límite",
+                "- Contexto faltante o resultados vacíos no deben romper el flujo.",
+                "- Evitar fuga de contexto entre tenants/workspaces.",
+                "",
+                "Validación",
+                "- Ejecutar typecheck y pruebas objetivo; confirmar estabilidad."
+            ].join("\n");
+        }
         return [
             "Objetivo",
             input.original_prompt,
             "",
-            "Estado actual",
-            `- Intención clasificada: ${input.intent}`,
-            "",
             "Restricciones",
             "- Mantener compatibilidad con contratos v1 y validación estricta.",
             "",
-            "Archivos probables a editar",
+            "Anclas del código",
             likelyFiles,
             "",
             "Checklist de implementación",
             "- Confirmar entradas/salidas del contrato antes de modificar lógica.",
             "- Aplicar cambios mínimos y mantener aislamiento por tenant/workspace.",
             "",
-            "Casos límite",
-            "- Workspace sin índice listo.",
-            "- Filtros de búsqueda que no devuelven resultados.",
-            "",
             "Validación y pruebas",
-            "- Ejecutar typecheck y pruebas de contratos/herramientas.",
+            "- Ejecutar typecheck y pruebas de contratos/herramientas."
+        ].join("\n");
+    }
+    if (input.style === "lean") {
+        const anchors = input.refs.length > 0 ? `- Anchors: ${input.refs.slice(0, 2).map((ref) => `${ref.path}:${ref.start_line}`).join(", ")}` : "";
+        return [
+            "Goal",
+            input.original_prompt,
+            "",
+            "Constraints",
+            "- Preserve existing behavior and contract compatibility.",
+            "- Keep changes minimal and safe.",
+            ...(anchors ? ["", anchors] : []),
+            "",
+            "Action steps",
+            "- Confirm current behavior and target scope.",
+            "- Implement the smallest safe change and add regression coverage.",
+            "",
+            "Validation",
+            "- Run relevant tests and confirm no regressions."
+        ].join("\n");
+    }
+    if (input.style === "deep") {
+        return [
+            "Goal",
+            input.original_prompt,
             "",
-            "Definición de terminado",
-            "- Los tests pasan y el comportamiento coincide con el spec."
+            "Scope and constraints",
+            "- Preserve current behavior and API/contract semantics.",
+            "- Limit changes to the required scope and keep them reversible.",
+            "- Prefer fail-secure defaults where policy boundaries are involved.",
+            "",
+            "Codebase anchors",
+            likelyFiles,
+            "",
+            "Implementation plan",
+            "- Establish baseline behavior and invariants before edits.",
+            "- Apply minimal, safe changes on critical paths only.",
+            "- Add regression coverage for positive, negative, and boundary scenarios.",
+            "",
+            "Edge cases",
+            "- Missing context, empty retrieval results, and async boundary leakage.",
+            "- Cross-tenant/workspace access paths and authorization bypass attempts.",
+            "",
+            "Validation",
+            "- Run typecheck and focused test suites; verify no behavioral regressions."
         ].join("\n");
     }
     return [
         "Goal",
         input.original_prompt,
         "",
-        "Current state",
-        `- Classified intent: ${input.intent}`,
-        "",
         "Constraints",
         "- Keep v1 contract compatibility and strict schema validation.",
         "",
-        "Likely files to edit",
+        "Codebase anchors",
         likelyFiles,
         "",
-        "Implementation checklist",
+        "Implementation plan",
         "- Confirm request/response contract assumptions before code edits.",
         "- Apply smallest safe changes while preserving tenant/workspace isolation.",
         "",
-        "Edge cases",
-        "- Workspace has no ready index.",
-        "- Search filters produce empty result sets.",
-        "",
         "Validation and tests",
-        "- Run typecheck and contract/tool tests.",
-        "",
-        "Definition of done",
-        "- Tests pass and behavior matches the v1 spec."
+        "- Run typecheck and contract/tool tests."
     ].join("\n");
 }
 function detectSecretMatches(content) {
@@ -2263,14 +4623,24 @@ export class RetrievalCore {
     store;
     cache;
     cacheTtlSeconds;
+    internalCandidateDepth;
     embeddingProvider;
     embeddingDescriptor;
+    rerankerProvider;
+    rerankerDescriptor;
+    rerankerTopN;
+    rerankerCacheVariant;
     observability;
     scoringConfig;
     scoringProfileId;
     scoringConfigChecksum;
+    enhancerProvider;
+    enhancerProviderDescriptor;
     enhancerConfig;
+    enhancerGenerationConfig;
     chunkingConfig;
+    contextPackingConfig;
+    snippetIntegrityConfig;
     enhancerDecisionTraceEnabled;
     cacheHits = 0;
     cacheMisses = 0;
@@ -2278,15 +4648,34 @@ export class RetrievalCore {
         this.store = store;
         this.cache = cache;
         this.cacheTtlSeconds = options?.cacheTtlSeconds ?? 60;
+        this.internalCandidateDepth = clampInternalCandidateDepth(options?.internalCandidateDepth);
         this.embeddingProvider = options?.embeddingProvider ?? new DeterministicEmbeddingProvider();
         this.embeddingDescriptor = normalizeEmbeddingDescriptor(options?.embeddingDescriptor ?? resolveEmbeddingDescriptor(this.embeddingProvider));
+        this.rerankerProvider = options?.rerankerProvider;
+        this.rerankerTopN = options?.rerankerTopN ?? DEFAULT_SEARCH_RERANKER_TOP_N;
+        if (!Number.isInteger(this.rerankerTopN) || this.rerankerTopN <= 0) {
+            throw new Error("invalid retrieval reranker config: rerankerTopN must be a positive integer");
+        }
+        this.rerankerDescriptor = this.rerankerProvider
+            ? normalizeRerankerDescriptor(resolveRerankerDescriptor(this.rerankerProvider))
+            : undefined;
+        this.rerankerCacheVariant = this.rerankerDescriptor
+            ? `provider:${this.rerankerDescriptor.provider}|model:${this.rerankerDescriptor.model ?? "unknown"}|top_n:${this.rerankerTopN}`
+            : "provider:disabled";
         this.observability = options?.observability ?? getObservability("retrieval-core");
         const baseProfile = resolveRetrievalScoringProfile(options?.scoringProfile);
         this.scoringConfig = mergeRetrievalScoringConfig(baseProfile.config, options?.scoringConfig);
         this.scoringProfileId = options?.scoringProfileId ?? baseProfile.profile_id;
         this.scoringConfigChecksum = scoringConfigChecksum(this.scoringConfig);
+        this.enhancerProvider = options?.enhancerProvider;
+        this.enhancerProviderDescriptor = this.enhancerProvider
+            ? normalizeEnhancerProviderDescriptor(resolveEnhancerProviderDescriptor(this.enhancerProvider))
+            : undefined;
         this.enhancerConfig = mergeRetrievalEnhancerConfig(DEFAULT_RETRIEVAL_ENHANCER_CONFIG, options?.enhancerConfig);
+        this.enhancerGenerationConfig = mergeRetrievalEnhancerGenerationConfig(DEFAULT_RETRIEVAL_ENHANCER_GENERATION_CONFIG, options?.enhancerGenerationConfig);
         this.chunkingConfig = mergeRetrievalChunkingConfig(DEFAULT_RETRIEVAL_CHUNKING_CONFIG, options?.chunkingConfig);
+        this.contextPackingConfig = mergeRetrievalContextPackingConfig(DEFAULT_RETRIEVAL_CONTEXT_PACKING_CONFIG, options?.contextPackingConfig);
+        this.snippetIntegrityConfig = mergeRetrievalSnippetIntegrityConfig(DEFAULT_RETRIEVAL_SNIPPET_INTEGRITY_CONFIG, options?.snippetIntegrityConfig);
         this.enhancerDecisionTraceEnabled = Boolean(options?.enhancerDecisionTraceEnabled);
     }
     async indexArtifact(artifact) {
@@ -2460,6 +4849,12 @@ export class RetrievalCore {
                     language: chunkLanguage,
                     reason: chunkBuild.fallback_reason ?? "none"
                 });
+                if (chunkBuild.recursive_semantic_chunking_used) {
+                    this.observability.metrics.increment("index_recursive_semantic_chunking_used_total", 1, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage
+                    });
+                }
                 if (chunkBuild.fallback_reason) {
                     this.observability.metrics.increment("index_chunking_fallback_total", 1, {
                         tenant_id: artifact.tenant_id,
@@ -2487,14 +4882,15 @@ export class RetrievalCore {
                         reason: chunkBuild.fallback_reason
                     });
                 }
-                const estimatedEmbeddingTokens = chunks.reduce((sum, chunk) => sum + tokenize(chunk.snippet).length, 0);
+                const embeddingTexts = buildChunkEmbeddingTexts(chunks, this.chunkingConfig, this.embeddingDescriptor.provider);
+                const estimatedEmbeddingTokens = embeddingTexts.reduce((sum, text) => sum + tokenize(text).length, 0);
                 this.observability.metrics.increment("index_embedding_tokens_total", estimatedEmbeddingTokens, {
                     tenant_id: artifact.tenant_id
                 });
                 const embeddings = chunks.length === 0
                     ? []
                     : await this.embeddingProvider.embed({
-                        texts: chunks.map((chunk) => chunk.snippet),
+                        texts: embeddingTexts,
                         purpose: "index"
                     });
                 if (embeddings.length !== chunks.length) {
@@ -2769,6 +5165,12 @@ export class RetrievalCore {
                     language: chunkLanguage,
                     reason: chunkBuild.fallback_reason ?? "none"
                 });
+                if (chunkBuild.recursive_semantic_chunking_used) {
+                    this.observability.metrics.increment("index_recursive_semantic_chunking_used_total", 1, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage
+                    });
+                }
                 if (chunkBuild.fallback_reason) {
                     this.observability.metrics.increment("index_chunking_fallback_total", 1, {
                         tenant_id: artifact.tenant_id,
@@ -2796,14 +5198,15 @@ export class RetrievalCore {
                         reason: chunkBuild.fallback_reason
                     });
                 }
-                const estimatedEmbeddingTokens = chunks.reduce((sum, chunk) => sum + tokenize(chunk.snippet).length, 0);
+                const embeddingTexts = buildChunkEmbeddingTexts(chunks, this.chunkingConfig, this.embeddingDescriptor.provider);
+                const estimatedEmbeddingTokens = embeddingTexts.reduce((sum, text) => sum + tokenize(text).length, 0);
                 this.observability.metrics.increment("index_embedding_tokens_total", estimatedEmbeddingTokens, {
                     tenant_id: artifact.tenant_id
                 });
                 const embeddings = chunks.length === 0
                     ? []
                     : await this.embeddingProvider.embed({
-                        texts: chunks.map((chunk) => chunk.snippet),
+                        texts: embeddingTexts,
                         purpose: "index"
                     });
                 if (embeddings.length !== chunks.length) {
@@ -2902,6 +5305,95 @@ export class RetrievalCore {
             status: existing.status
         };
     }
+    async applyLearnedReranker(input) {
+        if (!this.rerankerProvider || !this.rerankerDescriptor) {
+            return input.candidates;
+        }
+        const cappedTopN = Math.min(this.rerankerTopN, input.candidates.length);
+        if (cappedTopN <= 1) {
+            return input.candidates;
+        }
+        const head = input.candidates.slice(0, cappedTopN);
+        const tail = input.candidates.slice(cappedTopN);
+        const labels = {
+            provider: this.rerankerDescriptor.provider,
+            model: this.rerankerDescriptor.model ?? "unknown"
+        };
+        this.observability.metrics.increment("retrieval_reranker_requests_total", 1, labels);
+        const startedAt = Date.now();
+        try {
+            const reranked = await this.rerankerProvider.rerank({
+                query: input.query,
+                documents: head.map((candidate) => buildRerankerDocument(candidate)),
+                top_n: cappedTopN
+            });
+            if (!Array.isArray(reranked) || reranked.length === 0) {
+                throw new RerankerProviderRequestError("invalid_response", "reranker response must contain at least one result");
+            }
+            const seen = new Set();
+            const reordered = [];
+            for (const row of reranked) {
+                if (!Number.isInteger(row.index)) {
+                    throw new RerankerProviderRequestError("invalid_response", "reranker result index must be an integer");
+                }
+                if (row.index < 0 || row.index >= head.length) {
+                    throw new RerankerProviderRequestError("invalid_response", "reranker result index out of range");
+                }
+                if (seen.has(row.index)) {
+                    continue;
+                }
+                const candidate = head[row.index];
+                if (!candidate) {
+                    continue;
+                }
+                seen.add(row.index);
+                reordered.push(candidate);
+            }
+            for (let index = 0; index < head.length; index += 1) {
+                if (seen.has(index)) {
+                    continue;
+                }
+                const candidate = head[index];
+                if (candidate) {
+                    reordered.push(candidate);
+                }
+            }
+            if (reordered.length === 0) {
+                throw new RerankerProviderRequestError("invalid_response", "reranker did not return usable indexes");
+            }
+            const maxTailScore = tail[0]?.score ?? Number.NEGATIVE_INFINITY;
+            const maxHeadScore = head[0]?.score ?? 0;
+            const scoreAnchor = Math.max(maxHeadScore, maxTailScore) + 1;
+            const scoreStep = 1e-6;
+            const adjusted = reordered.map((candidate, index) => ({
+                ...candidate,
+                score: scoreAnchor - index * scoreStep
+            }));
+            return [...adjusted, ...tail];
+        }
+        catch (error) {
+            const reason = classifyRerankerFailureReason(error);
+            this.observability.metrics.increment("retrieval_reranker_failures_total", 1, {
+                ...labels,
+                reason
+            });
+            this.observability.metrics.increment("retrieval_reranker_fallback_total", 1, {
+                reason
+            });
+            this.observability.logger.warn("search_context reranker fallback applied", {
+                trace_id: input.trace_id,
+                provider: labels.provider,
+                model: labels.model,
+                reason,
+                top_n: cappedTopN,
+                error_message: error instanceof Error ? error.message : String(error)
+            });
+            return input.candidates;
+        }
+        finally {
+            this.observability.metrics.observe("retrieval_reranker_latency_ms", Date.now() - startedAt, labels);
+        }
+    }
     async searchContext(input) {
         const searchStartedAt = Date.now();
         const index = await this.store.getLatestReadyIndex({
@@ -2915,9 +5407,9 @@ export class RetrievalCore {
             tenant_id: input.tenant_id,
             index_id: index.index_id
         });
-        const topK = Math.min(input.request.top_k ?? 8, MAX_TOP_K);
-        const candidatePoolTopK = Math.min(MAX_TOP_K, Math.max(topK * 4, 12));
         const query = normalizeQuery(input.request.query);
+        const topK = Math.min(input.request.top_k ?? 8, MAX_TOP_K);
+        const candidatePoolTopK = Math.max(Math.max(topK * 4, 12), this.internalCandidateDepth);
         if (!indexMetadata) {
             this.observability.metrics.increment("retrieval_embedding_metadata_mismatch_total", 1, {
                 reason: "metadata_missing"
@@ -2977,12 +5469,20 @@ export class RetrievalCore {
             throw new RetrievalError("UPSTREAM_FAILURE", `embedding provider returned query embedding dimensions ${queryEmbedding.length}; expected ${this.embeddingDescriptor.dimensions}`);
         }
         const queryTokens = tokenize(query);
+        const searchLiterals = extractSearchLiterals(query);
+        this.observability.metrics.observe("retrieval_candidate_depth_requested", topK, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        this.observability.metrics.observe("retrieval_candidate_depth_effective", candidatePoolTopK, {
+            retrieval_profile_id: this.scoringProfileId
+        });
         const cacheKey = buildQueryCacheKey({
             workspace_id: input.workspace_id,
             index_version: index.index_version,
             query,
             top_k: topK,
-            filters: input.request.filters
+            filters: input.request.filters,
+            retrieval_variant: `${this.rerankerCacheVariant}|context_pack:${this.contextPackingConfig.enabled ? "on" : "off"}|context_pack_spans:${this.contextPackingConfig.max_spans_per_result}|context_pack_gap:${this.contextPackingConfig.max_gap_lines}|snippet_integrity:${this.snippetIntegrityConfig.enabled ? "on" : "off"}|snippet_integrity_gap:${this.snippetIntegrityConfig.max_contiguous_gap_lines}|snippet_integrity_langs:${this.snippetIntegrityConfig.target_languages.join(",")}|snippet_repair:${this.snippetIntegrityConfig.repair_enabled ? "on" : "off"}|snippet_repair_env:${this.snippetIntegrityConfig.repair_max_envelope_lines}|snippet_repair_chars:${this.snippetIntegrityConfig.repair_max_snippet_chars}|chunk_recursive:${this.chunkingConfig.recursive_semantic_chunking_enabled ? "on" : "off"}|chunk_semantic_gap:${this.chunkingConfig.semantic_merge_gap_lines}|chunk_semantic_span:${this.chunkingConfig.semantic_merge_max_span_lines}|chunk_comment_absorb:${this.chunkingConfig.comment_forward_absorb_enabled ? "on" : "off"}|chunk_embed_prefix:${this.chunkingConfig.embedding_context_prefix_enabled ? "on" : "off"}|smart_cutoff:${this.scoringConfig.rerank.smart_cutoff_enabled ? "on" : "off"}|smart_cutoff_min_k:${this.scoringConfig.rerank.smart_cutoff_min_k}|smart_cutoff_max_k:${this.scoringConfig.rerank.smart_cutoff_max_k}|smart_cutoff_min_score:${this.scoringConfig.rerank.smart_cutoff_min_score}|smart_cutoff_top_ratio:${this.scoringConfig.rerank.smart_cutoff_top_ratio}|smart_cutoff_delta_abs:${this.scoringConfig.rerank.smart_cutoff_delta_abs}`
         });
         const cached = await this.cache.get(cacheKey);
         if (cached) {
@@ -2999,6 +5499,8 @@ export class RetrievalCore {
             tenant_id: input.tenant_id,
             workspace_id: input.workspace_id
         }, async () => {
+            let literalPathMatchCount = 0;
+            let literalSnippetMatchCount = 0;
             let ranked;
             if (this.store.rankChunksByIndex) {
                 ranked = await this.store.rankChunksByIndex({
@@ -3017,11 +5519,21 @@ export class RetrievalCore {
                     .map((candidate) => {
                     let score = candidate.score;
                     score += pathQualityBias(candidate.path, queryTokens, this.scoringConfig, query);
+                    const literalBoost = applyLiteralBoost({
+                        path: candidate.path,
+                        snippet: candidate.snippet,
+                        literals: searchLiterals,
+                        path_bias: this.scoringConfig.path_bias
+                    });
+                    score += literalBoost.boost;
+                    literalPathMatchCount += literalBoost.path_matches;
+                    literalSnippetMatchCount += literalBoost.snippet_matches;
                     if (looksLowInformation(candidate.snippet)) {
                         score -= this.scoringConfig.rerank.low_information_penalty;
                     }
                     const reason = chooseReason({
                         lexical: candidate.lexical_score,
+                        literal_match: literalBoost.matched,
                         path_match: candidate.path_match,
                         recency_boosted: candidate.recency_boosted
                     });
@@ -3059,10 +5571,24 @@ export class RetrievalCore {
                         score -= candidateWeights.generated_penalty;
                     }
                     score += pathQualityBias(chunk.path, queryTokens, this.scoringConfig, query);
+                    const literalBoost = applyLiteralBoost({
+                        path: chunk.path,
+                        snippet: chunk.snippet,
+                        literals: searchLiterals,
+                        path_bias: this.scoringConfig.path_bias
+                    });
+                    score += literalBoost.boost;
+                    literalPathMatchCount += literalBoost.path_matches;
+                    literalSnippetMatchCount += literalBoost.snippet_matches;
                     if (looksLowInformation(chunk.snippet)) {
                         score -= this.scoringConfig.rerank.low_information_penalty;
                     }
-                    const reason = chooseReason({ lexical: l, path_match: pathMatch, recency_boosted: recencyBoost });
+                    const reason = chooseReason({
+                        lexical: l,
+                        literal_match: literalBoost.matched,
+                        path_match: pathMatch,
+                        recency_boosted: recencyBoost
+                    });
                     return {
                         path: chunk.path,
                         start_line: chunk.start_line,
@@ -3078,18 +5604,59 @@ export class RetrievalCore {
                 channel: "hybrid",
                 retrieval_profile_id: this.scoringProfileId
             });
+            this.observability.metrics.observe("retrieval_candidates_pre_rerank_count", output.length, {
+                retrieval_profile_id: this.scoringProfileId
+            });
+            if (literalPathMatchCount > 0) {
+                this.observability.metrics.increment("retrieval_literal_boost_applied_total", literalPathMatchCount, {
+                    retrieval_profile_id: this.scoringProfileId,
+                    channel: "path"
+                });
+            }
+            if (literalSnippetMatchCount > 0) {
+                this.observability.metrics.increment("retrieval_literal_boost_applied_total", literalSnippetMatchCount, {
+                    retrieval_profile_id: this.scoringProfileId,
+                    channel: "snippet"
+                });
+            }
             return output;
         });
+        const rerankedCandidates = await this.observability.tracing.withSpan("retrieval.learned_rerank", { trace_id: input.trace_id }, async () => this.applyLearnedReranker({
+            trace_id: input.trace_id,
+            query,
+            candidates
+        }));
+        const consolidatedCandidates = await this.observability.tracing.withSpan("retrieval.overlap_merge", { trace_id: input.trace_id }, async () => mergeOverlappingCandidates(rerankedCandidates, this.scoringConfig.rerank));
+        this.observability.metrics.observe("retrieval_candidates_post_overlap_merge_count", consolidatedCandidates.length, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        const mergedCandidateCount = Math.max(0, rerankedCandidates.length - consolidatedCandidates.length);
+        if (mergedCandidateCount > 0) {
+            this.observability.metrics.increment("retrieval_overlap_candidates_merged_total", mergedCandidateCount, {
+                retrieval_profile_id: this.scoringProfileId
+            });
+        }
+        const cutoffCandidates = await this.observability.tracing.withSpan("retrieval.smart_cutoff", { trace_id: input.trace_id }, async () => applySmartCutoffCandidates(consolidatedCandidates, this.scoringConfig.rerank));
+        if (this.scoringConfig.rerank.smart_cutoff_enabled) {
+            this.observability.metrics.increment("retrieval_smart_cutoff_applied_total", 1, {
+                retrieval_profile_id: this.scoringProfileId
+            });
+            const droppedCount = Math.max(0, consolidatedCandidates.length - cutoffCandidates.length);
+            this.observability.metrics.increment("retrieval_smart_cutoff_drop_count", droppedCount, {
+                retrieval_profile_id: this.scoringProfileId
+            });
+        }
         const deduped = await this.observability.tracing.withSpan("retrieval.rerank", { trace_id: input.trace_id }, async () => {
             const output = [];
             const seen = new Set();
             const pathCounts = new Map();
+            const selectedRangesByPath = new Map();
             const directoryCounts = new Map();
             const extensionCounts = new Map();
             const maxChunksPerPath = hasFileLookupIntent(queryTokens)
                 ? this.scoringConfig.rerank.max_chunks_per_path_file_lookup
                 : this.scoringConfig.rerank.max_chunks_per_path_default;
-            const available = [...candidates];
+            const available = [...cutoffCandidates];
             while (output.length < topK && available.length > 0) {
                 let bestIndex = -1;
                 let bestAdjustedScore = Number.NEGATIVE_INFINITY;
@@ -3107,6 +5674,12 @@ export class RetrievalCore {
                     if (pathCount >= maxChunksPerPath) {
                         continue;
                     }
+                    if (this.scoringConfig.rerank.merge_overlapping_chunks_enabled && pathCount > 0) {
+                        const selectedRanges = selectedRangesByPath.get(candidate.path) ?? [];
+                        if (isHeavilyOverlappingLineRange(candidate, selectedRanges)) {
+                            continue;
+                        }
+                    }
                     const directoryKey = parentDirectory(candidate.path).toLowerCase();
                     const extensionKey = fileExtension(candidate.path);
                     const adjustedScore = candidate.score -
@@ -3139,6 +5712,13 @@ export class RetrievalCore {
                 const selectedKey = `${selected.path}:${selected.start_line}:${selected.end_line}`;
                 seen.add(selectedKey);
                 pathCounts.set(selected.path, (pathCounts.get(selected.path) ?? 0) + 1);
+                const selectedRanges = selectedRangesByPath.get(selected.path);
+                if (selectedRanges) {
+                    selectedRanges.push({ start_line: selected.start_line, end_line: selected.end_line });
+                }
+                else {
+                    selectedRangesByPath.set(selected.path, [{ start_line: selected.start_line, end_line: selected.end_line }]);
+                }
                 const selectedDirectory = parentDirectory(selected.path).toLowerCase();
                 const selectedExtension = fileExtension(selected.path);
                 directoryCounts.set(selectedDirectory, (directoryCounts.get(selectedDirectory) ?? 0) + 1);
@@ -3147,16 +5727,61 @@ export class RetrievalCore {
             }
             return output;
         });
+        const candidateRankByKey = new Map();
+        for (let index = 0; index < cutoffCandidates.length; index += 1) {
+            const candidate = cutoffCandidates[index];
+            if (!candidate) {
+                continue;
+            }
+            const key = `${candidate.path}:${candidate.start_line}:${candidate.end_line}`;
+            if (!candidateRankByKey.has(key)) {
+                candidateRankByKey.set(key, index + 1);
+            }
+        }
+        let literalMatchesInTopK = 0;
+        for (let postRank = 0; postRank < deduped.length; postRank += 1) {
+            const row = deduped[postRank];
+            if (!row) {
+                continue;
+            }
+            if (isExactLiteralReason(row.reason)) {
+                literalMatchesInTopK += 1;
+            }
+            this.observability.metrics.increment("retrieval_reason_topk_total", 1, {
+                retrieval_profile_id: this.scoringProfileId,
+                reason: row.reason
+            });
+            const key = `${row.path}:${row.start_line}:${row.end_line}`;
+            const preRank = candidateRankByKey.get(key) ?? postRank + 1;
+            this.observability.metrics.observe("retrieval_rank_shift_delta", preRank - (postRank + 1), {
+                retrieval_profile_id: this.scoringProfileId
+            });
+        }
+        this.observability.metrics.observe("retrieval_literal_matches_topk", literalMatchesInTopK, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        const packedResults = packSearchResultsWithContext({
+            selected: deduped,
+            sourceCandidates: cutoffCandidates,
+            config: this.contextPackingConfig
+        });
+        const assembledResults = annotateSearchResultsWithSnippetIntegrity({
+            selected: packedResults,
+            sourceCandidates: cutoffCandidates,
+            config: this.snippetIntegrityConfig,
+            observability: this.observability,
+            retrievalProfileId: this.scoringProfileId
+        });
         const output = {
             trace_id: input.trace_id,
-            results: deduped,
+            results: assembledResults,
             search_metadata: {
                 latency_ms: Date.now() - searchStartedAt,
                 retrieval_mode: "hybrid",
                 index_version: index.index_version
             }
         };
-        this.observability.metrics.observe("retrieval_topk_hit_proxy", deduped.length > 0 ? 1 : 0, {
+        this.observability.metrics.observe("retrieval_topk_hit_proxy", assembledResults.length > 0 ? 1 : 0, {
             retrieval_profile_id: this.scoringProfileId
         });
         this.observability.logger.info("search_context completed", {
@@ -3171,18 +5796,117 @@ export class RetrievalCore {
         await this.cache.set(cacheKey, output, this.cacheTtlSeconds);
         return output;
     }
+    enhancerProviderLabels() {
+        return {
+            provider: this.enhancerProviderDescriptor?.provider ?? "template",
+            model: this.enhancerProviderDescriptor?.model ?? "n/a",
+            tool_mode: this.enhancerGenerationConfig.tool_mode
+        };
+    }
+    buildEnhancerContextSnippets(results) {
+        const maxSnippets = this.enhancerGenerationConfig.max_context_snippets;
+        const snippetCharLimit = this.contextPackingConfig.enabled ? this.contextPackingConfig.enhancer_snippet_char_limit : 1_600;
+        const snippets = [];
+        for (const result of results.slice(0, maxSnippets)) {
+            snippets.push({
+                path: result.path,
+                start_line: result.start_line,
+                end_line: result.end_line,
+                reason: result.reason,
+                snippet: result.snippet.slice(0, snippetCharLimit),
+                score: result.score
+            });
+        }
+        return snippets;
+    }
+    async generateEnhancedPrompt(input) {
+        if (!this.enhancerProvider) {
+            return formatEnhancedPrompt({
+                style: input.style_resolved,
+                language: input.language,
+                original_prompt: input.request.prompt,
+                refs: input.context_refs
+            });
+        }
+        const maxAttempts = this.enhancerGenerationConfig.max_retries + 1;
+        let lastFailure;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            const startedAt = Date.now();
+            this.observability.metrics.increment("enhancer_provider_requests_total", 1, this.enhancerProviderLabels());
+            try {
+                const generated = await runWithInactivityTimeout({
+                    timeout_ms: this.enhancerGenerationConfig.timeout_ms,
+                    fn: ({ touch, signal }) => this.enhancerProvider.generate({
+                        trace_id: input.trace_id,
+                        tenant_id: input.tenant_id,
+                        workspace_id: input.workspace_id,
+                        request: input.request,
+                        style_requested: input.style_requested,
+                        style_resolved: input.style_resolved,
+                        intent: input.intent,
+                        query_intent: input.query_intent,
+                        language: input.language,
+                        context_refs: input.context_refs,
+                        context_snippets: input.context_snippets,
+                        warnings: input.warnings,
+                        questions: input.questions,
+                        tool_mode: this.enhancerGenerationConfig.tool_mode,
+                        abort_signal: signal,
+                        on_progress: touch
+                    })
+                });
+                this.observability.metrics.observe("enhancer_provider_latency_ms", Date.now() - startedAt, this.enhancerProviderLabels());
+                const enhancedPrompt = normalizeProviderEnhancedPrompt(generated.enhanced_prompt);
+                if (enhancedPrompt.length === 0) {
+                    throw new EnhancerProviderRequestError("invalid_response", "enhancer provider returned an empty enhanced_prompt");
+                }
+                return enhancedPrompt;
+            }
+            catch (error) {
+                const reason = classifyEnhancerGenerationFailureReason(error);
+                const failure = error instanceof EnhancerProviderRequestError ? error : new EnhancerProviderRequestError(reason, String(error));
+                lastFailure = failure;
+                this.observability.metrics.increment("enhancer_provider_failures_total", 1, {
+                    ...this.enhancerProviderLabels(),
+                    reason
+                });
+                this.observability.logger.warn("enhancer provider generation failed", {
+                    trace_id: input.trace_id,
+                    attempt,
+                    max_attempts: maxAttempts,
+                    reason,
+                    retrying: attempt < maxAttempts &&
+                        reason !== "timeout" &&
+                        reason !== "schema_error" &&
+                        reason !== "invalid_response",
+                    style_requested: input.style_requested,
+                    style_resolved: input.style_resolved,
+                    provider: this.enhancerProviderDescriptor?.provider ?? "custom",
+                    model: this.enhancerProviderDescriptor?.model ?? "unknown",
+                    error: failure.message
+                });
+                if (reason === "timeout" || reason === "schema_error" || reason === "invalid_response") {
+                    break;
+                }
+            }
+        }
+        const message = lastFailure?.message ?? "enhancer provider failed";
+        throw new RetrievalError("UPSTREAM_FAILURE", `enhancer provider failed after retries: ${message}`);
+    }
     async enhancePrompt(input) {
         const startedAt = Date.now();
         const warnings = [];
-        const questions = [];
-        const addQuestion = (value) => {
-            if (!questions.includes(value)) {
-                questions.push(value);
-            }
-        };
         const intent = classifyIntent(input.request.prompt);
         const queryIntent = classifyEnhancerQueryIntent(input.request.prompt, input.request.conversation_history);
         const language = detectDominantLanguage(input.request.prompt, input.request.conversation_history);
+        const style = resolveEnhancerPromptStyle({
+            requested: input.request.style,
+            intent,
+            query_intent: queryIntent,
+            prompt: input.request.prompt,
+            history: input.request.conversation_history,
+            has_context: Boolean(input.request.project_root_path && input.workspace_id)
+        });
         const negativePreferences = detectNegativePathPreferences(`${input.request.prompt}\n${input.request.conversation_history.map((entry) => entry.content).join("\n")}`);
         const intentPolicy = resolveEnhancerIntentPolicy({
             query_intent: queryIntent,
@@ -3230,7 +5954,7 @@ export class RetrievalCore {
                         top_k: MAX_TOP_K
                     }
                 });
-                const budgetedResults = trimToContextBudget(retrieval.results);
+                const budgetedResults = trimToContextBudget(retrieval.results, this.contextPackingConfig.enabled ? "lightweight" : "ranking");
                 const dedupedByPath = dedupeEnhancerCandidatesByPath(budgetedResults);
                 const collapsedByDirectory = collapseEnhancerCandidatesByDirectory(dedupedByPath, intentPolicy.max_candidates_per_directory_pre_rerank);
                 const filteredCandidates = applyEnhancerIntentPathFiltering(collapsedByDirectory, {
@@ -3292,16 +6016,6 @@ export class RetrievalCore {
                         strict_impl_only_filtering: intentPolicy.strict_impl_only_filtering
                     }));
                     searchResults = collapseEnhancerCandidatesByDirectory(searchResults, intentPolicy.max_candidates_per_directory_pre_rerank).slice(0, intentPolicy.max_candidates_pre_rerank);
-                    const symbolCandidates = extractLikelyCodeSymbols(`${input.request.prompt}\n${input.request.conversation_history.map((entry) => entry.content).join("\n")}`, 3);
-                    if (confidenceSignals.failed_signals.includes("score_spread")) {
-                        addQuestion(localizeLowConfidenceQuestion({ language, kind: "scope" }));
-                    }
-                    if (confidenceSignals.failed_signals.includes("token_overlap")) {
-                        addQuestion(localizeLowConfidenceQuestion({ language, kind: "symbol", symbol: symbolCandidates[0] }));
-                    }
-                    if (confidenceSignals.failed_signals.includes("path_diversity")) {
-                        addQuestion(localizeLowConfidenceQuestion({ language, kind: "source_priority" }));
-                    }
                 }
                 else {
                     searchResults = dedupeEnhancerCandidatesByPath(searchResults);
@@ -3310,6 +6024,9 @@ export class RetrievalCore {
                 candidateCountPostRerank = searchResults.length;
             }
             catch (error) {
+                if (error instanceof RetrievalError && error.code === "RATE_LIMITED") {
+                    throw error;
+                }
                 warnings.push("Context retrieval unavailable; enhancement generated with limited confidence.");
                 fallbackTriggered = true;
                 fallbackReason = "context_retrieval_unavailable";
@@ -3319,31 +6036,34 @@ export class RetrievalCore {
                 }
             }
         }
-        if (intent === "unknown") {
-            addQuestion(language === "es"
-                ? "¿Cuál es el resultado esperado exacto y el alcance del cambio?"
-                : language === "zh"
-                    ? "这次变更的精确目标和范围是什么？"
-                    : "What exact outcome and scope should this change target?");
-        }
         const contextRefs = searchResults.map((result) => ({
             path: result.path,
             start_line: result.start_line,
             end_line: result.end_line,
             reason: result.reason
         }));
-        const enhancedPrompt = formatEnhancedPrompt({
+        const contextSnippets = this.buildEnhancerContextSnippets(searchResults);
+        const enhancedPrompt = await this.generateEnhancedPrompt({
+            trace_id: input.trace_id,
+            tenant_id: input.tenant_id,
+            workspace_id: input.workspace_id,
+            request: input.request,
+            style_requested: style.requested,
+            style_resolved: style.resolved,
             intent,
+            query_intent: queryIntent,
             language,
-            original_prompt: input.request.prompt,
-            refs: contextRefs
+            context_refs: contextRefs,
+            context_snippets: contextSnippets,
+            warnings: [],
+            questions: []
         });
         const output = {
             trace_id: input.trace_id,
             enhanced_prompt: enhancedPrompt,
             context_refs: contextRefs,
-            warnings,
-            questions
+            warnings: [],
+            questions: []
         };
         const latency_ms = Date.now() - startedAt;
         this.observability.metrics.observe("enhancer_latency_ms", latency_ms, {});
@@ -3392,6 +6112,11 @@ export class RetrievalCore {
             fallback_triggered: fallbackTriggered,
             fallback_reason: fallbackReason,
             query_intent: queryIntent,
+            style_requested: style.requested,
+            style_resolved: style.resolved,
+            enhancer_provider: this.enhancerProviderDescriptor?.provider ?? "template",
+            enhancer_model: this.enhancerProviderDescriptor?.model ?? null,
+            enhancer_tool_mode: this.enhancerGenerationConfig.tool_mode,
             confidence_score_spread: confidenceSignals?.score_spread ?? null,
             confidence_token_overlap: confidenceSignals?.token_overlap ?? null,
             confidence_path_diversity: confidenceSignals?.path_diversity ?? null,