@rce-mcp/retrieval-core 0.1.0

package/src/index.ts

@@ -0,0 +1,4338 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { EnhancePromptInput, EnhancePromptOutput, SearchContextInput, SearchContextOutput } from "@rce-mcp/contracts";
+import {
+  buildQueryCacheKey,
+  type CandidateScoreWeights,
+  type IndexRepository,
+  type QueryCache,
+  type RankedChunkCandidate,
+  type WorkspaceRecord
+} from "@rce-mcp/data-plane";
+import { InMemoryQueryCache } from "@rce-mcp/data-plane";
+import { getObservability, type Observability } from "@rce-mcp/observability";
+import {
+  buildChunksForFile,
+  getChunkingParserAvailabilitySnapshot,
+  type ChunkingFallbackReason,
+  type ChunkingStrategy
+} from "./chunking.js";
+
+type RetrievalMode = SearchContextOutput["search_metadata"]["retrieval_mode"];
+type ContextRef = EnhancePromptOutput["context_refs"][number];
+
+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: CandidateScoreWeights = {
+  lexical_weight: 0.6,
+  vector_weight: 0.4,
+  path_match_boost: 0.2,
+  recency_boost: 0.1,
+  generated_penalty: 0.2
+};
+
+export interface RetrievalPathBiasConfig {
+  source_path_boost: number;
+  low_priority_prefix_penalty: number;
+  low_priority_substring_penalty: number;
+  low_priority_asset_penalty: number;
+  lockfile_penalty: number;
+  doc_intent_docs_boost: number;
+  doc_intent_markdown_boost: number;
+  docs_without_doc_intent_penalty: number;
+  non_doc_markdown_penalty: number;
+  code_intent_docs_penalty: number;
+  doc_intent_source_penalty: number;
+  workspace_manifest_root_boost: number;
+  workspace_manifest_nested_boost: number;
+  ui_component_tsx_boost: number;
+  ui_component_css_penalty: number;
+  docs_archive_penalty: number;
+  public_path_penalty: number;
+  test_path_penalty: number;
+  example_path_penalty: number;
+  declaration_file_penalty: number;
+  test_intent_test_boost: number;
+  example_intent_example_boost: number;
+  filename_token_match_boost: number;
+  negation_avoid_docs_penalty: number;
+  negation_avoid_tests_penalty: number;
+  negation_avoid_examples_penalty: number;
+  negation_avoid_archive_penalty: number;
+  min_total_bias: number;
+  max_total_bias: number;
+}
+
+export interface RetrievalRerankConfig {
+  low_information_penalty: number;
+  max_chunks_per_path_default: number;
+  max_chunks_per_path_file_lookup: number;
+  same_directory_penalty: number;
+  same_extension_penalty: number;
+}
+
+export interface RetrievalScoringConfig {
+  candidate_weights: CandidateScoreWeights;
+  path_bias: RetrievalPathBiasConfig;
+  rerank: RetrievalRerankConfig;
+}
+
+export interface RetrievalEnhancerConfig {
+  max_expansion_hints: number;
+  max_candidates_pre_rerank: number;
+  rerank_timeout_ms: number;
+}
+
+export interface RetrievalChunkingConfig {
+  strategy: ChunkingStrategy;
+  fallback_strategy: "sliding";
+  parse_timeout_ms: number;
+  enabled_languages: string[];
+}
+
+export type RetrievalScoringConfigInput = Partial<{
+  candidate_weights: Partial<CandidateScoreWeights>;
+  path_bias: Partial<RetrievalPathBiasConfig>;
+  rerank: Partial<RetrievalRerankConfig>;
+}>;
+
+export type RetrievalEnhancerConfigInput = Partial<RetrievalEnhancerConfig>;
+export type RetrievalChunkingConfigInput = Partial<{
+  strategy: ChunkingStrategy;
+  fallback_strategy: "sliding";
+  parse_timeout_ms: number;
+  enabled_languages: string[];
+}>;
+
+export const BASELINE_RETRIEVAL_SCORING_CONFIG: RetrievalScoringConfig = {
+  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: RetrievalScoringConfig = {
+  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: RetrievalEnhancerConfig = {
+  max_expansion_hints: 24,
+  max_candidates_pre_rerank: 4,
+  rerank_timeout_ms: 40
+};
+
+export const DEFAULT_RETRIEVAL_CHUNKING_CONFIG: RetrievalChunkingConfig = {
+  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
+} as const;
+
+export type BuiltinRetrievalScoringProfileId = keyof typeof BUILTIN_RETRIEVAL_SCORING_PROFILES;
+
+function deepCloneScoringConfig(config: RetrievalScoringConfig): RetrievalScoringConfig {
+  return {
+    candidate_weights: { ...config.candidate_weights },
+    path_bias: { ...config.path_bias },
+    rerank: { ...config.rerank }
+  };
+}
+
+function assertFiniteNumber(value: unknown, label: string): number {
+  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: RetrievalScoringConfig): void {
+  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: string | undefined): {
+  profile_id: BuiltinRetrievalScoringProfileId;
+  config: RetrievalScoringConfig;
+} {
+  const normalized = (profile_id ?? "baseline").trim().toLowerCase() as BuiltinRetrievalScoringProfileId;
+  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: RetrievalScoringConfig,
+  overrides?: RetrievalScoringConfigInput
+): RetrievalScoringConfig {
+  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: RetrievalEnhancerConfig): void {
+  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: RetrievalEnhancerConfig,
+  overrides?: RetrievalEnhancerConfigInput
+): RetrievalEnhancerConfig {
+  const next: RetrievalEnhancerConfig = {
+    ...base,
+    ...(overrides ?? {})
+  };
+  validateEnhancerConfig(next);
+  return next;
+}
+
+function normalizeChunkingLanguageList(value: string[]): string[] {
+  const deduped = new Set<string>();
+  for (const language of value) {
+    const normalized = language.trim().toLowerCase();
+    if (normalized.length === 0) {
+      continue;
+    }
+    deduped.add(normalized);
+  }
+  return [...deduped];
+}
+
+function validateChunkingConfig(config: RetrievalChunkingConfig): void {
+  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: RetrievalChunkingConfig,
+  overrides?: RetrievalChunkingConfigInput
+): RetrievalChunkingConfig {
+  const next: RetrievalChunkingConfig = {
+    ...base,
+    ...(overrides ?? {}),
+    enabled_languages: normalizeChunkingLanguageList(overrides?.enabled_languages ?? base.enabled_languages)
+  };
+  validateChunkingConfig(next);
+  return next;
+}
+
+function stableSerialize(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableSerialize(entry)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableSerialize(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function scoringConfigChecksum(config: RetrievalScoringConfig): string {
+  return sha256(stableSerialize(config)).slice(0, 12);
+}
+
+const REASON_STRINGS = [
+  "semantic match",
+  "exact symbol match",
+  "path and token overlap",
+  "recently modified relevant module"
+] as const;
+
+export type RetrievalReason = (typeof REASON_STRINGS)[number];
+
+export class RetrievalError extends Error {
+  readonly code: "INVALID_ARGUMENT" | "NOT_FOUND" | "UPSTREAM_FAILURE";
+
+  constructor(code: "INVALID_ARGUMENT" | "NOT_FOUND" | "UPSTREAM_FAILURE", message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export interface RawFile {
+  path: string;
+  content: string;
+  language?: string;
+  updated_at?: string;
+  generated?: boolean;
+  binary?: boolean;
+}
+
+export interface IndexUploadArtifact {
+  tenant_id: string;
+  workspace_id: string;
+  index_version: string;
+  files: RawFile[];
+  manifest?: {
+    object_key: string;
+    checksum: string;
+  };
+}
+
+export interface IndexDeltaArtifact {
+  tenant_id: string;
+  workspace_id: string;
+  index_version: string;
+  base_index_version?: string;
+  upsert_files: RawFile[];
+  deleted_paths: string[];
+}
+
+interface IndexedChunk {
+  path: string;
+  start_line: number;
+  end_line: number;
+  snippet: string;
+  language?: string;
+  generated?: boolean;
+  updated_at: string;
+  hash: string;
+  embedding?: number[];
+}
+
+interface ReadyIndex {
+  index_id: string;
+  tenant_id: string;
+  workspace_id: string;
+  index_version: string;
+  status: "indexing" | "ready" | "failed";
+  created_at: string;
+  updated_at: string;
+}
+
+interface PersistedFile {
+  file_id: string;
+  repo_path: string;
+  content_hash: string;
+  language?: string;
+}
+
+export interface IndexingWarning {
+  path: string;
+  reason: string;
+  category: "secret_exclusion" | "filter_exclusion";
+}
+
+export interface IndexingReport {
+  workspace_id: string;
+  index_version: string;
+  status: "ready";
+  counts: {
+    added: number;
+    modified: number;
+    deleted: number;
+    unchanged: number;
+    skipped: number;
+  };
+  skipped_files: Array<{ path: string; reason: string }>;
+  warnings: IndexingWarning[];
+}
+
+export interface RetrievalCoreOptions {
+  cacheTtlSeconds?: number;
+  embeddingProvider?: EmbeddingProvider;
+  embeddingDescriptor?: EmbeddingDescriptor;
+  observability?: Observability;
+  scoringProfile?: BuiltinRetrievalScoringProfileId;
+  scoringProfileId?: string;
+  scoringConfig?: RetrievalScoringConfigInput;
+  enhancerConfig?: RetrievalEnhancerConfigInput;
+  chunkingConfig?: RetrievalChunkingConfigInput;
+  enhancerDecisionTraceEnabled?: boolean;
+}
+
+export interface EmbeddingDescriptor {
+  provider: string;
+  model?: string;
+  dimensions: number;
+  version?: string;
+}
+
+export type EmbeddingPurpose = "index" | "query";
+
+export interface EmbeddingProvider {
+  embed(input: { texts: string[]; purpose: EmbeddingPurpose }): Promise<number[][]>;
+  describe?(): EmbeddingDescriptor;
+}
+
+export interface DeterministicEmbeddingProviderOptions {
+  dimensions?: number;
+  model?: string;
+  version?: string;
+}
+
+export interface OpenAICompatibleEmbeddingProviderOptions {
+  base_url: string;
+  api_key: string;
+  model?: string;
+  dimensions?: number;
+  timeout_ms?: number;
+  batch_size?: number;
+  max_retries?: number;
+  observability?: Observability;
+}
+
+class EmbeddingProviderRequestError extends Error {
+  constructor(
+    readonly reason: string,
+    readonly retryable: boolean,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+const SECRET_PATTERNS: Array<{ label: string; pattern: RegExp }> = [
+  { 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: string): string {
+  return path.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^\.\//, "").trim();
+}
+
+function normalizeQuery(query: string): string {
+  return query.normalize("NFKC").trim();
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function pluralizeToken(token: string): string | undefined {
+  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: string): string | undefined {
+  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: string): string[] {
+  const coarseTokens = text
+    .split(/[^a-z0-9_./-]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+
+  const expandedTokens = new Set<string>();
+  const addToken = (value: string): void => {
+    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: string, haystack: string): number {
+  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: number[], b: number[]): number {
+  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: string): boolean {
+  const trimmed = snippet.trim();
+  if (trimmed.length < 12) {
+    return true;
+  }
+  const noWhitespace = trimmed.replace(/\s+/g, "");
+  return /^(.)\1+$/.test(noWhitespace);
+}
+
+function chooseReason(input: {
+  lexical: number;
+  path_match: boolean;
+  recency_boosted: boolean;
+}): RetrievalReason {
+  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"
+];
+
+interface NegativePathPreferences {
+  avoid_docs: boolean;
+  avoid_tests: boolean;
+  avoid_examples: boolean;
+  avoid_archive: boolean;
+}
+
+function hasNegationNearTarget(normalized: string, targetPattern: string): boolean {
+  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: string): NegativePathPreferences {
+  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: string[]): boolean {
+  return tokens.some((token) => DOC_INTENT_TOKENS.has(token));
+}
+
+function hasCodeIntent(tokens: string[]): boolean {
+  return tokens.some((token) => CODE_INTENT_TOKENS.has(token));
+}
+
+function hasWorkspaceManifestIntent(tokens: string[]): boolean {
+  return tokens.some((token) => WORKSPACE_MANIFEST_TOKENS.has(token));
+}
+
+function hasUiComponentIntent(tokens: string[]): boolean {
+  return tokens.some((token) => UI_COMPONENT_TOKENS.has(token));
+}
+
+function hasFileLookupIntent(tokens: string[]): boolean {
+  return tokens.some((token) => FILE_LOOKUP_TOKENS.has(token));
+}
+
+function hasTestIntent(tokens: string[]): boolean {
+  return tokens.some((token) => TEST_INTENT_TOKENS.has(token));
+}
+
+function hasExampleIntent(tokens: string[]): boolean {
+  return tokens.some((token) => EXAMPLE_INTENT_TOKENS.has(token));
+}
+
+function pathQualityBias(path: string, queryTokens: string[], config: RetrievalScoringConfig, queryText?: string): number {
+  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));
+}
+
+interface ChunkBuildReport {
+  chunks: IndexedChunk[];
+  strategy: ChunkingStrategy;
+  fallback_reason?: ChunkingFallbackReason;
+  parse_latency_ms?: number;
+  language_aware_attempt_latency_ms?: number;
+  fallback_path_latency_ms?: number;
+  language?: string;
+}
+
+function buildChunks(file: RawFile, chunkingConfig: RetrievalChunkingConfig): ChunkBuildReport {
+  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: string, dimensions = 24): number[] {
+  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: number[] = [];
+  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: unknown): value is number[] {
+  return Array.isArray(value) && value.every((cell) => typeof cell === "number" && Number.isFinite(cell));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+export class DeterministicEmbeddingProvider implements EmbeddingProvider {
+  private readonly dimensions: number;
+  private readonly model: string;
+  private readonly version: string;
+
+  constructor(options: DeterministicEmbeddingProviderOptions = {}) {
+    this.dimensions = options.dimensions ?? 24;
+    this.model = options.model ?? "pseudo-sha256";
+    this.version = options.version ?? "v1";
+  }
+
+  async embed(input: { texts: string[]; purpose: EmbeddingPurpose }): Promise<number[][]> {
+    return input.texts.map((text) => pseudoEmbedding(text, this.dimensions));
+  }
+
+  describe(): EmbeddingDescriptor {
+    return {
+      provider: "deterministic",
+      model: this.model,
+      dimensions: this.dimensions,
+      version: this.version
+    };
+  }
+}
+
+export class OpenAICompatibleEmbeddingProvider implements EmbeddingProvider {
+  private readonly baseUrl: string;
+  private readonly endpoint: string;
+  private readonly apiKey: string;
+  private readonly model: string;
+  private readonly dimensions: number;
+  private readonly timeoutMs: number;
+  private readonly batchSize: number;
+  private readonly maxRetries: number;
+  private readonly observability: Observability;
+
+  constructor(options: OpenAICompatibleEmbeddingProviderOptions) {
+    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(): EmbeddingDescriptor {
+    return {
+      provider: "openai_compatible",
+      model: this.model,
+      dimensions: this.dimensions
+    };
+  }
+
+  async embed(input: { texts: string[]; purpose: EmbeddingPurpose }): Promise<number[][]> {
+    if (input.texts.length === 0) {
+      return [];
+    }
+
+    const output: number[][] = [];
+    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;
+  }
+
+  private async embedBatchWithRetries(texts: string[], purpose: EmbeddingPurpose): Promise<number[][]> {
+    const labels = {
+      provider: "openai_compatible",
+      model: this.model,
+      purpose
+    } as const;
+
+    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");
+  }
+
+  private async embedBatchOnce(texts: string[]): Promise<number[][]> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, this.timeoutMs);
+
+    let response: 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 as { name?: string }).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: unknown;
+    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 as { data: unknown }).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 as { index?: unknown }).index)
+    );
+
+    const ordered = hasIndexField
+      ? [...rawData].sort((a, b) => {
+          const left = (a as { index: number }).index;
+          const right = (b as { index: number }).index;
+          return left - right;
+        })
+      : rawData;
+
+    const vectors: number[][] = [];
+    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 as { index: number }).index !== i) {
+        throw new EmbeddingProviderRequestError("invalid_response", false, "embedding row indexes are not contiguous");
+      }
+      const embedding = (row as { embedding?: unknown }).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;
+  }
+
+  private retryDelayMs(attempt: number): number {
+    const base = 100 * (attempt + 1);
+    const jitter = Math.floor(Math.random() * 75);
+    return base + jitter;
+  }
+
+  private toProviderFailure(error: unknown): EmbeddingProviderRequestError {
+    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: Response): Promise<string> {
+  try {
+    const text = await response.text();
+    return text.slice(0, 512);
+  } catch {
+    return "";
+  }
+}
+
+function resolveEmbeddingDescriptor(provider: EmbeddingProvider): EmbeddingDescriptor {
+  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: EmbeddingDescriptor): EmbeddingDescriptor {
+  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: string): "bugfix" | "feature" | "refactor" | "docs" | "tests" | "unknown" {
+  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: string, history: EnhancePromptInput["conversation_history"]): "en" | "es" | "zh" {
+  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";
+}
+
+interface EnhancerFrameworkHintRule {
+  id: string;
+  token_triggers: string[];
+  phrase_triggers: string[];
+  symbol_hints: string[];
+  path_hints: string[];
+}
+
+const ENHANCER_FRAMEWORK_HINT_RULES: EnhancerFrameworkHintRule[] = [
+  {
+    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"
+]);
+
+type EnhancerQueryIntent = "symbol-heavy" | "impl-focused" | "conceptual";
+
+interface EnhancerIntentPolicy {
+  max_expansion_hints: number;
+  max_candidates_pre_rerank: number;
+  max_candidates_per_directory_pre_rerank: number;
+  strict_impl_only_filtering: boolean;
+}
+
+function classifyEnhancerQueryIntent(prompt: string, history: EnhancePromptInput["conversation_history"]): EnhancerQueryIntent {
+  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: {
+  query_intent: EnhancerQueryIntent;
+  enhancer_config: RetrievalEnhancerConfig;
+  negative_preferences: NegativePathPreferences;
+}): EnhancerIntentPolicy {
+  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: string): boolean {
+  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: string): string[] {
+  const out: string[] = [];
+  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: string, limit = 12): string[] {
+  const symbols: string[] = [];
+  const seen = new Set<string>();
+
+  const add = (candidate: string): void => {
+    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: string, limit = 12): string[] {
+  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: string[] = [];
+  const seen = new Set<string>();
+  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: string,
+  history: EnhancePromptInput["conversation_history"],
+  options?: { maxExpansionHints?: number; queryIntent?: EnhancerQueryIntent }
+): { query: string; expanded_hint_count: number; query_intent: EnhancerQueryIntent } {
+  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<string>();
+  const hints: string[] = [];
+  const addHint = (value: string): void => {
+    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: string): void => {
+    if (genericHintCount >= genericHintBudget) {
+      return;
+    }
+    const beforeCount = hints.length;
+    addHint(value);
+    if (hints.length > beforeCount) {
+      genericHintCount += 1;
+    }
+  };
+  const addFrameworkHint = (value: string): void => {
+    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: string): string {
+  const normalized = normalizePath(path);
+  const idx = normalized.lastIndexOf("/");
+  if (idx <= 0) {
+    return ".";
+  }
+  return normalized.slice(0, idx);
+}
+
+function fileExtension(path: string): string {
+  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: number[]): number {
+  if (values.length === 0) {
+    return 0;
+  }
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function percentile(values: number[], p: number): number {
+  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: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function normalizeEnhancerOverlapTokens(text: string): string[] {
+  return tokenize(text).filter((token) => token.length >= 3 && !ENHANCER_CONFIDENCE_OVERLAP_STOPWORDS.has(token));
+}
+
+function overlapRatio(queryTokens: string[], result: SearchContextOutput["results"][number]): number {
+  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: SearchContextOutput["results"]): number {
+  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: string): boolean {
+  const normalized = normalizePath(path).toLowerCase();
+  return (
+    normalized.startsWith("docs/") ||
+    normalized.includes("/docs/") ||
+    normalized.endsWith(".md") ||
+    normalized.endsWith(".rst") ||
+    normalized.endsWith(".txt")
+  );
+}
+
+function isTestLikePath(path: string): boolean {
+  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: string): boolean {
+  const normalized = normalizePath(path).toLowerCase();
+  return (
+    normalized.startsWith("example/") ||
+    normalized.startsWith("examples/") ||
+    normalized.includes("/example/") ||
+    normalized.includes("/examples/")
+  );
+}
+
+function isArchiveLikePath(path: string): boolean {
+  const normalized = normalizePath(path).toLowerCase();
+  return (
+    normalized.includes("/archive/") ||
+    normalized.includes("/_archive/") ||
+    normalized.startsWith("archive/") ||
+    normalized.startsWith("_archive/")
+  );
+}
+
+function shouldAvoidPathFromNegation(path: string, preferences: NegativePathPreferences): boolean {
+  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: string, intent: ReturnType<typeof classifyIntent>): boolean {
+  if (intent === "docs") {
+    return false;
+  }
+  if (intent === "tests") {
+    return isDocsLikePath(path) || isExampleLikePath(path);
+  }
+  return isDocsLikePath(path) || isTestLikePath(path) || isExampleLikePath(path);
+}
+
+function applyEnhancerIntentPathFiltering(
+  results: SearchContextOutput["results"],
+  input: {
+    intent: ReturnType<typeof classifyIntent>;
+    negative_preferences: NegativePathPreferences;
+    strict_impl_only_filtering: boolean;
+  }
+): SearchContextOutput["results"] {
+  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: SearchContextOutput["results"][number], b: SearchContextOutput["results"][number]): number {
+  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: SearchContextOutput["results"]): SearchContextOutput["results"] {
+  const byPath = new Map<string, SearchContextOutput["results"][number]>();
+  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: SearchContextOutput["results"],
+  maxPerDirectory: number
+): SearchContextOutput["results"] {
+  if (maxPerDirectory <= 0) {
+    return [];
+  }
+  const output: SearchContextOutput["results"] = [];
+  const directoryCounts = new Map<string, number>();
+  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: string): string[] {
+  const anchors = new Set<string>();
+  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: {
+  prompt: string;
+  history: EnhancePromptInput["conversation_history"];
+  results: SearchContextOutput["results"];
+}): boolean {
+  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: {
+  query_intent: EnhancerQueryIntent;
+  prompt: string;
+  history: EnhancePromptInput["conversation_history"];
+  results: SearchContextOutput["results"];
+  negative_preferences: NegativePathPreferences;
+}): boolean {
+  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;
+}
+
+interface EnhancerConfidenceSignals {
+  score_spread: number;
+  token_overlap: number;
+  path_diversity: number;
+  confidence_score: number;
+  confidence_threshold: number;
+  failed_signals: string[];
+  low_confidence: boolean;
+}
+
+function evaluateEnhancerConfidence(input: {
+  prompt: string;
+  retrieval_query: string;
+  query_intent: EnhancerQueryIntent;
+  results: SearchContextOutput["results"];
+}): EnhancerConfidenceSignals {
+  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: string[] = [];
+  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: {
+  results: SearchContextOutput["results"];
+  intent: ReturnType<typeof classifyIntent>;
+  query_intent: EnhancerQueryIntent;
+  negative_preferences: NegativePathPreferences;
+  prompt: string;
+  retrieval_query: string;
+}): SearchContextOutput["results"] {
+  const overlapTokens = normalizeEnhancerOverlapTokens(`${input.prompt}\n${input.retrieval_query}`);
+  const anchors = extractEnhancerAnchors(`${input.prompt}\n${input.retrieval_query}`);
+  const anchorScore = (result: SearchContextOutput["results"][number]): number => {
+    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<T>(input: { timeout_ms: number; fn: () => Promise<T> | T }): Promise<T> {
+  return await new Promise<T>((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: {
+  results: SearchContextOutput["results"];
+  intent: ReturnType<typeof classifyIntent>;
+  negative_preferences: NegativePathPreferences;
+}): SearchContextOutput["results"] {
+  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: {
+  language: "en" | "es" | "zh";
+  kind: "scope" | "symbol" | "source_priority";
+  symbol?: string;
+}): string {
+  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: SearchContextOutput["results"]): SearchContextOutput["results"] {
+  let total = 0;
+  const out: SearchContextOutput["results"] = [];
+  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: {
+  intent: ReturnType<typeof classifyIntent>;
+  language: "en" | "es" | "zh";
+  original_prompt: string;
+  refs: ContextRef[];
+}): string {
+  const emptyRefsByLanguage = {
+    en: "- (no file context available)",
+    es: "- (no hay contexto de archivos disponible)",
+    zh: "- (暂无可用文件上下文)"
+  } as const;
+  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: string): string[] {
+  const matches = new Set<string>();
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.pattern.test(content)) {
+      matches.add(pattern.label);
+    }
+    pattern.pattern.lastIndex = 0;
+  }
+  return [...matches];
+}
+
+export class InMemoryIndexStore implements IndexRepository {
+  private readonly workspaces = new Map<string, WorkspaceRecord>();
+  private readonly workspacesByPath = new Map<string, WorkspaceRecord>();
+  private readonly indexes = new Map<string, ReadyIndex>();
+  private readonly workspaceIndexes = new Map<string, string[]>();
+  private readonly filesByIndex = new Map<string, PersistedFile[]>();
+  private readonly chunksByFile = new Map<string, IndexedChunk[]>();
+  private readonly indexMetadata = new Map<
+    string,
+    {
+      tenant_id: string;
+      embedding_provider: string;
+      embedding_model?: string;
+      embedding_dimensions: number;
+      embedding_version?: string;
+      chunking_strategy: "language_aware" | "sliding";
+      chunking_fallback_strategy: "sliding";
+      created_at: string;
+    }
+  >();
+
+  async migrate(): Promise<void> {
+    return;
+  }
+
+  async upsertWorkspace(input: WorkspaceRecord): Promise<void> {
+    this.workspaces.set(input.workspace_id, input);
+    this.workspacesByPath.set(`${input.tenant_id}:${input.project_root_path}`, input);
+  }
+
+  async resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined> {
+    return this.workspacesByPath.get(`${tenant_id}:${project_root_path}`);
+  }
+
+  async resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined> {
+    const workspace = this.workspaces.get(workspace_id);
+    if (!workspace || workspace.tenant_id !== tenant_id) {
+      return undefined;
+    }
+    return workspace;
+  }
+
+  async createIndexVersion(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    status?: "indexing" | "ready" | "failed";
+  }): Promise<ReadyIndex> {
+    const indexId = `idx_${randomUUID()}`;
+    const index: ReadyIndex = {
+      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: {
+    tenant_id: string;
+    workspace_id: string;
+    index_id: string;
+    status: "indexing" | "ready" | "failed";
+  }): Promise<void> {
+    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: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+  }): Promise<ReadyIndex | undefined> {
+    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: {
+    tenant_id: string;
+    index_id: string;
+  }): Promise<void> {
+    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: { tenant_id: string; workspace_id: string }): Promise<ReadyIndex | undefined> {
+    const indexIds = this.workspaceIndexes.get(input.workspace_id) ?? [];
+    const readyIndexes = indexIds
+      .map((id) => this.indexes.get(id))
+      .filter((index): index is ReadyIndex => 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: { tenant_id: string; index_id: string }): Promise<PersistedFile[]> {
+    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: {
+    tenant_id: string;
+    source_index_id: string;
+    target_index_id: string;
+    repo_path: string;
+  }): Promise<void> {
+    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: PersistedFile = {
+      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: {
+    tenant_id: string;
+    index_id: string;
+    repo_path: string;
+    content_hash: string;
+    size_bytes: number;
+    language?: string;
+  }): Promise<{ file_id: string }> {
+    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: {
+    tenant_id: string;
+    file_id: string;
+    repo_path: string;
+    chunks: Array<{
+      start_line: number;
+      end_line: number;
+      snippet: string;
+      embedding: number[];
+      generated?: boolean;
+      updated_at?: string;
+    }>;
+  }): Promise<void> {
+    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(): Promise<void> {
+    return;
+  }
+
+  async saveIndexMetadata(input: {
+    tenant_id: string;
+    index_id: string;
+    embedding_provider: string;
+    embedding_model?: string;
+    embedding_dimensions: number;
+    embedding_version?: string;
+    chunking_strategy: "language_aware" | "sliding";
+    chunking_fallback_strategy: "sliding";
+  }): Promise<void> {
+    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: { tenant_id: string; index_id: string }): Promise<{
+    embedding_provider: string;
+    embedding_model?: string;
+    embedding_dimensions: number;
+    embedding_version?: string;
+    chunking_strategy: "language_aware" | "sliding";
+    chunking_fallback_strategy: "sliding";
+    created_at: string;
+  } | undefined> {
+    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: {
+    tenant_id: string;
+    index_id: string;
+    filters?: {
+      language?: string;
+      path_prefix?: string;
+      glob?: string;
+    };
+  }): Promise<
+    Array<{
+      chunk_id: string;
+      file_id: string;
+      path: string;
+      start_line: number;
+      end_line: number;
+      snippet: string;
+      language?: string;
+      generated?: boolean;
+      updated_at: string;
+      embedding: number[];
+    }>
+  > {
+    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: Array<{
+      chunk_id: string;
+      file_id: string;
+      path: string;
+      start_line: number;
+      end_line: number;
+      snippet: string;
+      language?: string;
+      generated?: boolean;
+      updated_at: string;
+      embedding: number[];
+    }> = [];
+
+    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: string): RegExp {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const pattern = `^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`;
+  return new RegExp(pattern);
+}
+
+export class RetrievalCore {
+  private readonly cacheTtlSeconds: number;
+  private readonly embeddingProvider: EmbeddingProvider;
+  private readonly embeddingDescriptor: EmbeddingDescriptor;
+  private readonly observability: Observability;
+  private readonly scoringConfig: RetrievalScoringConfig;
+  private readonly scoringProfileId: string;
+  private readonly scoringConfigChecksum: string;
+  private readonly enhancerConfig: RetrievalEnhancerConfig;
+  private readonly chunkingConfig: RetrievalChunkingConfig;
+  private readonly enhancerDecisionTraceEnabled: boolean;
+  private cacheHits = 0;
+  private cacheMisses = 0;
+
+  constructor(
+    private readonly store: IndexRepository,
+    private readonly cache: QueryCache,
+    options?: RetrievalCoreOptions
+  ) {
+    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: IndexUploadArtifact): Promise<IndexingReport> {
+    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: Array<{ path: string; reason: string }> = [];
+    const warnings: IndexingWarning[] = [];
+
+    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<string, string>();
+    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<string, string>();
+    const changedFiles: RawFile[] = [];
+
+    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: IndexDeltaArtifact): Promise<IndexingReport> {
+    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<string, RawFile>();
+    for (const file of artifact.upsert_files) {
+      const normalizedPath = normalizePath(file.path);
+      dedupedUpsertFiles.set(normalizedPath, {
+        ...file,
+        path: normalizedPath
+      });
+    }
+    const normalizedUpsertFiles = [...dedupedUpsertFiles.values()];
+
+    const skipped: Array<{ path: string; reason: string }> = [];
+    const warnings: IndexingWarning[] = [];
+    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<string, string>();
+    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: RawFile[] = [];
+    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: string[] = [];
+    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: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+  }): Promise<
+    | {
+        index_id: string;
+        status: "indexing" | "ready" | "failed";
+      }
+    | undefined
+  > {
+    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: {
+    trace_id: string;
+    tenant_id: string;
+    workspace_id: string;
+    request: SearchContextInput;
+  }): Promise<SearchContextOutput> {
+    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: "provider_mismatch" | "model_mismatch" | "dimension_mismatch" | undefined;
+    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: RankedChunkCandidate[] | undefined;
+        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: SearchContextOutput["results"] = [];
+      const seen = new Set<string>();
+      const pathCounts = new Map<string, number>();
+      const directoryCounts = new Map<string, number>();
+      const extensionCounts = new Map<string, number>();
+      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: SearchContextOutput = {
+      trace_id: input.trace_id,
+      results: deduped,
+      search_metadata: {
+        latency_ms: Date.now() - searchStartedAt,
+        retrieval_mode: "hybrid" satisfies RetrievalMode,
+        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: {
+    trace_id: string;
+    tenant_id: string;
+    workspace_id?: string;
+    request: EnhancePromptInput;
+  }): Promise<EnhancePromptOutput> {
+    const startedAt = Date.now();
+    const warnings: string[] = [];
+    const questions: string[] = [];
+    const addQuestion = (value: string): void => {
+      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: SearchContextOutput["results"] = [];
+    let retrievalQuery = "";
+    let lowConfidenceTriggered = false;
+    let fallbackTriggered = false;
+    let fallbackReason: string | null = null;
+    let confidenceSignals: EnhancerConfidenceSignals | undefined;
+    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: SearchContextOutput["results"];
+          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: ContextRef[] = 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: EnhancePromptOutput = {
+      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(): RetrievalCore {
+  return new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache());
+}
+
+export async function seedWorkspaceIndex(core: RetrievalCore, artifact: IndexUploadArtifact): Promise<IndexingReport> {
+  return core.indexArtifact(artifact);
+}
+
+export * from "./remote-sync.js";