@rce-mcp/retrieval-core 0.1.0

package/dist/index.js

@@ -0,0 +1,3417 @@
+import { createHash, randomUUID } from "node:crypto";
+import { buildQueryCacheKey } 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 MAX_TOP_K = 20;
+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";
+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;
+const DEFAULT_CANDIDATE_SCORE_WEIGHTS = {
+    lexical_weight: 0.6,
+    vector_weight: 0.4,
+    path_match_boost: 0.2,
+    recency_boost: 0.1,
+    generated_penalty: 0.2
+};
+export const BASELINE_RETRIEVAL_SCORING_CONFIG = {
+    candidate_weights: { ...DEFAULT_CANDIDATE_SCORE_WEIGHTS },
+    path_bias: {
+        source_path_boost: 0.12,
+        low_priority_prefix_penalty: 0.15,
+        low_priority_substring_penalty: 0.15,
+        low_priority_asset_penalty: 0.2,
+        lockfile_penalty: 0.2,
+        doc_intent_docs_boost: 0.18,
+        doc_intent_markdown_boost: 0.08,
+        docs_without_doc_intent_penalty: 0.2,
+        non_doc_markdown_penalty: 0.15,
+        code_intent_docs_penalty: 0.08,
+        doc_intent_source_penalty: 0.08,
+        workspace_manifest_root_boost: 0.26,
+        workspace_manifest_nested_boost: 0.16,
+        ui_component_tsx_boost: 0.18,
+        ui_component_css_penalty: 0.2,
+        docs_archive_penalty: 0.15,
+        public_path_penalty: 0.08,
+        test_path_penalty: 0.35,
+        example_path_penalty: 0.2,
+        declaration_file_penalty: 0.12,
+        test_intent_test_boost: 0.08,
+        example_intent_example_boost: 0.06,
+        filename_token_match_boost: 0.06,
+        negation_avoid_docs_penalty: 0.35,
+        negation_avoid_tests_penalty: 0.35,
+        negation_avoid_examples_penalty: 0.3,
+        negation_avoid_archive_penalty: 0.35,
+        min_total_bias: -0.45,
+        max_total_bias: 0.35
+    },
+    rerank: {
+        low_information_penalty: 0.15,
+        max_chunks_per_path_default: 2,
+        max_chunks_per_path_file_lookup: 1,
+        same_directory_penalty: 0,
+        same_extension_penalty: 0
+    }
+};
+export const CONSERVATIVE_RETRIEVAL_SCORING_CONFIG = {
+    candidate_weights: {
+        lexical_weight: 0.55,
+        vector_weight: 0.45,
+        path_match_boost: 0.1,
+        recency_boost: 0.05,
+        generated_penalty: 0.15
+    },
+    path_bias: {
+        source_path_boost: 0.08,
+        low_priority_prefix_penalty: 0.08,
+        low_priority_substring_penalty: 0.08,
+        low_priority_asset_penalty: 0.12,
+        lockfile_penalty: 0.12,
+        doc_intent_docs_boost: 0.1,
+        doc_intent_markdown_boost: 0.05,
+        docs_without_doc_intent_penalty: 0.08,
+        non_doc_markdown_penalty: 0.08,
+        code_intent_docs_penalty: 0.05,
+        doc_intent_source_penalty: 0.05,
+        workspace_manifest_root_boost: 0.14,
+        workspace_manifest_nested_boost: 0.1,
+        ui_component_tsx_boost: 0.1,
+        ui_component_css_penalty: 0.1,
+        docs_archive_penalty: 0.1,
+        public_path_penalty: 0.05,
+        test_path_penalty: 0.12,
+        example_path_penalty: 0.06,
+        declaration_file_penalty: 0.08,
+        test_intent_test_boost: 0.04,
+        example_intent_example_boost: 0.04,
+        filename_token_match_boost: 0.04,
+        negation_avoid_docs_penalty: 0.2,
+        negation_avoid_tests_penalty: 0.2,
+        negation_avoid_examples_penalty: 0.16,
+        negation_avoid_archive_penalty: 0.2,
+        min_total_bias: -0.25,
+        max_total_bias: 0.2
+    },
+    rerank: {
+        low_information_penalty: 0.1,
+        max_chunks_per_path_default: 2,
+        max_chunks_per_path_file_lookup: 1,
+        same_directory_penalty: 0,
+        same_extension_penalty: 0
+    }
+};
+export const DEFAULT_RETRIEVAL_ENHANCER_CONFIG = {
+    max_expansion_hints: 24,
+    max_candidates_pre_rerank: 4,
+    rerank_timeout_ms: 40
+};
+export const DEFAULT_RETRIEVAL_CHUNKING_CONFIG = {
+    strategy: "sliding",
+    fallback_strategy: "sliding",
+    parse_timeout_ms: 80,
+    enabled_languages: ["typescript", "javascript", "python", "go"]
+};
+const BUILTIN_RETRIEVAL_SCORING_PROFILES = {
+    baseline: BASELINE_RETRIEVAL_SCORING_CONFIG,
+    conservative: CONSERVATIVE_RETRIEVAL_SCORING_CONFIG
+};
+function deepCloneScoringConfig(config) {
+    return {
+        candidate_weights: { ...config.candidate_weights },
+        path_bias: { ...config.path_bias },
+        rerank: { ...config.rerank }
+    };
+}
+function assertFiniteNumber(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`invalid retrieval scoring config: ${label} must be a finite number`);
+    }
+    return value;
+}
+function validateScoringConfig(config) {
+    const weights = config.candidate_weights;
+    const pathBias = config.path_bias;
+    const rerank = config.rerank;
+    assertFiniteNumber(weights.lexical_weight, "candidate_weights.lexical_weight");
+    assertFiniteNumber(weights.vector_weight, "candidate_weights.vector_weight");
+    assertFiniteNumber(weights.path_match_boost, "candidate_weights.path_match_boost");
+    assertFiniteNumber(weights.recency_boost, "candidate_weights.recency_boost");
+    assertFiniteNumber(weights.generated_penalty, "candidate_weights.generated_penalty");
+    const weightSum = weights.lexical_weight + weights.vector_weight;
+    if (Math.abs(weightSum - 1) > 0.001) {
+        throw new Error("invalid retrieval scoring config: lexical_weight + vector_weight must equal 1");
+    }
+    for (const [key, value] of Object.entries(pathBias)) {
+        assertFiniteNumber(value, `path_bias.${key}`);
+    }
+    if (pathBias.min_total_bias > pathBias.max_total_bias) {
+        throw new Error("invalid retrieval scoring config: path_bias.min_total_bias must be <= max_total_bias");
+    }
+    assertFiniteNumber(rerank.low_information_penalty, "rerank.low_information_penalty");
+    if (!Number.isInteger(rerank.max_chunks_per_path_default) || rerank.max_chunks_per_path_default <= 0) {
+        throw new Error("invalid retrieval scoring config: rerank.max_chunks_per_path_default must be a positive integer");
+    }
+    if (!Number.isInteger(rerank.max_chunks_per_path_file_lookup) || rerank.max_chunks_per_path_file_lookup <= 0) {
+        throw new Error("invalid retrieval scoring config: rerank.max_chunks_per_path_file_lookup must be a positive integer");
+    }
+    assertFiniteNumber(rerank.same_directory_penalty, "rerank.same_directory_penalty");
+    assertFiniteNumber(rerank.same_extension_penalty, "rerank.same_extension_penalty");
+    if (rerank.same_directory_penalty < 0) {
+        throw new Error("invalid retrieval scoring config: rerank.same_directory_penalty must be >= 0");
+    }
+    if (rerank.same_extension_penalty < 0) {
+        throw new Error("invalid retrieval scoring config: rerank.same_extension_penalty must be >= 0");
+    }
+}
+export function resolveRetrievalScoringProfile(profile_id) {
+    const normalized = (profile_id ?? "baseline").trim().toLowerCase();
+    if (!(normalized in BUILTIN_RETRIEVAL_SCORING_PROFILES)) {
+        throw new Error(`unknown retrieval scoring profile "${profile_id ?? ""}". Expected one of: ${Object.keys(BUILTIN_RETRIEVAL_SCORING_PROFILES).join(", ")}`);
+    }
+    return {
+        profile_id: normalized,
+        config: deepCloneScoringConfig(BUILTIN_RETRIEVAL_SCORING_PROFILES[normalized])
+    };
+}
+export function mergeRetrievalScoringConfig(base, overrides) {
+    const next = deepCloneScoringConfig(base);
+    if (overrides?.candidate_weights) {
+        next.candidate_weights = {
+            ...next.candidate_weights,
+            ...overrides.candidate_weights
+        };
+    }
+    if (overrides?.path_bias) {
+        next.path_bias = {
+            ...next.path_bias,
+            ...overrides.path_bias
+        };
+    }
+    if (overrides?.rerank) {
+        next.rerank = {
+            ...next.rerank,
+            ...overrides.rerank
+        };
+    }
+    validateScoringConfig(next);
+    return next;
+}
+function validateEnhancerConfig(config) {
+    if (!Number.isInteger(config.max_expansion_hints) || config.max_expansion_hints <= 0) {
+        throw new Error("invalid retrieval enhancer config: max_expansion_hints must be a positive integer");
+    }
+    if (!Number.isInteger(config.max_candidates_pre_rerank) || config.max_candidates_pre_rerank <= 0) {
+        throw new Error("invalid retrieval enhancer config: max_candidates_pre_rerank must be a positive integer");
+    }
+    if (!Number.isInteger(config.rerank_timeout_ms) || config.rerank_timeout_ms <= 0) {
+        throw new Error("invalid retrieval enhancer config: rerank_timeout_ms must be a positive integer");
+    }
+}
+export function mergeRetrievalEnhancerConfig(base, overrides) {
+    const next = {
+        ...base,
+        ...(overrides ?? {})
+    };
+    validateEnhancerConfig(next);
+    return next;
+}
+function normalizeChunkingLanguageList(value) {
+    const deduped = new Set();
+    for (const language of value) {
+        const normalized = language.trim().toLowerCase();
+        if (normalized.length === 0) {
+            continue;
+        }
+        deduped.add(normalized);
+    }
+    return [...deduped];
+}
+function validateChunkingConfig(config) {
+    if (!["language_aware", "sliding"].includes(config.strategy)) {
+        throw new Error("invalid retrieval chunking config: strategy must be language_aware|sliding");
+    }
+    if (config.fallback_strategy !== "sliding") {
+        throw new Error("invalid retrieval chunking config: fallback_strategy must be sliding");
+    }
+    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 (!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");
+    }
+    for (const language of config.enabled_languages) {
+        if (typeof language !== "string" || language.trim().length === 0) {
+            throw new Error("invalid retrieval chunking config: enabled_languages must contain non-empty strings");
+        }
+    }
+}
+export function mergeRetrievalChunkingConfig(base, overrides) {
+    const next = {
+        ...base,
+        ...(overrides ?? {}),
+        enabled_languages: normalizeChunkingLanguageList(overrides?.enabled_languages ?? base.enabled_languages)
+    };
+    validateChunkingConfig(next);
+    return next;
+}
+function stableSerialize(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableSerialize(entry)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableSerialize(v)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function scoringConfigChecksum(config) {
+    return sha256(stableSerialize(config)).slice(0, 12);
+}
+const REASON_STRINGS = [
+    "semantic match",
+    "exact symbol match",
+    "path and token overlap",
+    "recently modified relevant module"
+];
+export class RetrievalError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+class EmbeddingProviderRequestError extends Error {
+    reason;
+    retryable;
+    constructor(reason, retryable, message) {
+        super(message);
+        this.reason = reason;
+        this.retryable = retryable;
+    }
+}
+const SECRET_PATTERNS = [
+    { label: "aws_access_key", pattern: /AKIA[0-9A-Z]{16}/g },
+    { label: "private_key", pattern: /-----BEGIN (?:RSA|EC|OPENSSH) PRIVATE KEY-----/g },
+    { label: "generic_secret_key", pattern: /(?:api|secret|access)[_-]?key\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}["']?/gi },
+    { label: "bearer_token", pattern: /Bearer\s+[A-Za-z0-9._\-]{10,}/gi }
+];
+function normalizePath(path) {
+    return path.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^\.\//, "").trim();
+}
+function normalizeQuery(query) {
+    return query.normalize("NFKC").trim();
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function pluralizeToken(token) {
+    if (!/^[a-z][a-z0-9]{2,}$/.test(token)) {
+        return undefined;
+    }
+    if (token.endsWith("s")) {
+        return undefined;
+    }
+    if (token.endsWith("y") && token.length > 3) {
+        return `${token.slice(0, -1)}ies`;
+    }
+    return `${token}s`;
+}
+function singularizeToken(token) {
+    if (!/^[a-z][a-z0-9]{2,}$/.test(token)) {
+        return undefined;
+    }
+    if (token.endsWith("ies") && token.length > 4) {
+        return `${token.slice(0, -3)}y`;
+    }
+    if (token.endsWith("es") && token.length > 4) {
+        return token.slice(0, -2);
+    }
+    if (token.endsWith("s") && !token.endsWith("ss") && token.length > 3) {
+        return token.slice(0, -1);
+    }
+    return undefined;
+}
+function tokenize(text) {
+    const coarseTokens = text
+        .split(/[^a-z0-9_./-]+/)
+        .map((token) => token.trim())
+        .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);
+            }
+        }
+    }
+    return [...expandedTokens];
+}
+function lexicalScore(query, haystack) {
+    const q = new Set(tokenize(query));
+    if (q.size === 0) {
+        return 0;
+    }
+    const h = new Set(tokenize(haystack));
+    let overlap = 0;
+    for (const token of q) {
+        if (h.has(token)) {
+            overlap += 1;
+        }
+    }
+    return overlap / q.size;
+}
+function cosineSimilarity(a, b) {
+    if (a.length === 0 || b.length === 0) {
+        return 0;
+    }
+    const max = Math.min(a.length, b.length);
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < max; i += 1) {
+        dot += (a[i] ?? 0) * (b[i] ?? 0);
+        normA += (a[i] ?? 0) * (a[i] ?? 0);
+        normB += (b[i] ?? 0) * (b[i] ?? 0);
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+function looksLowInformation(snippet) {
+    const trimmed = snippet.trim();
+    if (trimmed.length < 12) {
+        return true;
+    }
+    const noWhitespace = trimmed.replace(/\s+/g, "");
+    return /^(.)\1+$/.test(noWhitespace);
+}
+function chooseReason(input) {
+    if (input.path_match) {
+        return "exact symbol match";
+    }
+    if (input.recency_boosted) {
+        return "recently modified relevant module";
+    }
+    if (input.lexical > 0.3) {
+        return "path and token overlap";
+    }
+    return "semantic match";
+}
+const DOC_INTENT_TOKENS = new Set([
+    "adr",
+    "architecture",
+    "design",
+    "doc",
+    "docs",
+    "documentation",
+    "milestone",
+    "readme",
+    "spec",
+    "specification"
+]);
+const CODE_INTENT_TOKENS = new Set([
+    "api",
+    "bug",
+    "bugfix",
+    "cli",
+    "code",
+    "command",
+    "component",
+    "error",
+    "entrypoint",
+    "feature",
+    "fix",
+    "function",
+    "handler",
+    "harden",
+    "hook",
+    "hooks",
+    "implement",
+    "implementation",
+    "middleware",
+    "module",
+    "optimize",
+    "pipeline",
+    "react",
+    "refactor",
+    "root",
+    "route",
+    "routing",
+    "source",
+    "struct",
+    "ts",
+    "type",
+    "typescript",
+    "tsx",
+    "ui"
+]);
+const WORKSPACE_MANIFEST_TOKENS = new Set(["cargo", "members", "resolver", "workspace", "rust"]);
+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 SOURCE_PATH_PREFIXES = ["src/", "app/", "apps/", "crates/", "internal/", "lib/", "package/", "packages/"];
+const LOW_PRIORITY_PATH_PREFIXES = [
+    ".next/",
+    ".nuxt/",
+    ".svelte-kit/",
+    "build/",
+    "coverage/",
+    "dist/",
+    "node_modules/",
+    "out/",
+    "target/"
+];
+const LOW_PRIORITY_PATH_SUBSTRINGS = ["/docs/_archive/", "/node_modules/", "/target/"];
+const LOW_PRIORITY_ASSET_EXTENSIONS = [".gif", ".ico", ".jpeg", ".jpg", ".pdf", ".png", ".svg", ".webp"];
+const LOW_PRIORITY_LOCK_FILES = [
+    "bun.lock",
+    "bun.lockb",
+    "cargo.lock",
+    "composer.lock",
+    "gemfile.lock",
+    "package-lock.json",
+    "pipfile.lock",
+    "pnpm-lock.yaml",
+    "yarn.lock"
+];
+function hasNegationNearTarget(normalized, targetPattern) {
+    const negationPrefix = "(?:avoid|avoiding|exclude|excluding|without|skip|omit|ignore|deprioriti(?:s|z)e|not|no|leave\\s+out|keep\\s+[^\\n]{0,40}?\\s+out\\s+of)";
+    return (new RegExp(`\\b${negationPrefix}\\b[^\\n,.!?;]{0,48}\\b(?:${targetPattern})\\b`, "i").test(normalized) ||
+        new RegExp(`\\b(?:${targetPattern})\\b[^\\n,.!?;]{0,24}\\b(?:not|avoid|exclude|without|skip|omit)\\b`, "i").test(normalized));
+}
+function detectNegativePathPreferences(query) {
+    const normalized = query.toLowerCase();
+    return {
+        avoid_docs: hasNegationNearTarget(normalized, "docs?|documentation|readme|specs?|guides?|markdown"),
+        avoid_tests: hasNegationNearTarget(normalized, "tests?|specs?|fixtures?|__tests__"),
+        avoid_examples: hasNegationNearTarget(normalized, "examples?|samples?|demos?|tutorials?"),
+        avoid_archive: hasNegationNearTarget(normalized, "archive|archived|_archive")
+    };
+}
+function hasDocIntent(tokens) {
+    return tokens.some((token) => DOC_INTENT_TOKENS.has(token));
+}
+function hasCodeIntent(tokens) {
+    return tokens.some((token) => CODE_INTENT_TOKENS.has(token));
+}
+function hasWorkspaceManifestIntent(tokens) {
+    return tokens.some((token) => WORKSPACE_MANIFEST_TOKENS.has(token));
+}
+function hasUiComponentIntent(tokens) {
+    return tokens.some((token) => UI_COMPONENT_TOKENS.has(token));
+}
+function hasFileLookupIntent(tokens) {
+    return tokens.some((token) => FILE_LOOKUP_TOKENS.has(token));
+}
+function hasTestIntent(tokens) {
+    return tokens.some((token) => TEST_INTENT_TOKENS.has(token));
+}
+function hasExampleIntent(tokens) {
+    return tokens.some((token) => EXAMPLE_INTENT_TOKENS.has(token));
+}
+function pathQualityBias(path, queryTokens, config, queryText) {
+    const normalizedPath = path.toLowerCase();
+    const docIntent = hasDocIntent(queryTokens);
+    const codeIntent = hasCodeIntent(queryTokens);
+    const docsPreferred = docIntent && !codeIntent;
+    const negativePreferences = detectNegativePathPreferences(queryText ?? queryTokens.join(" "));
+    const workspaceManifestIntent = hasWorkspaceManifestIntent(queryTokens);
+    const uiComponentIntent = hasUiComponentIntent(queryTokens);
+    const testIntent = hasTestIntent(queryTokens);
+    const exampleIntent = hasExampleIntent(queryTokens);
+    let bias = 0;
+    const pathBias = config.path_bias;
+    const isSourcePath = SOURCE_PATH_PREFIXES.some((prefix) => normalizedPath.startsWith(prefix) || normalizedPath.includes(`/${prefix}`));
+    const isDocsPath = normalizedPath.startsWith("docs/") || normalizedPath.includes("/docs/");
+    const isMarkdown = normalizedPath.endsWith(".md");
+    const isTestPath = normalizedPath.startsWith("test/") ||
+        normalizedPath.startsWith("tests/") ||
+        normalizedPath.startsWith("__tests__/") ||
+        normalizedPath.includes("/test/") ||
+        normalizedPath.includes("/tests/") ||
+        normalizedPath.includes("/__tests__/") ||
+        normalizedPath.endsWith(".test.js") ||
+        normalizedPath.endsWith(".test.ts") ||
+        normalizedPath.endsWith(".spec.js") ||
+        normalizedPath.endsWith(".spec.ts");
+    const isExamplePath = normalizedPath.startsWith("example/") ||
+        normalizedPath.startsWith("examples/") ||
+        normalizedPath.includes("/example/") ||
+        normalizedPath.includes("/examples/");
+    const isLibPath = normalizedPath === "lib" || normalizedPath.startsWith("lib/") || normalizedPath.includes("/lib/");
+    const isChangelogLikeDoc = /(?:^|\/)(?:history|changelog|changes|readme)\.md$/.test(normalizedPath);
+    if (isSourcePath) {
+        bias += pathBias.source_path_boost;
+    }
+    if (codeIntent && isLibPath) {
+        bias += pathBias.source_path_boost;
+    }
+    if (LOW_PRIORITY_PATH_PREFIXES.some((prefix) => normalizedPath.startsWith(prefix))) {
+        bias -= pathBias.low_priority_prefix_penalty;
+    }
+    if (LOW_PRIORITY_PATH_SUBSTRINGS.some((pattern) => normalizedPath.includes(pattern))) {
+        bias -= pathBias.low_priority_substring_penalty;
+    }
+    if (LOW_PRIORITY_ASSET_EXTENSIONS.some((ext) => normalizedPath.endsWith(ext))) {
+        bias -= pathBias.low_priority_asset_penalty;
+    }
+    if (LOW_PRIORITY_LOCK_FILES.some((name) => normalizedPath.endsWith(name))) {
+        bias -= pathBias.lockfile_penalty;
+    }
+    if (docsPreferred && isDocsPath) {
+        bias += pathBias.doc_intent_docs_boost;
+    }
+    if (docsPreferred && isMarkdown) {
+        bias += pathBias.doc_intent_markdown_boost;
+    }
+    if (!docsPreferred && isDocsPath) {
+        bias -= pathBias.docs_without_doc_intent_penalty;
+    }
+    if (!docsPreferred && isMarkdown) {
+        bias -= pathBias.non_doc_markdown_penalty;
+    }
+    if (codeIntent && isDocsPath) {
+        bias -= pathBias.code_intent_docs_penalty;
+    }
+    if (codeIntent && isMarkdown) {
+        bias -= pathBias.non_doc_markdown_penalty;
+    }
+    if (codeIntent && isChangelogLikeDoc) {
+        bias -= pathBias.docs_without_doc_intent_penalty;
+    }
+    if (docsPreferred && isSourcePath) {
+        bias -= pathBias.doc_intent_source_penalty;
+    }
+    if (workspaceManifestIntent && normalizedPath === "cargo.toml") {
+        bias += pathBias.workspace_manifest_root_boost;
+    }
+    if (workspaceManifestIntent && normalizedPath.endsWith("/cargo.toml")) {
+        bias += pathBias.workspace_manifest_nested_boost;
+    }
+    if (uiComponentIntent && (normalizedPath.endsWith(".tsx") || normalizedPath.endsWith(".jsx"))) {
+        bias += pathBias.ui_component_tsx_boost;
+    }
+    if (uiComponentIntent && normalizedPath.endsWith(".css")) {
+        bias -= pathBias.ui_component_css_penalty;
+    }
+    if (normalizedPath.startsWith("docs/_archive/")) {
+        bias -= pathBias.docs_archive_penalty;
+    }
+    if (normalizedPath.includes("/public/") && !queryTokens.some((token) => token.includes("public"))) {
+        bias -= pathBias.public_path_penalty;
+    }
+    if (!testIntent && isTestPath) {
+        bias -= pathBias.test_path_penalty;
+    }
+    if (testIntent && isTestPath) {
+        bias += pathBias.test_intent_test_boost;
+    }
+    if (!exampleIntent && isExamplePath) {
+        bias -= pathBias.example_path_penalty;
+    }
+    if (exampleIntent && isExamplePath) {
+        bias += pathBias.example_intent_example_boost;
+    }
+    if (codeIntent && normalizedPath.endsWith(".d.ts")) {
+        bias -= pathBias.declaration_file_penalty;
+    }
+    if (negativePreferences.avoid_docs && (isDocsPath || isMarkdown)) {
+        bias -= pathBias.negation_avoid_docs_penalty;
+    }
+    if (negativePreferences.avoid_tests && isTestPath) {
+        bias -= pathBias.negation_avoid_tests_penalty;
+    }
+    if (negativePreferences.avoid_examples && isExamplePath) {
+        bias -= pathBias.negation_avoid_examples_penalty;
+    }
+    if (negativePreferences.avoid_archive && normalizedPath.includes("archive")) {
+        bias -= pathBias.negation_avoid_archive_penalty;
+    }
+    const filename = normalizedPath.split("/").pop() ?? normalizedPath;
+    const filenameStem = filename.replace(/\.[a-z0-9]+$/, "");
+    for (const token of queryTokens) {
+        if (token === filename || token === filenameStem) {
+            bias += pathBias.filename_token_match_boost;
+        }
+    }
+    return Math.max(pathBias.min_total_bias, Math.min(pathBias.max_total_bias, bias));
+}
+function buildChunks(file, chunkingConfig) {
+    const normalizedPath = normalizePath(file.path);
+    const chunkingResult = buildChunksForFile({
+        file: {
+            path: normalizedPath,
+            content: file.content,
+            language: file.language
+        },
+        config: {
+            strategy: chunkingConfig.strategy,
+            fallback_strategy: chunkingConfig.fallback_strategy,
+            target_chunk_tokens: TARGET_CHUNK_TOKENS,
+            chunk_overlap_tokens: CHUNK_OVERLAP_TOKENS,
+            max_chunks_per_file: MAX_CHUNKS_PER_FILE,
+            parse_timeout_ms: chunkingConfig.parse_timeout_ms,
+            enabled_languages: chunkingConfig.enabled_languages
+        },
+        tokenize
+    });
+    return {
+        chunks: chunkingResult.chunks.map((chunk) => ({
+            path: normalizedPath,
+            start_line: chunk.start_line,
+            end_line: chunk.end_line,
+            snippet: chunk.snippet,
+            language: file.language,
+            generated: file.generated,
+            updated_at: file.updated_at ?? new Date().toISOString(),
+            hash: sha256(`${normalizedPath}:${chunk.start_line}:${chunk.end_line}:${chunk.snippet}`)
+        })),
+        strategy: chunkingResult.strategy,
+        fallback_reason: chunkingResult.fallback_reason,
+        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
+    };
+}
+function pseudoEmbedding(input, dimensions = 24) {
+    const safeDimensions = Math.max(1, dimensions);
+    let source = sha256(input);
+    let salt = 1;
+    while (source.length < safeDimensions * 2) {
+        source += sha256(`${input}:${salt}`);
+        salt += 1;
+    }
+    const out = [];
+    for (let i = 0; i < safeDimensions; i += 1) {
+        const offset = i * 2;
+        const segment = source.slice(offset, offset + 2);
+        out.push(parseInt(segment, 16) / 255);
+    }
+    return out;
+}
+function isFiniteNumberArray(value) {
+    return Array.isArray(value) && value.every((cell) => typeof cell === "number" && Number.isFinite(cell));
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export class DeterministicEmbeddingProvider {
+    dimensions;
+    model;
+    version;
+    constructor(options = {}) {
+        this.dimensions = options.dimensions ?? 24;
+        this.model = options.model ?? "pseudo-sha256";
+        this.version = options.version ?? "v1";
+    }
+    async embed(input) {
+        return input.texts.map((text) => pseudoEmbedding(text, this.dimensions));
+    }
+    describe() {
+        return {
+            provider: "deterministic",
+            model: this.model,
+            dimensions: this.dimensions,
+            version: this.version
+        };
+    }
+}
+export class OpenAICompatibleEmbeddingProvider {
+    baseUrl;
+    endpoint;
+    apiKey;
+    model;
+    dimensions;
+    timeoutMs;
+    batchSize;
+    maxRetries;
+    observability;
+    constructor(options) {
+        const baseUrl = options.base_url.trim().replace(/\/+$/, "");
+        if (baseUrl.length === 0) {
+            throw new Error("invalid openai-compatible embedding config: base_url must be non-empty");
+        }
+        const apiKey = options.api_key.trim();
+        if (apiKey.length === 0) {
+            throw new Error("invalid openai-compatible embedding config: api_key must be non-empty");
+        }
+        this.baseUrl = baseUrl;
+        this.endpoint = `${this.baseUrl}/embeddings`;
+        this.apiKey = apiKey;
+        this.model = options.model?.trim() || DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_MODEL;
+        this.dimensions = options.dimensions ?? DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_DIMENSIONS;
+        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.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");
+        }
+        if (!Number.isInteger(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new Error("invalid openai-compatible embedding config: timeout_ms must be a positive integer");
+        }
+        if (!Number.isInteger(this.batchSize) || this.batchSize <= 0) {
+            throw new Error("invalid openai-compatible embedding config: batch_size must be a positive integer");
+        }
+        if (!Number.isInteger(this.maxRetries) || this.maxRetries < 0) {
+            throw new Error("invalid openai-compatible embedding config: max_retries must be a non-negative integer");
+        }
+    }
+    describe() {
+        return {
+            provider: "openai_compatible",
+            model: this.model,
+            dimensions: this.dimensions
+        };
+    }
+    async embed(input) {
+        if (input.texts.length === 0) {
+            return [];
+        }
+        const output = [];
+        for (let offset = 0; offset < input.texts.length; offset += this.batchSize) {
+            const batch = input.texts.slice(offset, offset + this.batchSize);
+            const vectors = await this.embedBatchWithRetries(batch, input.purpose);
+            output.push(...vectors);
+        }
+        return output;
+    }
+    async embedBatchWithRetries(texts, purpose) {
+        const labels = {
+            provider: "openai_compatible",
+            model: this.model,
+            purpose
+        };
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            const startedAt = Date.now();
+            this.observability.metrics.increment("retrieval_embedding_provider_requests_total", 1, labels);
+            try {
+                return await this.embedBatchOnce(texts);
+            }
+            catch (error) {
+                const failure = this.toProviderFailure(error);
+                this.observability.metrics.increment("retrieval_embedding_provider_failures_total", 1, {
+                    ...labels,
+                    reason: failure.reason
+                });
+                const shouldRetry = failure.retryable && attempt < this.maxRetries;
+                this.observability.logger.warn("embedding provider request failed", {
+                    provider: "openai_compatible",
+                    model: this.model,
+                    purpose,
+                    reason: failure.reason,
+                    retryable: failure.retryable,
+                    retrying: shouldRetry,
+                    attempt: attempt + 1,
+                    max_attempts: this.maxRetries + 1
+                });
+                if (shouldRetry) {
+                    await sleep(this.retryDelayMs(attempt));
+                    continue;
+                }
+                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) {
+        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,
+                    input: texts,
+                    encoding_format: "float"
+                }),
+                signal: controller.signal
+            });
+        }
+        catch (error) {
+            if (error && typeof error === "object" && "name" in error && error.name === "AbortError") {
+                throw new EmbeddingProviderRequestError("timeout", true, `request timed out after ${this.timeoutMs}ms`);
+            }
+            throw new EmbeddingProviderRequestError("network_error", true, error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const details = await safeResponseText(response);
+            if (response.status === 429) {
+                throw new EmbeddingProviderRequestError("rate_limited", true, `HTTP 429 ${details}`.trim());
+            }
+            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 === 404) {
+                throw new EmbeddingProviderRequestError("endpoint_not_found", false, `HTTP 404 ${details}`.trim());
+            }
+            throw new EmbeddingProviderRequestError("http_4xx", false, `HTTP ${response.status} ${details}`.trim());
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            throw new EmbeddingProviderRequestError("invalid_json", false, "provider returned non-JSON response");
+        }
+        if (!payload || typeof payload !== "object" || !("data" in payload)) {
+            throw new EmbeddingProviderRequestError("invalid_response", false, "provider response missing data field");
+        }
+        const rawData = payload.data;
+        if (!Array.isArray(rawData)) {
+            throw new EmbeddingProviderRequestError("invalid_response", false, "provider response data must be an array");
+        }
+        if (rawData.length !== texts.length) {
+            throw new EmbeddingProviderRequestError("count_mismatch", false, `provider returned ${rawData.length} embeddings for ${texts.length} inputs`);
+        }
+        const hasIndexField = rawData.every((entry) => entry && typeof entry === "object" && Number.isInteger(entry.index));
+        const ordered = hasIndexField
+            ? [...rawData].sort((a, b) => {
+                const left = a.index;
+                const right = b.index;
+                return left - right;
+            })
+            : rawData;
+        const vectors = [];
+        for (let i = 0; i < ordered.length; i += 1) {
+            const row = ordered[i];
+            if (!row || typeof row !== "object") {
+                throw new EmbeddingProviderRequestError("invalid_response", false, "embedding row must be an object");
+            }
+            if (hasIndexField && row.index !== i) {
+                throw new EmbeddingProviderRequestError("invalid_response", false, "embedding row indexes are not contiguous");
+            }
+            const embedding = row.embedding;
+            if (!isFiniteNumberArray(embedding)) {
+                throw new EmbeddingProviderRequestError("invalid_vector", false, "embedding must be a numeric array");
+            }
+            if (embedding.length !== this.dimensions) {
+                throw new EmbeddingProviderRequestError("dimension_mismatch", false, `expected ${this.dimensions} dimensions, received ${embedding.length}`);
+            }
+            vectors.push([...embedding]);
+        }
+        return vectors;
+    }
+    retryDelayMs(attempt) {
+        const base = 100 * (attempt + 1);
+        const jitter = Math.floor(Math.random() * 75);
+        return base + jitter;
+    }
+    toProviderFailure(error) {
+        if (error instanceof EmbeddingProviderRequestError) {
+            return error;
+        }
+        if (error instanceof RetrievalError) {
+            return new EmbeddingProviderRequestError("upstream_failure", false, error.message);
+        }
+        if (error instanceof Error) {
+            return new EmbeddingProviderRequestError("unknown_error", false, error.message);
+        }
+        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 "";
+    }
+}
+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 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 classifyIntent(prompt) {
+    const p = prompt.toLowerCase();
+    if (/fix|bug|error|crash|regression/.test(p)) {
+        return "bugfix";
+    }
+    if (/add|implement|new|support/.test(p)) {
+        return "feature";
+    }
+    if (/refactor|cleanup|restructure/.test(p)) {
+        return "refactor";
+    }
+    if (/readme|docs|documentation/.test(p)) {
+        return "docs";
+    }
+    if (/test|coverage|assert/.test(p)) {
+        return "tests";
+    }
+    return "unknown";
+}
+function detectDominantLanguage(prompt, history) {
+    const latestUser = [...history].reverse().find((m) => m.role === "user")?.content ?? prompt;
+    const sample = `${prompt}\n${latestUser}`.toLowerCase();
+    if (/[\u3400-\u9fff]/.test(sample)) {
+        return "zh";
+    }
+    if (/[áéíóúñ¿¡]/.test(sample) || /\b(implementar|arreglar|prueba|archivo|código)\b/.test(sample)) {
+        return "es";
+    }
+    return "en";
+}
+const ENHANCER_FRAMEWORK_HINT_RULES = [
+    {
+        id: "flask",
+        token_triggers: ["flask", "jinja", "template", "templates", "render_template", "render", "templating"],
+        phrase_triggers: ["render template", "render_template", "jinja loader", "before render template"],
+        symbol_hints: [
+            "render_template",
+            "render_template_string",
+            "before_render_template",
+            "DispatchingJinjaLoader",
+            "register_error_handler"
+        ],
+        path_hints: [
+            "src/flask/templating.py",
+            "src/flask/views.py",
+            "src/flask/signals.py",
+            "src/flask/sansio/scaffold.py",
+            "src/flask/sansio/app.py"
+        ]
+    },
+    {
+        id: "fastify",
+        token_triggers: [
+            "fastify",
+            "hook",
+            "hooks",
+            "addhook",
+            "seterrorhandler",
+            "onrequest",
+            "onerror",
+            "plugin"
+        ],
+        phrase_triggers: ["error handler", "seterrorhandler", "addhook", "request lifecycle"],
+        symbol_hints: ["addHook", "setErrorHandler", "onRequest", "onError", "preHandler", "setNotFoundHandler"],
+        path_hints: ["fastify.js", "lib/hooks.js", "lib/error-handler.js", "lib/route.js", "lib/handle-request.js"]
+    },
+    {
+        id: "node_web_runtime",
+        token_triggers: [
+            "express",
+            "koa",
+            "middleware",
+            "router",
+            "route",
+            "handler",
+            "request",
+            "response",
+            "pipeline"
+        ],
+        phrase_triggers: ["request pipeline", "error handler", "middleware chain", "route handler"],
+        symbol_hints: [
+            "middleware",
+            "router",
+            "handleRequest",
+            "setErrorHandler",
+            "onRequest",
+            "response.send",
+            "onerror",
+            "app.onerror"
+        ],
+        path_hints: ["lib/application.js", "lib/request.js", "lib/response.js", "lib/context.js", "lib/router", "src/server.ts"]
+    },
+    {
+        id: "http_client_runtime",
+        token_triggers: ["axios", "request", "adapter", "dispatch", "url", "fetch", "http", "client"],
+        phrase_triggers: ["http adapter", "request dispatch", "url builder", "request pipeline"],
+        symbol_hints: ["dispatchRequest", "mergeConfig", "buildURL", "combineURLs", "adapter"],
+        path_hints: ["lib/core", "lib/helpers", "lib/adapters", "src/client", "src/http"]
+    }
+];
+const SYMBOL_STOPWORDS = new Set([
+    "about",
+    "after",
+    "before",
+    "behavior",
+    "change",
+    "compatibility",
+    "enhance",
+    "flow",
+    "keep",
+    "logic",
+    "module",
+    "preserve",
+    "refactor",
+    "request",
+    "response",
+    "should",
+    "stable",
+    "support",
+    "while"
+]);
+const ENHANCER_IMPLEMENTATION_INTENT_HINTS = [
+    "implementation",
+    "source",
+    "runtime",
+    "module",
+    "handler",
+    "function",
+    "class",
+    "codepath",
+    "src",
+    "lib"
+];
+const ENHANCER_DOCS_INTENT_TOKENS = new Set([
+    "adr",
+    "architecture",
+    "doc",
+    "docs",
+    "documentation",
+    "readme",
+    "spec",
+    "specification"
+]);
+const ENHANCER_TEST_INTENT_TOKENS = new Set(["assert", "coverage", "integration", "spec", "test", "tests", "unit"]);
+const ENHANCER_CONCEPTUAL_INTENT_TOKENS = new Set([
+    "architecture",
+    "concept",
+    "design",
+    "explain",
+    "guidance",
+    "how",
+    "overview",
+    "reason",
+    "tradeoff",
+    "why"
+]);
+function classifyEnhancerQueryIntent(prompt, history) {
+    const recentMessages = [...history]
+        .reverse()
+        .filter((message) => message.role !== "system")
+        .map((message) => message.content.trim())
+        .filter((content) => content.length > 0 && content !== prompt.trim())
+        .slice(0, 4)
+        .reverse();
+    const combined = normalizeQuery([prompt, ...recentMessages].join("\n").trim());
+    const tokens = tokenize(combined);
+    const extractedSymbols = extractLikelyCodeSymbols(combined, 20);
+    const extractedPaths = extractPathLikeSymbols(combined);
+    const quotedSymbols = (combined.match(/`[^`]+`/g) ?? []).length;
+    const symbolSignal = extractedSymbols.length + extractedPaths.length * 2 + quotedSymbols * 2;
+    if (symbolSignal >= 8 || (extractedSymbols.length >= 4 && (extractedPaths.length > 0 || quotedSymbols > 0))) {
+        return "symbol-heavy";
+    }
+    let implSignal = 0;
+    let conceptualSignal = 0;
+    for (const token of tokens) {
+        if (CODE_INTENT_TOKENS.has(token) || ENHANCER_IMPLEMENTATION_INTENT_HINTS.includes(token)) {
+            implSignal += 1;
+        }
+        if (ENHANCER_DOCS_INTENT_TOKENS.has(token) || ENHANCER_CONCEPTUAL_INTENT_TOKENS.has(token)) {
+            conceptualSignal += 1;
+        }
+    }
+    const negativePreferences = detectNegativePathPreferences(combined);
+    if (negativePreferences.avoid_docs || negativePreferences.avoid_tests || negativePreferences.avoid_examples) {
+        implSignal += 2;
+    }
+    if (implSignal >= conceptualSignal + 1) {
+        return "impl-focused";
+    }
+    return "conceptual";
+}
+function resolveEnhancerIntentPolicy(input) {
+    const strictImplOnlyFiltering = input.query_intent !== "conceptual" &&
+        (input.negative_preferences.avoid_docs ||
+            input.negative_preferences.avoid_tests ||
+            input.negative_preferences.avoid_examples);
+    if (input.query_intent === "symbol-heavy") {
+        return {
+            max_expansion_hints: Math.min(input.enhancer_config.max_expansion_hints, 12),
+            max_candidates_pre_rerank: Math.max(1, Math.min(input.enhancer_config.max_candidates_pre_rerank, 3)),
+            max_candidates_per_directory_pre_rerank: 1,
+            strict_impl_only_filtering: strictImplOnlyFiltering
+        };
+    }
+    if (input.query_intent === "impl-focused") {
+        return {
+            max_expansion_hints: Math.min(input.enhancer_config.max_expansion_hints, 18),
+            max_candidates_pre_rerank: Math.max(1, Math.min(input.enhancer_config.max_candidates_pre_rerank, 4)),
+            max_candidates_per_directory_pre_rerank: 2,
+            strict_impl_only_filtering: strictImplOnlyFiltering
+        };
+    }
+    return {
+        max_expansion_hints: Math.min(input.enhancer_config.max_expansion_hints, 22),
+        max_candidates_pre_rerank: Math.max(1, Math.min(input.enhancer_config.max_candidates_pre_rerank, 4)),
+        max_candidates_per_directory_pre_rerank: 3,
+        strict_impl_only_filtering: false
+    };
+}
+function looksLikeCodeSymbol(value) {
+    if (value.length < 3 || value.length > 96) {
+        return false;
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_./-]*$/.test(value)) {
+        return false;
+    }
+    const normalized = value.toLowerCase();
+    if (SYMBOL_STOPWORDS.has(normalized)) {
+        return false;
+    }
+    return (value.includes("_") ||
+        value.includes(".") ||
+        value.includes("/") ||
+        /[a-z][A-Z]/.test(value) ||
+        /[A-Z]{2,}/.test(value) ||
+        /^(?:get|set|add|create|render|handle|parse|build|validate|register|process|update|remove|is|has)[A-Z_]/.test(value));
+}
+function extractPathLikeSymbols(text) {
+    const out = [];
+    for (const match of text.matchAll(/\b(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.[A-Za-z0-9]+\b/g)) {
+        const value = (match[0] ?? "").trim();
+        if (value) {
+            out.push(value);
+        }
+    }
+    return out;
+}
+function extractLikelyCodeSymbols(text, limit = 12) {
+    const symbols = [];
+    const seen = new Set();
+    const add = (candidate) => {
+        const normalized = candidate.trim().replace(/^[`"'([{]+|[`"')\]}:;,.]+$/g, "");
+        if (!normalized || seen.has(normalized) || !looksLikeCodeSymbol(normalized)) {
+            return;
+        }
+        seen.add(normalized);
+        symbols.push(normalized);
+    };
+    for (const match of text.matchAll(/`([^`]+)`/g)) {
+        const quoted = match[1] ?? "";
+        for (const part of quoted.split(/[\s,;(){}[\]]+/g).filter(Boolean)) {
+            add(part);
+            if (symbols.length >= limit) {
+                return symbols;
+            }
+        }
+    }
+    for (const value of extractPathLikeSymbols(text)) {
+        add(value);
+        if (symbols.length >= limit) {
+            return symbols;
+        }
+    }
+    for (const match of text.matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\s*\(/g)) {
+        add(match[1] ?? "");
+        if (symbols.length >= limit) {
+            return symbols;
+        }
+    }
+    for (const match of text.matchAll(/\b[A-Za-z_][A-Za-z0-9_]*(?:[./-][A-Za-z_][A-Za-z0-9_]*)*\b/g)) {
+        add(match[0] ?? "");
+        if (symbols.length >= limit) {
+            return symbols;
+        }
+    }
+    return symbols;
+}
+function extractPathFormHints(text, limit = 12) {
+    const words = (text.toLowerCase().match(/\b[a-z][a-z0-9_]{1,48}\b/g) ?? [])
+        .map((token) => token.trim())
+        .filter(Boolean)
+        .filter((token) => !SYMBOL_STOPWORDS.has(token));
+    const out = [];
+    const seen = new Set();
+    for (let i = 0; i < words.length - 1; i += 1) {
+        const left = words[i];
+        const right = words[i + 1];
+        if (!left || !right || left.length < 3 || right.length < 3) {
+            continue;
+        }
+        const forms = [
+            `${left}/${right}`,
+            `${singularizeToken(left) ?? left}/${singularizeToken(right) ?? right}`,
+            `${pluralizeToken(left) ?? left}/${right}`
+        ];
+        for (const form of forms) {
+            if (seen.has(form)) {
+                continue;
+            }
+            seen.add(form);
+            out.push(form);
+            if (out.length >= limit) {
+                return out;
+            }
+        }
+    }
+    return out;
+}
+function buildEnhancerRetrievalQuery(prompt, history, options) {
+    const maxExpansionHints = options?.maxExpansionHints ?? DEFAULT_RETRIEVAL_ENHANCER_CONFIG.max_expansion_hints;
+    const queryIntent = options?.queryIntent ?? classifyEnhancerQueryIntent(prompt, history);
+    const recentMessages = [...history]
+        .reverse()
+        .filter((message) => message.role !== "system")
+        .map((message) => message.content.trim())
+        .filter((content) => content.length > 0 && content !== prompt.trim())
+        .slice(0, 4)
+        .reverse();
+    const combined = normalizeQuery([prompt, ...recentMessages].join("\n").trim());
+    const lower = combined.toLowerCase();
+    const queryTokens = tokenize(combined);
+    const queryTokenSet = new Set(queryTokens);
+    const docsIntent = queryTokens.some((token) => ENHANCER_DOCS_INTENT_TOKENS.has(token));
+    const negativePreferences = detectNegativePathPreferences(combined);
+    const testsIntent = queryTokens.some((token) => ENHANCER_TEST_INTENT_TOKENS.has(token));
+    const implementationIntent = queryIntent !== "conceptual";
+    const hintSet = new Set();
+    const hints = [];
+    const addHint = (value) => {
+        if (hints.length >= maxExpansionHints) {
+            return;
+        }
+        const normalized = value.trim();
+        if (!normalized || hintSet.has(normalized)) {
+            return;
+        }
+        hintSet.add(normalized);
+        hints.push(normalized);
+    };
+    const extractedSymbols = extractLikelyCodeSymbols(combined, 12);
+    for (const symbol of extractedSymbols) {
+        addHint(symbol);
+    }
+    const extractedPathForms = extractPathFormHints(combined, 12);
+    for (const pathForm of extractedPathForms) {
+        addHint(pathForm);
+    }
+    const symbolHeavyPrompt = queryIntent === "symbol-heavy" || extractedSymbols.length >= 4 || extractedPathForms.length >= 4;
+    const genericHintBudget = queryIntent === "symbol-heavy"
+        ? Math.max(2, Math.floor(maxExpansionHints / 3))
+        : queryIntent === "impl-focused"
+            ? Math.max(4, Math.floor(maxExpansionHints * 0.8))
+            : maxExpansionHints;
+    const frameworkHintBudget = queryIntent === "symbol-heavy"
+        ? Math.max(2, Math.floor(genericHintBudget / 2))
+        : queryIntent === "impl-focused"
+            ? Math.max(3, Math.floor(genericHintBudget * 0.8))
+            : Math.max(4, Math.floor(genericHintBudget * 0.85));
+    let genericHintCount = 0;
+    let frameworkHintCount = 0;
+    const addGenericHint = (value) => {
+        if (genericHintCount >= genericHintBudget) {
+            return;
+        }
+        const beforeCount = hints.length;
+        addHint(value);
+        if (hints.length > beforeCount) {
+            genericHintCount += 1;
+        }
+    };
+    const addFrameworkHint = (value) => {
+        if (frameworkHintCount >= frameworkHintBudget) {
+            return;
+        }
+        const beforeCount = hints.length;
+        addGenericHint(value);
+        if (hints.length > beforeCount) {
+            frameworkHintCount += 1;
+        }
+    };
+    if (/\b(cli|subcommand|command|flag)\b/.test(lower)) {
+        addGenericHint("main.rs");
+        addGenericHint("clap");
+        addGenericHint("subcommand");
+        addGenericHint("command");
+    }
+    if (/\b(react|tsx|ui|component|layout|panel)\b/.test(lower)) {
+        addGenericHint("app.tsx");
+        addGenericHint("component");
+        addGenericHint("ui");
+    }
+    if (queryIntent === "conceptual" || (!implementationIntent && /\b(adr|readme|spec|docs|documentation|milestone)\b/.test(lower))) {
+        addGenericHint("docs");
+        addGenericHint("spec");
+        addGenericHint("markdown");
+    }
+    if (/\b(python|django|flask|jinja|pydantic)\b/.test(lower)) {
+        addGenericHint("py");
+        addGenericHint("src");
+        addGenericHint("views.py");
+        addGenericHint("handlers");
+    }
+    if (/\b(node|javascript|typescript|ts|js|express|koa|fastify)\b/.test(lower)) {
+        addGenericHint("src");
+        addGenericHint("lib");
+        addGenericHint("handler");
+        addGenericHint("middleware");
+    }
+    const prefersRuntimeOnly = negativePreferences.avoid_docs || negativePreferences.avoid_tests || negativePreferences.avoid_examples;
+    if (implementationIntent && (!docsIntent || prefersRuntimeOnly)) {
+        for (const hint of ENHANCER_IMPLEMENTATION_INTENT_HINTS) {
+            addGenericHint(hint);
+        }
+    }
+    if (prefersRuntimeOnly) {
+        addGenericHint("runtime");
+        addGenericHint("src");
+        addGenericHint("lib");
+        addGenericHint("implementation");
+    }
+    if (testsIntent) {
+        addGenericHint("test");
+        addGenericHint("assert");
+    }
+    for (const rule of ENHANCER_FRAMEWORK_HINT_RULES) {
+        const hasTokenTrigger = rule.token_triggers.some((token) => queryTokenSet.has(token));
+        const hasPhraseTrigger = rule.phrase_triggers.some((phrase) => lower.includes(phrase));
+        if (!hasTokenTrigger && !hasPhraseTrigger) {
+            continue;
+        }
+        for (const symbol of rule.symbol_hints) {
+            addFrameworkHint(symbol);
+        }
+        for (const pathHint of rule.path_hints) {
+            addFrameworkHint(pathHint);
+        }
+    }
+    const sections = [combined];
+    sections.push(`query_intent: ${queryIntent}`);
+    if (extractedSymbols.length > 0) {
+        sections.push(`symbol_candidates: ${extractedSymbols.join(" ")}`);
+    }
+    if (hints.length > 0) {
+        sections.push(`retrieval_hints: ${hints.join(" ")}`);
+    }
+    return {
+        query: sections.join("\n").trim(),
+        expanded_hint_count: hints.length,
+        query_intent: queryIntent
+    };
+}
+const ENHANCER_LOW_CONFIDENCE_WARNING = "Low retrieval confidence; narrowed context refs and added clarification questions.";
+const ENHANCER_CONFIDENCE_OVERLAP_STOPWORDS = new Set([
+    "a",
+    "about",
+    "an",
+    "and",
+    "avoid",
+    "behavior",
+    "change",
+    "doc",
+    "docs",
+    "documentation",
+    "example",
+    "examples",
+    "for",
+    "from",
+    "in",
+    "is",
+    "not",
+    "of",
+    "on",
+    "or",
+    "readme",
+    "spec",
+    "tests",
+    "test",
+    "the",
+    "to",
+    "without",
+    "with"
+]);
+function parentDirectory(path) {
+    const normalized = normalizePath(path);
+    const idx = normalized.lastIndexOf("/");
+    if (idx <= 0) {
+        return ".";
+    }
+    return normalized.slice(0, idx);
+}
+function fileExtension(path) {
+    const normalized = normalizePath(path).toLowerCase();
+    const filename = normalized.split("/").pop() ?? normalized;
+    const idx = filename.lastIndexOf(".");
+    if (idx < 0) {
+        return "";
+    }
+    return filename.slice(idx);
+}
+function average(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function percentile(values, p) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
+    return sorted[idx] ?? 0;
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function normalizeEnhancerOverlapTokens(text) {
+    return tokenize(text).filter((token) => token.length >= 3 && !ENHANCER_CONFIDENCE_OVERLAP_STOPWORDS.has(token));
+}
+function overlapRatio(queryTokens, result) {
+    if (queryTokens.length === 0) {
+        return 0;
+    }
+    const haystack = new Set(tokenize(`${result.path}\n${result.reason}\n${result.snippet}`));
+    let overlap = 0;
+    for (const token of queryTokens) {
+        if (haystack.has(token)) {
+            overlap += 1;
+        }
+    }
+    return overlap / queryTokens.length;
+}
+function pathDiversity(results) {
+    if (results.length === 0) {
+        return 0;
+    }
+    const uniqueDirs = new Set(results.map((result) => parentDirectory(result.path).toLowerCase()));
+    return uniqueDirs.size / results.length;
+}
+function isDocsLikePath(path) {
+    const normalized = normalizePath(path).toLowerCase();
+    return (normalized.startsWith("docs/") ||
+        normalized.includes("/docs/") ||
+        normalized.endsWith(".md") ||
+        normalized.endsWith(".rst") ||
+        normalized.endsWith(".txt"));
+}
+function isTestLikePath(path) {
+    const normalized = normalizePath(path).toLowerCase();
+    return (normalized.startsWith("test/") ||
+        normalized.startsWith("tests/") ||
+        normalized.startsWith("__tests__/") ||
+        normalized.includes("/test/") ||
+        normalized.includes("/tests/") ||
+        normalized.includes("/__tests__/") ||
+        normalized.endsWith(".test.js") ||
+        normalized.endsWith(".test.ts") ||
+        normalized.endsWith(".spec.js") ||
+        normalized.endsWith(".spec.ts") ||
+        normalized.endsWith(".spec.py"));
+}
+function isExampleLikePath(path) {
+    const normalized = normalizePath(path).toLowerCase();
+    return (normalized.startsWith("example/") ||
+        normalized.startsWith("examples/") ||
+        normalized.includes("/example/") ||
+        normalized.includes("/examples/"));
+}
+function isArchiveLikePath(path) {
+    const normalized = normalizePath(path).toLowerCase();
+    return (normalized.includes("/archive/") ||
+        normalized.includes("/_archive/") ||
+        normalized.startsWith("archive/") ||
+        normalized.startsWith("_archive/"));
+}
+function shouldAvoidPathFromNegation(path, preferences) {
+    if (preferences.avoid_archive && isArchiveLikePath(path)) {
+        return true;
+    }
+    if (preferences.avoid_docs && isDocsLikePath(path)) {
+        return true;
+    }
+    if (preferences.avoid_tests && isTestLikePath(path)) {
+        return true;
+    }
+    if (preferences.avoid_examples && isExampleLikePath(path)) {
+        return true;
+    }
+    return false;
+}
+function isRiskyEnhancerPath(path, intent) {
+    if (intent === "docs") {
+        return false;
+    }
+    if (intent === "tests") {
+        return isDocsLikePath(path) || isExampleLikePath(path);
+    }
+    return isDocsLikePath(path) || isTestLikePath(path) || isExampleLikePath(path);
+}
+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 dedupeEnhancerCandidatesByPath(results) {
+    const byPath = new Map();
+    for (const result of results) {
+        const key = normalizePath(result.path).toLowerCase();
+        const existing = byPath.get(key);
+        if (!existing || compareSearchResults(result, existing) < 0) {
+            byPath.set(key, result);
+        }
+    }
+    return [...byPath.values()].sort(compareSearchResults);
+}
+function collapseEnhancerCandidatesByDirectory(results, maxPerDirectory) {
+    if (maxPerDirectory <= 0) {
+        return [];
+    }
+    const output = [];
+    const directoryCounts = new Map();
+    for (const result of [...results].sort(compareSearchResults)) {
+        const directory = parentDirectory(result.path).toLowerCase();
+        const count = directoryCounts.get(directory) ?? 0;
+        if (count >= maxPerDirectory) {
+            continue;
+        }
+        directoryCounts.set(directory, count + 1);
+        output.push(result);
+    }
+    return output;
+}
+function extractEnhancerAnchors(text) {
+    const anchors = new Set();
+    for (const symbol of extractLikelyCodeSymbols(text, 10)) {
+        const normalized = symbol.trim().toLowerCase();
+        if (normalized.length >= 4) {
+            anchors.add(normalized);
+        }
+    }
+    for (const rawPath of extractPathLikeSymbols(text).slice(0, 10)) {
+        const normalizedPath = normalizePath(rawPath).toLowerCase();
+        if (normalizedPath.length >= 4) {
+            anchors.add(normalizedPath);
+        }
+        const leaf = normalizedPath.split("/").pop();
+        if (leaf && leaf.length >= 4) {
+            anchors.add(leaf);
+        }
+    }
+    return [...anchors];
+}
+function hasStrongEnhancerAnchorMatch(input) {
+    const top = dedupeEnhancerCandidatesByPath(input.results).slice(0, 3);
+    if (top.length === 0) {
+        return false;
+    }
+    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");
+    if (hasTopExactSymbolMatch && strongScoreMargin && topScore >= 0.55) {
+        return true;
+    }
+    const anchorSource = `${input.prompt}\n${input.history.map((entry) => entry.content).join("\n")}`;
+    const anchors = extractEnhancerAnchors(anchorSource);
+    if (anchors.length === 0) {
+        return false;
+    }
+    let anchorMatches = 0;
+    for (const result of top) {
+        const normalizedPath = normalizePath(result.path).toLowerCase();
+        const normalizedSnippet = result.snippet.toLowerCase();
+        const matched = anchors.some((anchor) => normalizedPath.includes(anchor) || (anchor.length >= 5 && normalizedSnippet.includes(anchor)));
+        if (matched) {
+            anchorMatches += 1;
+        }
+    }
+    return anchorMatches >= 2 && strongScoreMargin;
+}
+function shouldBypassEnhancerRerankForAnchors(input) {
+    if (input.query_intent === "conceptual") {
+        return false;
+    }
+    const hasStrongAnchors = hasStrongEnhancerAnchorMatch({
+        prompt: input.prompt,
+        history: input.history,
+        results: input.results
+    });
+    if (!hasStrongAnchors) {
+        return false;
+    }
+    if (input.query_intent === "symbol-heavy") {
+        return true;
+    }
+    if (input.negative_preferences.avoid_docs ||
+        input.negative_preferences.avoid_tests ||
+        input.negative_preferences.avoid_examples ||
+        input.negative_preferences.avoid_archive) {
+        return true;
+    }
+    const top = dedupeEnhancerCandidatesByPath(input.results).slice(0, 2);
+    if (top.length < 2) {
+        return true;
+    }
+    const lead = (top[0]?.score ?? 0) - (top[1]?.score ?? 0);
+    return lead >= 0.04;
+}
+function evaluateEnhancerConfidence(input) {
+    const top = input.results.slice(0, 5);
+    if (top.length === 0) {
+        return {
+            score_spread: 0,
+            token_overlap: 0,
+            path_diversity: 0,
+            confidence_score: 0,
+            confidence_threshold: 0.5,
+            failed_signals: ["empty_results"],
+            low_confidence: true
+        };
+    }
+    const topScores = top.map((result) => result.score);
+    const topScore = topScores[0] ?? 0;
+    const runnerUpScore = topScores[1] ?? topScore;
+    const scoreSpread = (topScores[0] ?? 0) - average(topScores);
+    const scoreP25 = percentile(topScores, 0.25);
+    const scoreP50 = percentile(topScores, 0.5);
+    const scoreP75 = percentile(topScores, 0.75);
+    const scoreIqr = Math.max(1e-6, scoreP75 - scoreP25);
+    const leadStrength = clamp01((topScore - runnerUpScore) / (Math.abs(topScore - runnerUpScore) + scoreIqr));
+    const spreadStrength = clamp01((topScore - scoreP50) / (Math.abs(topScore - scoreP50) + scoreIqr));
+    const distributionStrength = average([leadStrength, spreadStrength]);
+    const overlapTokens = normalizeEnhancerOverlapTokens(`${input.prompt}\n${input.retrieval_query}`);
+    const topOverlap = average(top.slice(0, 3).map((result) => overlapRatio(overlapTokens, result)));
+    const topPathDiversity = pathDiversity(top);
+    const targetPathDiversity = input.query_intent === "conceptual" ? 0.6 : 0.45;
+    const diversityStrength = clamp01(1 - Math.abs(topPathDiversity - targetPathDiversity) / Math.max(0.2, targetPathDiversity));
+    const confidenceComponents = [distributionStrength, topOverlap, diversityStrength];
+    const confidenceScore = average(confidenceComponents);
+    const thresholdQuantile = input.query_intent === "symbol-heavy" ? 0.5 : input.query_intent === "impl-focused" ? 0.55 : 0.6;
+    const confidenceThreshold = percentile(confidenceComponents, thresholdQuantile);
+    const failedSignals = [];
+    if (distributionStrength < confidenceThreshold) {
+        failedSignals.push("score_spread");
+    }
+    if (topOverlap < confidenceThreshold) {
+        failedSignals.push("token_overlap");
+    }
+    if (diversityStrength < confidenceThreshold) {
+        failedSignals.push("path_diversity");
+    }
+    const strongSymbolOrPathSignal = top.some((result) => result.reason === "exact symbol match") && topOverlap >= 0.16;
+    const lowConfidence = !strongSymbolOrPathSignal && confidenceScore + 0.01 < confidenceThreshold;
+    return {
+        score_spread: scoreSpread,
+        token_overlap: topOverlap,
+        path_diversity: topPathDiversity,
+        confidence_score: confidenceScore,
+        confidence_threshold: confidenceThreshold,
+        failed_signals: failedSignals,
+        low_confidence: lowConfidence
+    };
+}
+function rankEnhancerResultsForConfidence(input) {
+    const overlapTokens = normalizeEnhancerOverlapTokens(`${input.prompt}\n${input.retrieval_query}`);
+    const anchors = extractEnhancerAnchors(`${input.prompt}\n${input.retrieval_query}`);
+    const anchorScore = (result) => {
+        const normalizedPath = normalizePath(result.path).toLowerCase();
+        const normalizedSnippet = result.snippet.toLowerCase();
+        let score = result.reason === "exact symbol match" ? 2 : 0;
+        for (const anchor of anchors) {
+            if (normalizedPath.includes(anchor)) {
+                score += 2;
+                continue;
+            }
+            if (anchor.length >= 5 && normalizedSnippet.includes(anchor)) {
+                score += 1;
+            }
+        }
+        return score;
+    };
+    return [...input.results].sort((a, b) => {
+        const aExcludedByNegation = shouldAvoidPathFromNegation(a.path, input.negative_preferences) ? 1 : 0;
+        const bExcludedByNegation = shouldAvoidPathFromNegation(b.path, input.negative_preferences) ? 1 : 0;
+        if (aExcludedByNegation !== bExcludedByNegation) {
+            return aExcludedByNegation - bExcludedByNegation;
+        }
+        const aRisk = isRiskyEnhancerPath(a.path, input.intent) ? 1 : 0;
+        const bRisk = isRiskyEnhancerPath(b.path, input.intent) ? 1 : 0;
+        if (aRisk !== bRisk) {
+            return aRisk - bRisk;
+        }
+        if (input.query_intent !== "conceptual") {
+            const aRuntimePenalty = isDocsLikePath(a.path) || isTestLikePath(a.path) || isExampleLikePath(a.path) || isArchiveLikePath(a.path) ? 1 : 0;
+            const bRuntimePenalty = isDocsLikePath(b.path) || isTestLikePath(b.path) || isExampleLikePath(b.path) || isArchiveLikePath(b.path) ? 1 : 0;
+            if (aRuntimePenalty !== bRuntimePenalty) {
+                return aRuntimePenalty - bRuntimePenalty;
+            }
+        }
+        const anchorDiff = anchorScore(b) - anchorScore(a);
+        if (anchorDiff !== 0) {
+            return anchorDiff;
+        }
+        const overlapDiff = overlapRatio(overlapTokens, b) - overlapRatio(overlapTokens, a);
+        if (Math.abs(overlapDiff) > 1e-6) {
+            return overlapDiff;
+        }
+        const scoreDiff = b.score - a.score;
+        if (Math.abs(scoreDiff) > 1e-6) {
+            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;
+    });
+}
+async function runWithTimeout(input) {
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            reject(new Error(`timeout_after_${input.timeout_ms}ms`));
+        }, input.timeout_ms);
+        Promise.resolve()
+            .then(() => input.fn())
+            .then((value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch((error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            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) {
+    let total = 0;
+    const out = [];
+    for (const result of results) {
+        total += tokenize(result.snippet).length;
+        if (total > MAX_CONTEXT_BUDGET_TOKENS) {
+            break;
+        }
+        out.push(result);
+    }
+    return out;
+}
+function formatEnhancedPrompt(input) {
+    const emptyRefsByLanguage = {
+        en: "- (no file context available)",
+        es: "- (no hay contexto de archivos disponible)",
+        zh: "- (暂无可用文件上下文)"
+    };
+    const likelyFiles = input.refs.length > 0 ? input.refs.map((r) => `- ${r.path}:${r.start_line}`).join("\n") : emptyRefsByLanguage[input.language];
+    if (input.language === "zh") {
+        return [
+            "目标",
+            input.original_prompt,
+            "",
+            "当前状态",
+            `- 识别意图: ${input.intent}`,
+            "",
+            "约束",
+            "- 保持 v1 合约兼容和严格校验。",
+            "",
+            "可能涉及的文件",
+            likelyFiles,
+            "",
+            "实现清单",
+            "- 在改动前确认请求/响应合约。",
+            "- 最小化改动并保持 tenant/workspace 隔离。",
+            "",
+            "边界情况",
+            "- Workspace 没有可用索引。",
+            "- 搜索过滤后结果为空。",
+            "",
+            "验证与测试",
+            "- 运行 typecheck 和合约/工具测试。",
+            "",
+            "完成定义",
+            "- 测试通过且行为符合 v1 规范。"
+        ].join("\n");
+    }
+    if (input.language === "es") {
+        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",
+            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.",
+            "",
+            "Definición de terminado",
+            "- Los tests pasan y el comportamiento coincide con el spec."
+        ].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",
+        likelyFiles,
+        "",
+        "Implementation checklist",
+        "- 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."
+    ].join("\n");
+}
+function detectSecretMatches(content) {
+    const matches = new Set();
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.pattern.test(content)) {
+            matches.add(pattern.label);
+        }
+        pattern.pattern.lastIndex = 0;
+    }
+    return [...matches];
+}
+export class InMemoryIndexStore {
+    workspaces = new Map();
+    workspacesByPath = new Map();
+    indexes = new Map();
+    workspaceIndexes = new Map();
+    filesByIndex = new Map();
+    chunksByFile = new Map();
+    indexMetadata = new Map();
+    async migrate() {
+        return;
+    }
+    async upsertWorkspace(input) {
+        this.workspaces.set(input.workspace_id, input);
+        this.workspacesByPath.set(`${input.tenant_id}:${input.project_root_path}`, input);
+    }
+    async resolveWorkspaceByProjectRoot(tenant_id, project_root_path) {
+        return this.workspacesByPath.get(`${tenant_id}:${project_root_path}`);
+    }
+    async resolveWorkspaceByWorkspaceId(tenant_id, workspace_id) {
+        const workspace = this.workspaces.get(workspace_id);
+        if (!workspace || workspace.tenant_id !== tenant_id) {
+            return undefined;
+        }
+        return workspace;
+    }
+    async createIndexVersion(input) {
+        const indexId = `idx_${randomUUID()}`;
+        const index = {
+            index_id: indexId,
+            workspace_id: input.workspace_id,
+            tenant_id: input.tenant_id,
+            index_version: input.index_version,
+            status: input.status ?? "indexing",
+            created_at: new Date().toISOString(),
+            updated_at: new Date().toISOString()
+        };
+        this.indexes.set(indexId, index);
+        const existing = this.workspaceIndexes.get(input.workspace_id) ?? [];
+        existing.push(indexId);
+        this.workspaceIndexes.set(input.workspace_id, existing);
+        this.filesByIndex.set(indexId, []);
+        return index;
+    }
+    async markIndexStatus(input) {
+        const index = this.indexes.get(input.index_id);
+        if (!index) {
+            return;
+        }
+        if (index.tenant_id !== input.tenant_id || index.workspace_id !== input.workspace_id) {
+            return;
+        }
+        index.status = input.status;
+        index.updated_at = new Date().toISOString();
+    }
+    async getIndexByVersion(input) {
+        for (const index of this.indexes.values()) {
+            if (index.tenant_id === input.tenant_id &&
+                index.workspace_id === input.workspace_id &&
+                index.index_version === input.index_version) {
+                return index;
+            }
+        }
+        return undefined;
+    }
+    async resetIndexContent(input) {
+        const index = this.indexes.get(input.index_id);
+        if (!index || index.tenant_id !== input.tenant_id) {
+            return;
+        }
+        const files = this.filesByIndex.get(input.index_id) ?? [];
+        for (const file of files) {
+            this.chunksByFile.delete(file.file_id);
+        }
+        this.filesByIndex.set(input.index_id, []);
+    }
+    async getLatestReadyIndex(input) {
+        const indexIds = this.workspaceIndexes.get(input.workspace_id) ?? [];
+        const readyIndexes = indexIds
+            .map((id) => this.indexes.get(id))
+            .filter((index) => index !== undefined)
+            .filter((index) => index.tenant_id === input.tenant_id && index.workspace_id === input.workspace_id && index.status === "ready");
+        readyIndexes.sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+        return readyIndexes[0];
+    }
+    async getFilesByIndex(input) {
+        const index = this.indexes.get(input.index_id);
+        if (!index || index.tenant_id !== input.tenant_id) {
+            return [];
+        }
+        return [...(this.filesByIndex.get(input.index_id) ?? [])];
+    }
+    async copyFileFromIndex(input) {
+        const sourceFiles = this.filesByIndex.get(input.source_index_id) ?? [];
+        const sourceFile = sourceFiles.find((file) => file.repo_path === input.repo_path);
+        if (!sourceFile) {
+            return;
+        }
+        const targetFiles = this.filesByIndex.get(input.target_index_id) ?? [];
+        const targetFile = {
+            file_id: `fil_${randomUUID()}`,
+            repo_path: sourceFile.repo_path,
+            content_hash: sourceFile.content_hash,
+            language: sourceFile.language
+        };
+        targetFiles.push(targetFile);
+        this.filesByIndex.set(input.target_index_id, targetFiles);
+        const sourceChunks = this.chunksByFile.get(sourceFile.file_id) ?? [];
+        this.chunksByFile.set(targetFile.file_id, sourceChunks.map((chunk) => ({
+            ...chunk,
+            hash: sha256(`${targetFile.file_id}:${chunk.start_line}:${chunk.end_line}:${chunk.snippet}`)
+        })));
+    }
+    async upsertFile(input) {
+        const files = this.filesByIndex.get(input.index_id) ?? [];
+        const existing = files.find((file) => file.repo_path === input.repo_path);
+        if (existing) {
+            existing.content_hash = input.content_hash;
+            existing.language = input.language;
+            return { file_id: existing.file_id };
+        }
+        const file_id = `fil_${randomUUID()}`;
+        files.push({
+            file_id,
+            repo_path: input.repo_path,
+            content_hash: input.content_hash,
+            language: input.language
+        });
+        this.filesByIndex.set(input.index_id, files);
+        return { file_id };
+    }
+    async replaceFileChunks(input) {
+        this.chunksByFile.set(input.file_id, input.chunks.map((chunk) => ({
+            path: input.repo_path,
+            start_line: chunk.start_line,
+            end_line: chunk.end_line,
+            snippet: chunk.snippet,
+            generated: chunk.generated,
+            updated_at: chunk.updated_at ?? new Date().toISOString(),
+            hash: sha256(`${input.file_id}:${chunk.start_line}:${chunk.end_line}:${chunk.snippet}`),
+            embedding: [...chunk.embedding]
+        })));
+    }
+    async saveManifest() {
+        return;
+    }
+    async saveIndexMetadata(input) {
+        this.indexMetadata.set(input.index_id, {
+            tenant_id: input.tenant_id,
+            embedding_provider: input.embedding_provider,
+            ...(input.embedding_model ? { embedding_model: input.embedding_model } : {}),
+            embedding_dimensions: input.embedding_dimensions,
+            ...(input.embedding_version ? { embedding_version: input.embedding_version } : {}),
+            chunking_strategy: input.chunking_strategy,
+            chunking_fallback_strategy: input.chunking_fallback_strategy,
+            created_at: new Date().toISOString()
+        });
+    }
+    async getIndexMetadata(input) {
+        const metadata = this.indexMetadata.get(input.index_id);
+        if (!metadata || metadata.tenant_id !== input.tenant_id) {
+            return undefined;
+        }
+        return {
+            embedding_provider: metadata.embedding_provider,
+            ...(metadata.embedding_model ? { embedding_model: metadata.embedding_model } : {}),
+            embedding_dimensions: metadata.embedding_dimensions,
+            ...(metadata.embedding_version ? { embedding_version: metadata.embedding_version } : {}),
+            chunking_strategy: metadata.chunking_strategy,
+            chunking_fallback_strategy: metadata.chunking_fallback_strategy,
+            created_at: metadata.created_at
+        };
+    }
+    async listChunksByIndex(input) {
+        const index = this.indexes.get(input.index_id);
+        if (!index || index.tenant_id !== input.tenant_id) {
+            return [];
+        }
+        const files = this.filesByIndex.get(input.index_id) ?? [];
+        const globRegex = input.filters?.glob ? compileGlob(input.filters.glob) : undefined;
+        const output = [];
+        for (const file of files) {
+            if (input.filters?.language && file.language !== input.filters.language) {
+                continue;
+            }
+            const chunks = this.chunksByFile.get(file.file_id) ?? [];
+            for (const chunk of chunks) {
+                if (input.filters?.path_prefix && !chunk.path.startsWith(input.filters.path_prefix)) {
+                    continue;
+                }
+                if (globRegex && !globRegex.test(chunk.path)) {
+                    continue;
+                }
+                output.push({
+                    chunk_id: `chk_${sha256(`${file.file_id}:${chunk.hash}`)}`,
+                    file_id: file.file_id,
+                    path: chunk.path,
+                    start_line: chunk.start_line,
+                    end_line: chunk.end_line,
+                    snippet: chunk.snippet,
+                    ...(file.language ? { language: file.language } : {}),
+                    ...(chunk.generated ? { generated: chunk.generated } : {}),
+                    updated_at: chunk.updated_at,
+                    embedding: [...(chunk.embedding ?? pseudoEmbedding(chunk.snippet))]
+                });
+            }
+        }
+        return output;
+    }
+}
+function compileGlob(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const pattern = `^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`;
+    return new RegExp(pattern);
+}
+export class RetrievalCore {
+    store;
+    cache;
+    cacheTtlSeconds;
+    embeddingProvider;
+    embeddingDescriptor;
+    observability;
+    scoringConfig;
+    scoringProfileId;
+    scoringConfigChecksum;
+    enhancerConfig;
+    chunkingConfig;
+    enhancerDecisionTraceEnabled;
+    cacheHits = 0;
+    cacheMisses = 0;
+    constructor(store, cache, options) {
+        this.store = store;
+        this.cache = cache;
+        this.cacheTtlSeconds = options?.cacheTtlSeconds ?? 60;
+        this.embeddingProvider = options?.embeddingProvider ?? new DeterministicEmbeddingProvider();
+        this.embeddingDescriptor = normalizeEmbeddingDescriptor(options?.embeddingDescriptor ?? resolveEmbeddingDescriptor(this.embeddingProvider));
+        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.enhancerConfig = mergeRetrievalEnhancerConfig(DEFAULT_RETRIEVAL_ENHANCER_CONFIG, options?.enhancerConfig);
+        this.chunkingConfig = mergeRetrievalChunkingConfig(DEFAULT_RETRIEVAL_CHUNKING_CONFIG, options?.chunkingConfig);
+        this.enhancerDecisionTraceEnabled = Boolean(options?.enhancerDecisionTraceEnabled);
+    }
+    async indexArtifact(artifact) {
+        const existingIndex = await this.store.getIndexByVersion({
+            tenant_id: artifact.tenant_id,
+            workspace_id: artifact.workspace_id,
+            index_version: artifact.index_version
+        });
+        if (existingIndex?.status === "ready") {
+            return {
+                workspace_id: artifact.workspace_id,
+                index_version: artifact.index_version,
+                status: "ready",
+                counts: {
+                    added: 0,
+                    modified: 0,
+                    deleted: 0,
+                    unchanged: 0,
+                    skipped: 0
+                },
+                skipped_files: [],
+                warnings: []
+            };
+        }
+        const previousReadyIndex = await this.store.getLatestReadyIndex({
+            tenant_id: artifact.tenant_id,
+            workspace_id: artifact.workspace_id
+        });
+        const nextIndex = existingIndex
+            ? existingIndex
+            : await this.store.createIndexVersion({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_version: artifact.index_version,
+                status: "indexing"
+            });
+        if (existingIndex) {
+            await this.store.markIndexStatus({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: existingIndex.index_id,
+                status: "indexing"
+            });
+            await this.store.resetIndexContent({
+                tenant_id: artifact.tenant_id,
+                index_id: existingIndex.index_id
+            });
+        }
+        const normalizedFiles = artifact.files.map((file) => ({
+            ...file,
+            path: normalizePath(file.path)
+        }));
+        const skipped = [];
+        const warnings = [];
+        const candidateFiles = normalizedFiles.filter((file) => {
+            const sizeBytes = Buffer.byteLength(file.content, "utf8");
+            if (file.binary) {
+                skipped.push({ path: file.path, reason: "binary file" });
+                return false;
+            }
+            if (sizeBytes > MAX_FILE_SIZE_BYTES) {
+                skipped.push({ path: file.path, reason: "max file size exceeded" });
+                return false;
+            }
+            const secretMatches = detectSecretMatches(file.content);
+            if (secretMatches.length > 0) {
+                skipped.push({ path: file.path, reason: `secret scan matched (${secretMatches.join(", ")})` });
+                warnings.push({
+                    path: file.path,
+                    reason: `excluded by default secret scanner: ${secretMatches.join(", ")}`,
+                    category: "secret_exclusion"
+                });
+                return false;
+            }
+            return true;
+        });
+        const previousHashes = new Map();
+        if (previousReadyIndex) {
+            const previousFiles = await this.store.getFilesByIndex({
+                tenant_id: artifact.tenant_id,
+                index_id: previousReadyIndex.index_id
+            });
+            for (const file of previousFiles) {
+                previousHashes.set(file.repo_path, file.content_hash);
+            }
+        }
+        const nextHashes = new Map();
+        const changedFiles = [];
+        let added = 0;
+        let modified = 0;
+        let unchanged = 0;
+        for (const file of candidateFiles) {
+            const hash = sha256(file.content);
+            nextHashes.set(file.path, hash);
+            const old = previousHashes.get(file.path);
+            if (!old) {
+                added += 1;
+                changedFiles.push(file);
+            }
+            else if (old !== hash) {
+                modified += 1;
+                changedFiles.push(file);
+            }
+            else {
+                unchanged += 1;
+            }
+        }
+        let deleted = 0;
+        for (const oldPath of previousHashes.keys()) {
+            if (!nextHashes.has(oldPath)) {
+                deleted += 1;
+            }
+        }
+        try {
+            await this.store.saveIndexMetadata?.({
+                tenant_id: artifact.tenant_id,
+                index_id: nextIndex.index_id,
+                embedding_provider: this.embeddingDescriptor.provider,
+                embedding_model: this.embeddingDescriptor.model,
+                embedding_dimensions: this.embeddingDescriptor.dimensions,
+                embedding_version: this.embeddingDescriptor.version,
+                chunking_strategy: this.chunkingConfig.strategy,
+                chunking_fallback_strategy: this.chunkingConfig.fallback_strategy
+            });
+            this.observability.logger.info("index embedding metadata persisted", {
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: nextIndex.index_id,
+                embedding_provider: this.embeddingDescriptor.provider,
+                embedding_model: this.embeddingDescriptor.model ?? "unknown",
+                embedding_dimensions: this.embeddingDescriptor.dimensions
+            });
+            if (previousReadyIndex) {
+                for (const [path, hash] of nextHashes) {
+                    const old = previousHashes.get(path);
+                    if (old && old === hash) {
+                        await this.store.copyFileFromIndex({
+                            tenant_id: artifact.tenant_id,
+                            source_index_id: previousReadyIndex.index_id,
+                            target_index_id: nextIndex.index_id,
+                            repo_path: path
+                        });
+                    }
+                }
+            }
+            if (this.chunkingConfig.strategy === "language_aware") {
+                const parserAvailabilitySnapshot = getChunkingParserAvailabilitySnapshot({
+                    enabled_languages: this.chunkingConfig.enabled_languages
+                });
+                for (const availability of parserAvailabilitySnapshot) {
+                    this.observability.metrics.gauge("index_chunking_parser_availability", availability.status === "available" ? 1 : 0, {
+                        tenant_id: artifact.tenant_id,
+                        language: availability.language,
+                        status: availability.status
+                    });
+                }
+                this.observability.logger.info("chunking parser availability snapshot", {
+                    tenant_id: artifact.tenant_id,
+                    workspace_id: artifact.workspace_id,
+                    index_id: nextIndex.index_id,
+                    snapshot: parserAvailabilitySnapshot
+                });
+            }
+            for (const file of changedFiles) {
+                const chunkBuild = buildChunks(file, this.chunkingConfig);
+                const chunks = chunkBuild.chunks;
+                const chunkLanguage = chunkBuild.language ?? file.language ?? "unknown";
+                this.observability.metrics.increment("index_chunking_strategy_total", 1, {
+                    tenant_id: artifact.tenant_id,
+                    strategy: chunkBuild.strategy,
+                    language: chunkLanguage,
+                    reason: chunkBuild.fallback_reason ?? "none"
+                });
+                if (chunkBuild.fallback_reason) {
+                    this.observability.metrics.increment("index_chunking_fallback_total", 1, {
+                        tenant_id: artifact.tenant_id,
+                        reason: chunkBuild.fallback_reason,
+                        language: chunkLanguage
+                    });
+                }
+                if (typeof chunkBuild.parse_latency_ms === "number") {
+                    this.observability.metrics.observe("index_chunk_parse_latency_ms", chunkBuild.parse_latency_ms, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage
+                    });
+                }
+                if (typeof chunkBuild.language_aware_attempt_latency_ms === "number") {
+                    this.observability.metrics.observe("index_chunk_language_aware_attempt_latency_ms", chunkBuild.language_aware_attempt_latency_ms, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage,
+                        outcome: chunkBuild.fallback_reason ? "fallback" : "success"
+                    });
+                }
+                if (typeof chunkBuild.fallback_path_latency_ms === "number" && chunkBuild.fallback_reason) {
+                    this.observability.metrics.observe("index_chunk_fallback_path_latency_ms", chunkBuild.fallback_path_latency_ms, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage,
+                        reason: chunkBuild.fallback_reason
+                    });
+                }
+                const estimatedEmbeddingTokens = chunks.reduce((sum, chunk) => sum + tokenize(chunk.snippet).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),
+                        purpose: "index"
+                    });
+                if (embeddings.length !== chunks.length) {
+                    throw new RetrievalError("UPSTREAM_FAILURE", `embedding provider returned ${embeddings.length} vectors for ${chunks.length} indexed chunks`);
+                }
+                const contentHash = sha256(file.content);
+                const sizeBytes = Buffer.byteLength(file.content, "utf8");
+                const chunkEmbeddings = chunks.map((chunk, index) => {
+                    const embedding = embeddings[index];
+                    if (!isFiniteNumberArray(embedding)) {
+                        throw new RetrievalError("UPSTREAM_FAILURE", `embedding provider returned a non-numeric vector for ${file.path}:${chunk.start_line}-${chunk.end_line}`);
+                    }
+                    if (embedding.length !== this.embeddingDescriptor.dimensions) {
+                        this.observability.metrics.increment("index_embedding_dimension_mismatch_total", 1, {
+                            tenant_id: artifact.tenant_id,
+                            expected_dimensions: this.embeddingDescriptor.dimensions,
+                            actual_dimensions: embedding.length
+                        });
+                        this.observability.logger.warn("embedding dimensions mismatch provider descriptor; failing index build", {
+                            tenant_id: artifact.tenant_id,
+                            workspace_id: artifact.workspace_id,
+                            path: file.path,
+                            expected_dimensions: this.embeddingDescriptor.dimensions,
+                            actual_dimensions: embedding.length
+                        });
+                        throw new RetrievalError("UPSTREAM_FAILURE", `embedding dimension mismatch for ${file.path}; expected ${this.embeddingDescriptor.dimensions}, received ${embedding.length}`);
+                    }
+                    return embedding;
+                });
+                const fileRow = await this.store.upsertFile({
+                    tenant_id: artifact.tenant_id,
+                    index_id: nextIndex.index_id,
+                    repo_path: file.path,
+                    content_hash: contentHash,
+                    size_bytes: sizeBytes,
+                    language: file.language,
+                    updated_at: file.updated_at ?? new Date().toISOString()
+                });
+                await this.store.replaceFileChunks({
+                    tenant_id: artifact.tenant_id,
+                    file_id: fileRow.file_id,
+                    repo_path: file.path,
+                    chunks: chunks.map((chunk, index) => ({
+                        start_line: chunk.start_line,
+                        end_line: chunk.end_line,
+                        snippet: chunk.snippet,
+                        embedding: chunkEmbeddings[index],
+                        generated: chunk.generated,
+                        updated_at: chunk.updated_at
+                    }))
+                });
+            }
+            if (artifact.manifest) {
+                await this.store.saveManifest({
+                    index_id: nextIndex.index_id,
+                    object_key: artifact.manifest.object_key,
+                    checksum: artifact.manifest.checksum
+                });
+            }
+            await this.store.markIndexStatus({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: nextIndex.index_id,
+                status: "ready"
+            });
+            await this.cache.invalidateWorkspace(artifact.workspace_id);
+            return {
+                workspace_id: artifact.workspace_id,
+                index_version: artifact.index_version,
+                status: "ready",
+                counts: {
+                    added,
+                    modified,
+                    deleted,
+                    unchanged,
+                    skipped: skipped.length
+                },
+                skipped_files: skipped,
+                warnings
+            };
+        }
+        catch (error) {
+            await this.store.markIndexStatus({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: nextIndex.index_id,
+                status: "failed"
+            });
+            throw error;
+        }
+    }
+    async indexArtifactDelta(artifact) {
+        const existingIndex = await this.store.getIndexByVersion({
+            tenant_id: artifact.tenant_id,
+            workspace_id: artifact.workspace_id,
+            index_version: artifact.index_version
+        });
+        if (existingIndex?.status === "ready") {
+            return {
+                workspace_id: artifact.workspace_id,
+                index_version: artifact.index_version,
+                status: "ready",
+                counts: {
+                    added: 0,
+                    modified: 0,
+                    deleted: 0,
+                    unchanged: 0,
+                    skipped: 0
+                },
+                skipped_files: [],
+                warnings: []
+            };
+        }
+        const baseIndex = artifact.base_index_version
+            ? await this.store.getIndexByVersion({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_version: artifact.base_index_version
+            })
+            : await this.store.getLatestReadyIndex({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id
+            });
+        if (artifact.base_index_version && (!baseIndex || baseIndex.status !== "ready")) {
+            throw new RetrievalError("INVALID_ARGUMENT", `base index version ${artifact.base_index_version} is not ready for workspace ${artifact.workspace_id}`);
+        }
+        const nextIndex = existingIndex
+            ? existingIndex
+            : await this.store.createIndexVersion({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_version: artifact.index_version,
+                status: "indexing"
+            });
+        if (existingIndex) {
+            await this.store.markIndexStatus({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: existingIndex.index_id,
+                status: "indexing"
+            });
+            await this.store.resetIndexContent({
+                tenant_id: artifact.tenant_id,
+                index_id: existingIndex.index_id
+            });
+        }
+        const dedupedUpsertFiles = new Map();
+        for (const file of artifact.upsert_files) {
+            const normalizedPath = normalizePath(file.path);
+            dedupedUpsertFiles.set(normalizedPath, {
+                ...file,
+                path: normalizedPath
+            });
+        }
+        const normalizedUpsertFiles = [...dedupedUpsertFiles.values()];
+        const skipped = [];
+        const warnings = [];
+        const candidateFiles = normalizedUpsertFiles.filter((file) => {
+            const sizeBytes = Buffer.byteLength(file.content, "utf8");
+            if (file.binary) {
+                skipped.push({ path: file.path, reason: "binary file" });
+                return false;
+            }
+            if (sizeBytes > MAX_FILE_SIZE_BYTES) {
+                skipped.push({ path: file.path, reason: "max file size exceeded" });
+                return false;
+            }
+            const secretMatches = detectSecretMatches(file.content);
+            if (secretMatches.length > 0) {
+                skipped.push({ path: file.path, reason: `secret scan matched (${secretMatches.join(", ")})` });
+                warnings.push({
+                    path: file.path,
+                    reason: `excluded by default secret scanner: ${secretMatches.join(", ")}`,
+                    category: "secret_exclusion"
+                });
+                return false;
+            }
+            return true;
+        });
+        const baseHashes = new Map();
+        if (baseIndex?.status === "ready") {
+            const baseFiles = await this.store.getFilesByIndex({
+                tenant_id: artifact.tenant_id,
+                index_id: baseIndex.index_id
+            });
+            for (const file of baseFiles) {
+                baseHashes.set(file.repo_path, file.content_hash);
+            }
+        }
+        const changedFiles = [];
+        let added = 0;
+        let modified = 0;
+        for (const file of candidateFiles) {
+            const hash = sha256(file.content);
+            const old = baseHashes.get(file.path);
+            if (!old) {
+                added += 1;
+                changedFiles.push(file);
+            }
+            else if (old !== hash) {
+                modified += 1;
+                changedFiles.push(file);
+            }
+        }
+        const changedPaths = new Set(changedFiles.map((file) => file.path));
+        const deletedPaths = new Set(artifact.deleted_paths
+            .map((path) => normalizePath(path))
+            .filter((path) => baseHashes.has(path) && !changedPaths.has(path)));
+        const copyPaths = [];
+        for (const path of baseHashes.keys()) {
+            if (deletedPaths.has(path) || changedPaths.has(path)) {
+                continue;
+            }
+            copyPaths.push(path);
+        }
+        const unchanged = copyPaths.length;
+        const deleted = deletedPaths.size;
+        try {
+            await this.store.saveIndexMetadata?.({
+                tenant_id: artifact.tenant_id,
+                index_id: nextIndex.index_id,
+                embedding_provider: this.embeddingDescriptor.provider,
+                embedding_model: this.embeddingDescriptor.model,
+                embedding_dimensions: this.embeddingDescriptor.dimensions,
+                embedding_version: this.embeddingDescriptor.version,
+                chunking_strategy: this.chunkingConfig.strategy,
+                chunking_fallback_strategy: this.chunkingConfig.fallback_strategy
+            });
+            this.observability.logger.info("index embedding metadata persisted", {
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: nextIndex.index_id,
+                embedding_provider: this.embeddingDescriptor.provider,
+                embedding_model: this.embeddingDescriptor.model ?? "unknown",
+                embedding_dimensions: this.embeddingDescriptor.dimensions
+            });
+            if (baseIndex?.status === "ready") {
+                for (const path of copyPaths) {
+                    await this.store.copyFileFromIndex({
+                        tenant_id: artifact.tenant_id,
+                        source_index_id: baseIndex.index_id,
+                        target_index_id: nextIndex.index_id,
+                        repo_path: path
+                    });
+                }
+            }
+            if (this.chunkingConfig.strategy === "language_aware") {
+                const parserAvailabilitySnapshot = getChunkingParserAvailabilitySnapshot({
+                    enabled_languages: this.chunkingConfig.enabled_languages
+                });
+                for (const availability of parserAvailabilitySnapshot) {
+                    this.observability.metrics.gauge("index_chunking_parser_availability", availability.status === "available" ? 1 : 0, {
+                        tenant_id: artifact.tenant_id,
+                        language: availability.language,
+                        status: availability.status
+                    });
+                }
+                this.observability.logger.info("chunking parser availability snapshot", {
+                    tenant_id: artifact.tenant_id,
+                    workspace_id: artifact.workspace_id,
+                    index_id: nextIndex.index_id,
+                    snapshot: parserAvailabilitySnapshot
+                });
+            }
+            for (const file of changedFiles) {
+                const chunkBuild = buildChunks(file, this.chunkingConfig);
+                const chunks = chunkBuild.chunks;
+                const chunkLanguage = chunkBuild.language ?? file.language ?? "unknown";
+                this.observability.metrics.increment("index_chunking_strategy_total", 1, {
+                    tenant_id: artifact.tenant_id,
+                    strategy: chunkBuild.strategy,
+                    language: chunkLanguage,
+                    reason: chunkBuild.fallback_reason ?? "none"
+                });
+                if (chunkBuild.fallback_reason) {
+                    this.observability.metrics.increment("index_chunking_fallback_total", 1, {
+                        tenant_id: artifact.tenant_id,
+                        reason: chunkBuild.fallback_reason,
+                        language: chunkLanguage
+                    });
+                }
+                if (typeof chunkBuild.parse_latency_ms === "number") {
+                    this.observability.metrics.observe("index_chunk_parse_latency_ms", chunkBuild.parse_latency_ms, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage
+                    });
+                }
+                if (typeof chunkBuild.language_aware_attempt_latency_ms === "number") {
+                    this.observability.metrics.observe("index_chunk_language_aware_attempt_latency_ms", chunkBuild.language_aware_attempt_latency_ms, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage,
+                        outcome: chunkBuild.fallback_reason ? "fallback" : "success"
+                    });
+                }
+                if (typeof chunkBuild.fallback_path_latency_ms === "number" && chunkBuild.fallback_reason) {
+                    this.observability.metrics.observe("index_chunk_fallback_path_latency_ms", chunkBuild.fallback_path_latency_ms, {
+                        tenant_id: artifact.tenant_id,
+                        language: chunkLanguage,
+                        reason: chunkBuild.fallback_reason
+                    });
+                }
+                const estimatedEmbeddingTokens = chunks.reduce((sum, chunk) => sum + tokenize(chunk.snippet).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),
+                        purpose: "index"
+                    });
+                if (embeddings.length !== chunks.length) {
+                    throw new RetrievalError("UPSTREAM_FAILURE", `embedding provider returned ${embeddings.length} vectors for ${chunks.length} indexed chunks`);
+                }
+                const contentHash = sha256(file.content);
+                const sizeBytes = Buffer.byteLength(file.content, "utf8");
+                const chunkEmbeddings = chunks.map((chunk, index) => {
+                    const embedding = embeddings[index];
+                    if (!isFiniteNumberArray(embedding)) {
+                        throw new RetrievalError("UPSTREAM_FAILURE", `embedding provider returned a non-numeric vector for ${file.path}:${chunk.start_line}-${chunk.end_line}`);
+                    }
+                    if (embedding.length !== this.embeddingDescriptor.dimensions) {
+                        this.observability.metrics.increment("index_embedding_dimension_mismatch_total", 1, {
+                            tenant_id: artifact.tenant_id,
+                            expected_dimensions: this.embeddingDescriptor.dimensions,
+                            actual_dimensions: embedding.length
+                        });
+                        this.observability.logger.warn("embedding dimensions mismatch provider descriptor; failing index build", {
+                            tenant_id: artifact.tenant_id,
+                            workspace_id: artifact.workspace_id,
+                            path: file.path,
+                            expected_dimensions: this.embeddingDescriptor.dimensions,
+                            actual_dimensions: embedding.length
+                        });
+                        throw new RetrievalError("UPSTREAM_FAILURE", `embedding dimension mismatch for ${file.path}; expected ${this.embeddingDescriptor.dimensions}, received ${embedding.length}`);
+                    }
+                    return embedding;
+                });
+                const fileRow = await this.store.upsertFile({
+                    tenant_id: artifact.tenant_id,
+                    index_id: nextIndex.index_id,
+                    repo_path: file.path,
+                    content_hash: contentHash,
+                    size_bytes: sizeBytes,
+                    language: file.language,
+                    updated_at: file.updated_at ?? new Date().toISOString()
+                });
+                await this.store.replaceFileChunks({
+                    tenant_id: artifact.tenant_id,
+                    file_id: fileRow.file_id,
+                    repo_path: file.path,
+                    chunks: chunks.map((chunk, index) => ({
+                        start_line: chunk.start_line,
+                        end_line: chunk.end_line,
+                        snippet: chunk.snippet,
+                        embedding: chunkEmbeddings[index],
+                        generated: chunk.generated,
+                        updated_at: chunk.updated_at
+                    }))
+                });
+            }
+            await this.store.markIndexStatus({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: nextIndex.index_id,
+                status: "ready"
+            });
+            await this.cache.invalidateWorkspace(artifact.workspace_id);
+            return {
+                workspace_id: artifact.workspace_id,
+                index_version: artifact.index_version,
+                status: "ready",
+                counts: {
+                    added,
+                    modified,
+                    deleted,
+                    unchanged,
+                    skipped: skipped.length
+                },
+                skipped_files: skipped,
+                warnings
+            };
+        }
+        catch (error) {
+            await this.store.markIndexStatus({
+                tenant_id: artifact.tenant_id,
+                workspace_id: artifact.workspace_id,
+                index_id: nextIndex.index_id,
+                status: "failed"
+            });
+            throw error;
+        }
+    }
+    async getIndexVersion(input) {
+        const existing = await this.store.getIndexByVersion({
+            tenant_id: input.tenant_id,
+            workspace_id: input.workspace_id,
+            index_version: input.index_version
+        });
+        if (!existing) {
+            return undefined;
+        }
+        return {
+            index_id: existing.index_id,
+            status: existing.status
+        };
+    }
+    async searchContext(input) {
+        const searchStartedAt = Date.now();
+        const index = await this.store.getLatestReadyIndex({
+            tenant_id: input.tenant_id,
+            workspace_id: input.workspace_id
+        });
+        if (!index) {
+            throw new RetrievalError("NOT_FOUND", "No ready index found for workspace. Run initial batch-upload push.");
+        }
+        const indexMetadata = await this.store.getIndexMetadata?.({
+            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);
+        if (!indexMetadata) {
+            this.observability.metrics.increment("retrieval_embedding_metadata_mismatch_total", 1, {
+                reason: "metadata_missing"
+            });
+            this.observability.logger.warn("index metadata missing embedding configuration; reindex required", {
+                tenant_id: input.tenant_id,
+                workspace_id: input.workspace_id,
+                index_id: index.index_id,
+                reindex_required: true
+            });
+            throw new RetrievalError("INVALID_ARGUMENT", "index embedding metadata missing; reindex required with current embedding model and dimensions.");
+        }
+        const expectedProvider = this.embeddingDescriptor.provider;
+        const expectedModel = this.embeddingDescriptor.model ?? "";
+        const expectedDimensions = this.embeddingDescriptor.dimensions;
+        const actualProvider = indexMetadata.embedding_provider;
+        const actualModel = indexMetadata.embedding_model ?? "";
+        const actualDimensions = indexMetadata.embedding_dimensions;
+        let mismatchReason;
+        if (actualProvider !== expectedProvider) {
+            mismatchReason = "provider_mismatch";
+        }
+        else if (actualModel !== expectedModel) {
+            mismatchReason = "model_mismatch";
+        }
+        else if (actualDimensions !== expectedDimensions) {
+            mismatchReason = "dimension_mismatch";
+        }
+        if (mismatchReason) {
+            this.observability.metrics.increment("retrieval_embedding_metadata_mismatch_total", 1, {
+                reason: mismatchReason
+            });
+            this.observability.logger.warn("embedding compatibility mismatch detected; reindex required", {
+                tenant_id: input.tenant_id,
+                workspace_id: input.workspace_id,
+                index_id: index.index_id,
+                reason: mismatchReason,
+                expected_provider: expectedProvider,
+                expected_model: expectedModel || "unknown",
+                expected_dimensions: expectedDimensions,
+                actual_provider: actualProvider,
+                actual_model: actualModel || "unknown",
+                actual_dimensions: actualDimensions,
+                reindex_required: true
+            });
+            throw new RetrievalError("INVALID_ARGUMENT", "embedding configuration mismatch; reindex required with current embedding model and dimensions.");
+        }
+        const queryEmbeddings = await this.embeddingProvider.embed({
+            texts: [query],
+            purpose: "query"
+        });
+        if (queryEmbeddings.length !== 1 || !isFiniteNumberArray(queryEmbeddings[0])) {
+            throw new RetrievalError("UPSTREAM_FAILURE", "embedding provider returned an invalid query embedding response");
+        }
+        const queryEmbedding = queryEmbeddings[0];
+        if (queryEmbedding.length !== this.embeddingDescriptor.dimensions) {
+            throw new RetrievalError("UPSTREAM_FAILURE", `embedding provider returned query embedding dimensions ${queryEmbedding.length}; expected ${this.embeddingDescriptor.dimensions}`);
+        }
+        const queryTokens = tokenize(query);
+        const cacheKey = buildQueryCacheKey({
+            workspace_id: input.workspace_id,
+            index_version: index.index_version,
+            query,
+            top_k: topK,
+            filters: input.request.filters
+        });
+        const cached = await this.cache.get(cacheKey);
+        if (cached) {
+            this.cacheHits += 1;
+            const ratio = this.cacheHits / Math.max(1, this.cacheHits + this.cacheMisses);
+            this.observability.metrics.gauge("retrieval_cache_hit_ratio", ratio, {});
+            return { ...cached, trace_id: input.trace_id };
+        }
+        this.cacheMisses += 1;
+        const ratio = this.cacheHits / Math.max(1, this.cacheHits + this.cacheMisses);
+        this.observability.metrics.gauge("retrieval_cache_hit_ratio", ratio, {});
+        const candidates = await this.observability.tracing.withSpan("retrieval.candidate_generation", {
+            trace_id: input.trace_id,
+            tenant_id: input.tenant_id,
+            workspace_id: input.workspace_id
+        }, async () => {
+            let ranked;
+            if (this.store.rankChunksByIndex) {
+                ranked = await this.store.rankChunksByIndex({
+                    tenant_id: input.tenant_id,
+                    index_id: index.index_id,
+                    query,
+                    query_embedding: queryEmbedding,
+                    query_tokens: queryTokens,
+                    top_k: candidatePoolTopK,
+                    candidate_weights: this.scoringConfig.candidate_weights,
+                    filters: input.request.filters
+                });
+            }
+            const output = ranked && ranked.length > 0
+                ? ranked
+                    .map((candidate) => {
+                    let score = candidate.score;
+                    score += pathQualityBias(candidate.path, queryTokens, this.scoringConfig, query);
+                    if (looksLowInformation(candidate.snippet)) {
+                        score -= this.scoringConfig.rerank.low_information_penalty;
+                    }
+                    const reason = chooseReason({
+                        lexical: candidate.lexical_score,
+                        path_match: candidate.path_match,
+                        recency_boosted: candidate.recency_boosted
+                    });
+                    return {
+                        path: candidate.path,
+                        start_line: candidate.start_line,
+                        end_line: candidate.end_line,
+                        snippet: candidate.snippet,
+                        score,
+                        reason
+                    };
+                })
+                    .filter((candidate) => candidate.end_line >= candidate.start_line)
+                    .sort((a, b) => b.score - a.score)
+                : (await this.store.listChunksByIndex({
+                    tenant_id: input.tenant_id,
+                    index_id: index.index_id,
+                    filters: input.request.filters
+                }))
+                    .map((chunk) => {
+                    const haystack = `${chunk.path}\n${chunk.snippet}`;
+                    const l = lexicalScore(query, haystack);
+                    const v = cosineSimilarity(queryEmbedding, chunk.embedding);
+                    const pathMatch = queryTokens.some((token) => chunk.path.toLowerCase().includes(token));
+                    const recencyBoost = Date.now() - new Date(chunk.updated_at).getTime() < 14 * 24 * 3600 * 1000;
+                    const candidateWeights = this.scoringConfig.candidate_weights;
+                    let score = l * candidateWeights.lexical_weight + v * candidateWeights.vector_weight;
+                    if (pathMatch) {
+                        score += candidateWeights.path_match_boost;
+                    }
+                    if (recencyBoost) {
+                        score += candidateWeights.recency_boost;
+                    }
+                    if (chunk.generated) {
+                        score -= candidateWeights.generated_penalty;
+                    }
+                    score += pathQualityBias(chunk.path, queryTokens, this.scoringConfig, query);
+                    if (looksLowInformation(chunk.snippet)) {
+                        score -= this.scoringConfig.rerank.low_information_penalty;
+                    }
+                    const reason = chooseReason({ lexical: l, path_match: pathMatch, recency_boosted: recencyBoost });
+                    return {
+                        path: chunk.path,
+                        start_line: chunk.start_line,
+                        end_line: chunk.end_line,
+                        snippet: chunk.snippet,
+                        score,
+                        reason
+                    };
+                })
+                    .filter((candidate) => candidate.end_line >= candidate.start_line)
+                    .sort((a, b) => b.score - a.score);
+            this.observability.metrics.observe("retrieval_candidates_count", output.length, {
+                channel: "hybrid",
+                retrieval_profile_id: this.scoringProfileId
+            });
+            return output;
+        });
+        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 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];
+            while (output.length < topK && available.length > 0) {
+                let bestIndex = -1;
+                let bestAdjustedScore = Number.NEGATIVE_INFINITY;
+                let bestRawScore = Number.NEGATIVE_INFINITY;
+                for (let i = 0; i < available.length; i += 1) {
+                    const candidate = available[i];
+                    if (!candidate) {
+                        continue;
+                    }
+                    const key = `${candidate.path}:${candidate.start_line}:${candidate.end_line}`;
+                    if (seen.has(key)) {
+                        continue;
+                    }
+                    const pathCount = pathCounts.get(candidate.path) ?? 0;
+                    if (pathCount >= maxChunksPerPath) {
+                        continue;
+                    }
+                    const directoryKey = parentDirectory(candidate.path).toLowerCase();
+                    const extensionKey = fileExtension(candidate.path);
+                    const adjustedScore = candidate.score -
+                        (directoryCounts.get(directoryKey) ?? 0) * this.scoringConfig.rerank.same_directory_penalty -
+                        (extensionCounts.get(extensionKey) ?? 0) * this.scoringConfig.rerank.same_extension_penalty;
+                    const currentBest = bestIndex >= 0 ? available[bestIndex] : undefined;
+                    const isBetter = adjustedScore > bestAdjustedScore + 1e-9 ||
+                        (Math.abs(adjustedScore - bestAdjustedScore) <= 1e-9 &&
+                            (candidate.score > bestRawScore + 1e-9 ||
+                                (Math.abs(candidate.score - bestRawScore) <= 1e-9 &&
+                                    (!currentBest ||
+                                        candidate.path.localeCompare(currentBest.path) < 0 ||
+                                        (candidate.path === currentBest.path &&
+                                            (candidate.start_line < currentBest.start_line ||
+                                                (candidate.start_line === currentBest.start_line &&
+                                                    candidate.end_line < currentBest.end_line)))))));
+                    if (isBetter) {
+                        bestAdjustedScore = adjustedScore;
+                        bestRawScore = candidate.score;
+                        bestIndex = i;
+                    }
+                }
+                if (bestIndex < 0) {
+                    break;
+                }
+                const selected = available.splice(bestIndex, 1)[0];
+                if (!selected) {
+                    break;
+                }
+                const selectedKey = `${selected.path}:${selected.start_line}:${selected.end_line}`;
+                seen.add(selectedKey);
+                pathCounts.set(selected.path, (pathCounts.get(selected.path) ?? 0) + 1);
+                const selectedDirectory = parentDirectory(selected.path).toLowerCase();
+                const selectedExtension = fileExtension(selected.path);
+                directoryCounts.set(selectedDirectory, (directoryCounts.get(selectedDirectory) ?? 0) + 1);
+                extensionCounts.set(selectedExtension, (extensionCounts.get(selectedExtension) ?? 0) + 1);
+                output.push(selected);
+            }
+            return output;
+        });
+        const output = {
+            trace_id: input.trace_id,
+            results: deduped,
+            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, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        this.observability.logger.info("search_context completed", {
+            trace_id: input.trace_id,
+            tenant_id: input.tenant_id,
+            workspace_id: input.workspace_id,
+            latency_ms: output.search_metadata.latency_ms,
+            result_count: output.results.length,
+            retrieval_profile_id: this.scoringProfileId,
+            retrieval_profile_checksum: this.scoringConfigChecksum
+        });
+        await this.cache.set(cacheKey, output, this.cacheTtlSeconds);
+        return output;
+    }
+    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 negativePreferences = detectNegativePathPreferences(`${input.request.prompt}\n${input.request.conversation_history.map((entry) => entry.content).join("\n")}`);
+        const intentPolicy = resolveEnhancerIntentPolicy({
+            query_intent: queryIntent,
+            enhancer_config: this.enhancerConfig,
+            negative_preferences: negativePreferences
+        });
+        const rerankTimeoutMs = queryIntent === "symbol-heavy"
+            ? Math.max(20, Math.floor(this.enhancerConfig.rerank_timeout_ms * 0.75))
+            : this.enhancerConfig.rerank_timeout_ms;
+        let searchResults = [];
+        let retrievalQuery = "";
+        let lowConfidenceTriggered = false;
+        let fallbackTriggered = false;
+        let fallbackReason = null;
+        let confidenceSignals;
+        let queryExpansionMs = 0;
+        let expandedHintCount = 0;
+        let candidateCountPreRerank = 0;
+        let candidateCountPostRerank = 0;
+        let rerankMs = 0;
+        let strongAnchorBypassUsed = false;
+        let rerankUsed = false;
+        if (!input.request.project_root_path || !input.workspace_id) {
+            warnings.push("Workspace context missing. Running text-only enhancement mode.");
+            fallbackTriggered = true;
+            fallbackReason = "workspace_context_missing";
+        }
+        else {
+            try {
+                const expansionStartedAt = Date.now();
+                const expandedQuery = buildEnhancerRetrievalQuery(input.request.prompt, input.request.conversation_history, {
+                    maxExpansionHints: intentPolicy.max_expansion_hints,
+                    queryIntent
+                });
+                queryExpansionMs = Date.now() - expansionStartedAt;
+                retrievalQuery = expandedQuery.query;
+                expandedHintCount = expandedQuery.expanded_hint_count;
+                const retrieval = await this.searchContext({
+                    trace_id: input.trace_id,
+                    tenant_id: input.tenant_id,
+                    workspace_id: input.workspace_id,
+                    request: {
+                        project_root_path: input.request.project_root_path,
+                        query: retrievalQuery,
+                        top_k: MAX_TOP_K
+                    }
+                });
+                const budgetedResults = trimToContextBudget(retrieval.results);
+                const dedupedByPath = dedupeEnhancerCandidatesByPath(budgetedResults);
+                const collapsedByDirectory = collapseEnhancerCandidatesByDirectory(dedupedByPath, intentPolicy.max_candidates_per_directory_pre_rerank);
+                const filteredCandidates = applyEnhancerIntentPathFiltering(collapsedByDirectory, {
+                    intent,
+                    negative_preferences: negativePreferences,
+                    strict_impl_only_filtering: intentPolicy.strict_impl_only_filtering
+                });
+                searchResults = filteredCandidates.slice(0, intentPolicy.max_candidates_pre_rerank);
+                candidateCountPreRerank = searchResults.length;
+                const shouldSkipRerankForStrongAnchors = shouldBypassEnhancerRerankForAnchors({
+                    query_intent: queryIntent,
+                    prompt: input.request.prompt,
+                    history: input.request.conversation_history,
+                    results: searchResults,
+                    negative_preferences: negativePreferences
+                });
+                strongAnchorBypassUsed = shouldSkipRerankForStrongAnchors;
+                confidenceSignals = evaluateEnhancerConfidence({
+                    prompt: input.request.prompt,
+                    retrieval_query: retrievalQuery,
+                    query_intent: queryIntent,
+                    results: filteredCandidates.slice(0, Math.max(intentPolicy.max_candidates_pre_rerank * 2, 6))
+                });
+                if (!shouldSkipRerankForStrongAnchors && confidenceSignals.low_confidence) {
+                    lowConfidenceTriggered = true;
+                    rerankUsed = true;
+                    warnings.push(ENHANCER_LOW_CONFIDENCE_WARNING);
+                    const rerankStartedAt = Date.now();
+                    let reranked;
+                    try {
+                        reranked = await runWithTimeout({
+                            timeout_ms: rerankTimeoutMs,
+                            fn: () => rankEnhancerResultsForConfidence({
+                                results: searchResults,
+                                intent,
+                                query_intent: queryIntent,
+                                negative_preferences: negativePreferences,
+                                prompt: input.request.prompt,
+                                retrieval_query: retrievalQuery
+                            })
+                        });
+                    }
+                    catch {
+                        fallbackTriggered = true;
+                        fallbackReason = "rerank_timeout";
+                        warnings.push("Enhancer rerank timeout; applied deterministic fallback ranking.");
+                        reranked = deterministicEnhancerFallbackRanking({
+                            results: searchResults,
+                            intent,
+                            negative_preferences: negativePreferences
+                        });
+                    }
+                    finally {
+                        rerankMs = Date.now() - rerankStartedAt;
+                    }
+                    searchResults = dedupeEnhancerCandidatesByPath(applyEnhancerIntentPathFiltering(reranked, {
+                        intent,
+                        negative_preferences: negativePreferences,
+                        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);
+                    searchResults = collapseEnhancerCandidatesByDirectory(searchResults, intentPolicy.max_candidates_per_directory_pre_rerank).slice(0, intentPolicy.max_candidates_pre_rerank);
+                }
+                candidateCountPostRerank = searchResults.length;
+            }
+            catch (error) {
+                warnings.push("Context retrieval unavailable; enhancement generated with limited confidence.");
+                fallbackTriggered = true;
+                fallbackReason = "context_retrieval_unavailable";
+                if (error instanceof RetrievalError && error.code === "NOT_FOUND") {
+                    warnings.push("No ready index found for workspace.");
+                    fallbackReason = "no_ready_index";
+                }
+            }
+        }
+        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({
+            intent,
+            language,
+            original_prompt: input.request.prompt,
+            refs: contextRefs
+        });
+        const output = {
+            trace_id: input.trace_id,
+            enhanced_prompt: enhancedPrompt,
+            context_refs: contextRefs,
+            warnings,
+            questions
+        };
+        const latency_ms = Date.now() - startedAt;
+        this.observability.metrics.observe("enhancer_latency_ms", latency_ms, {});
+        this.observability.metrics.observe("enhancer_context_refs_count", output.context_refs.length, {});
+        this.observability.metrics.observe("enhancer_questions_count", output.questions.length, {});
+        this.observability.metrics.observe("enhancer_query_expansion_ms", queryExpansionMs, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        this.observability.metrics.observe("enhancer_expanded_hint_count", expandedHintCount, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        this.observability.metrics.observe("enhancer_candidate_count_pre_rerank", candidateCountPreRerank, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        this.observability.metrics.observe("enhancer_candidate_count_post_rerank", candidateCountPostRerank, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        this.observability.metrics.observe("enhancer_rerank_ms", rerankMs, {
+            retrieval_profile_id: this.scoringProfileId
+        });
+        this.observability.metrics.observe("enhancer_low_confidence_triggered", lowConfidenceTriggered ? 1 : 0, {});
+        this.observability.metrics.observe("enhancer_fallback_triggered", fallbackTriggered ? 1 : 0, {});
+        if (lowConfidenceTriggered) {
+            this.observability.metrics.increment("enhancer_low_confidence_total", 1, {
+                retrieval_profile_id: this.scoringProfileId
+            });
+        }
+        if (fallbackTriggered) {
+            this.observability.metrics.increment("enhancer_fallback_total", 1, {
+                retrieval_profile_id: this.scoringProfileId,
+                reason: fallbackReason ?? "unknown"
+            });
+        }
+        this.observability.logger.info("enhance_prompt completed", {
+            trace_id: input.trace_id,
+            tenant_id: input.tenant_id,
+            workspace_id: input.workspace_id ?? "none",
+            latency_ms,
+            context_refs: output.context_refs.length,
+            query_expansion_ms: queryExpansionMs,
+            expanded_hint_count: expandedHintCount,
+            candidate_count_pre_rerank: candidateCountPreRerank,
+            candidate_count_post_rerank: candidateCountPostRerank,
+            rerank_ms: rerankMs,
+            low_confidence_triggered: lowConfidenceTriggered,
+            fallback_triggered: fallbackTriggered,
+            fallback_reason: fallbackReason,
+            query_intent: queryIntent,
+            confidence_score_spread: confidenceSignals?.score_spread ?? null,
+            confidence_token_overlap: confidenceSignals?.token_overlap ?? null,
+            confidence_path_diversity: confidenceSignals?.path_diversity ?? null,
+            ...(this.enhancerDecisionTraceEnabled
+                ? {
+                    intent_class: intent,
+                    strong_anchor_bypass_used: strongAnchorBypassUsed,
+                    rerank_used: rerankUsed,
+                    confidence_score: confidenceSignals?.confidence_score ?? null,
+                    confidence_threshold: confidenceSignals?.confidence_threshold ?? null
+                }
+                : {})
+        });
+        return output;
+    }
+}
+export function createDefaultRetrievalCore() {
+    return new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache());
+}
+export async function seedWorkspaceIndex(core, artifact) {
+    return core.indexArtifact(artifact);
+}
+export * from "./remote-sync.js";