@100xprompt/chitta 0.1.0

package/src/mcp/tools/context-rebuild.ts

@@ -0,0 +1,22 @@
+import type { ContextBackend } from "../backend"
+import type { ToolModule, ToolResult } from "./types"
+
+const schema = {
+  name: "context_rebuild",
+  description:
+    "Re-extract the knowledge graph over ALL stored records using the current extractor. Run this after " +
+    "connecting a local LLM (CONTEXT_LLM_URL) to upgrade older data from untyped to TYPED triples " +
+    "(e.g. 'Google partners_with HSBC'), so questions resolve to exact facts. May take a while on large stores.",
+  inputSchema: { type: "object" as const, properties: {} },
+}
+
+async function handler(_args: Record<string, unknown>, backend: ContextBackend): Promise<ToolResult> {
+  const r = await backend.rebuild!()
+  return {
+    content: [
+      { type: "text", text: `Rebuilt the knowledge graph: ${r.records} record(s) → ${r.entities} concept-mention(s) re-extracted with the current model.` },
+    ],
+  }
+}
+
+export const contextRebuildTool: ToolModule = { schema, handler, available: (b) => !!b.rebuild }

package/src/mcp/tools/context-relate.ts

@@ -0,0 +1,88 @@
+import type { ContextBackend } from "../backend"
+import type { ToolModule, ToolResult } from "./types"
+
+const schema = {
+  name: "context_relate",
+  description:
+    "Query the knowledge graph AS A GRAPH (not text search). Four modes:\n" +
+    "• neighbors - what's directly connected to an entity (optionally by relation).\n" +
+    "• path - HOW two entities are related (shortest relation chain between them).\n" +
+    "• impact - which records reference an entity + what it connects to ('what depends on X').\n" +
+    "• central - the hub entities (most-connected concepts the user knows about).\n" +
+    "• communities - clusters of related entities (the natural groupings in the graph).\n" +
+    "• walk - multi-hop relevance (Personalized PageRank) from one or more seed entities: what's\n" +
+    "  most related across the WHOLE graph, not just direct neighbors. Seeds = `entity` (comma-separated).\n" +
+    "• cypher - export the (permission-filtered) graph as Neo4j Cypher for interop.\n" +
+    "Works for CODE graphs too (functions/classes/calls/imports) and prose. " +
+    "USE WHEN the user asks 'how are X and Y connected', 'what's related to X', 'what calls/references X', " +
+    "'what are the main things here', or 'what clusters exist'. Permission-filtered. DON'T USE to fetch document text (get_context).",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      mode: { type: "string", enum: ["neighbors", "path", "impact", "central", "communities", "cypher", "walk"], description: "which graph query" },
+      entity: { type: "string", description: "the entity (for neighbors/impact), or first entity (for path)" },
+      to: { type: "string", description: "the second entity (path mode only)" },
+      relation: { type: "string", description: "optional relation filter (neighbors mode)" },
+    },
+    required: ["mode"],
+  },
+}
+
+async function handler(args: Record<string, unknown>, backend: ContextBackend): Promise<ToolResult> {
+  const a = args as { mode: string; entity?: string; to?: string; relation?: string }
+  const gq = backend.graphQuery!
+  if (a.mode === "central") {
+    const hubs = (await gq.central(15)) as Array<{ label: string; degree: number; strength: number }>
+    const text = hubs.length
+      ? "Central concepts (most-connected):\n" + hubs.map((h) => `  ${h.label} - ${h.degree} link(s), strength ${h.strength}`).join("\n")
+      : "The knowledge graph has no relationships yet."
+    return { content: [{ type: "text", text }] }
+  }
+  if (a.mode === "communities") {
+    const cs = (await gq.communities()) as Array<{ size: number; hub: string; members: string[] }>
+    const text = cs.length
+      ? "Communities (clusters of related entities):\n" +
+        cs.slice(0, 20).map((c, i) => `  [${i + 1}] ${c.hub} +${c.size - 1} more - ${c.members.slice(0, 8).join(", ")}${c.members.length > 8 ? "…" : ""}`).join("\n")
+      : "No clusters yet (graph has no relationships)."
+    return { content: [{ type: "text", text }] }
+  }
+  if (a.mode === "walk") {
+    if (!a.entity) return { content: [{ type: "text", text: "Provide `entity` (one or more comma-separated seeds)." }], isError: true }
+    const seeds = a.entity.split(/\s*,\s*|\s+and\s+/i).filter(Boolean)
+    const r = (await gq.walk(seeds)) as Array<{ label: string; score: number; type: string }>
+    const text = r.length
+      ? `Most related to ${seeds.join(", ")} (multi-hop PageRank):\n` + r.map((x) => `  ${x.label}${x.type ? ` (${x.type})` : ""} - ${x.score.toFixed(4)}`).join("\n")
+      : `No entity matching "${a.entity}" in accessible knowledge.`
+    return { content: [{ type: "text", text }] }
+  }
+  if (a.mode === "cypher") {
+    const cy = await gq.cypher()
+    return { content: [{ type: "text", text: cy || "// empty graph" }] }
+  }
+  if (!a.entity) return { content: [{ type: "text", text: "Provide `entity`." }], isError: true }
+  if (a.mode === "neighbors") {
+    const r = (await gq.neighbors(a.entity, a.relation)) as { entity: string; neighbors: Array<{ label: string; relation: string; direction: string; weight: number }> } | null
+    if (!r) return { content: [{ type: "text", text: `No entity matching "${a.entity}" in accessible knowledge.` }] }
+    const text = r.neighbors.length
+      ? `${r.entity} is connected to:\n` + r.neighbors.map((n) => `  ${n.direction === "out" ? "→" : "←"} ${n.label} (${n.relation}, ×${n.weight})`).join("\n")
+      : `${r.entity} has no recorded relationships.`
+    return { content: [{ type: "text", text }] }
+  }
+  if (a.mode === "impact") {
+    const r = (await gq.impact(a.entity)) as { entity: string; records: string[]; connectedEntities: Array<{ label: string; relation: string }> } | null
+    if (!r) return { content: [{ type: "text", text: `No entity matching "${a.entity}" in accessible knowledge.` }] }
+    const recs = r.records.length ? `Referenced by: ${r.records.join(", ")}.` : "Not referenced by any record."
+    const conn = r.connectedEntities.length ? "\nConnects to: " + r.connectedEntities.map((c) => `${c.label} (${c.relation})`).join(", ") : ""
+    return { content: [{ type: "text", text: `${r.entity}\n${recs}${conn}` }] }
+  }
+  if (a.mode === "path") {
+    if (!a.to) return { content: [{ type: "text", text: "Path mode needs `entity` and `to`." }], isError: true }
+    const r = (await gq.path(a.entity, a.to)) as { found: boolean; hops: number; steps: Array<{ from: string; relation: string; to: string }> }
+    if (!r.found) return { content: [{ type: "text", text: `No path found between "${a.entity}" and "${a.to}" (or one isn't in accessible knowledge).` }] }
+    const chain = r.steps.map((s) => `${s.from} -${s.relation}→ ${s.to}`).join("\n  then ")
+    return { content: [{ type: "text", text: `Connected in ${r.hops} hop(s):\n  ${chain}` }] }
+  }
+  return { content: [{ type: "text", text: `unknown mode: ${a.mode}` }], isError: true }
+}
+
+export const contextRelateTool: ToolModule = { schema, handler, available: (b) => !!b.graphQuery }

package/src/mcp/tools/get-context.ts

@@ -0,0 +1,52 @@
+import { RetrievalStatus, type SearchResult } from "../../types"
+import type { ContextBackend } from "../backend"
+import type { ToolModule, ToolResult } from "./types"
+
+function render(results: SearchResult[]): string {
+  return results.map((r, i) => `[${i + 1}] ${r.metadata.recordName ?? "untitled"}\n${r.content}`).join("\n\n")
+}
+
+const schema = {
+  name: "get_context",
+  description:
+    "Recall stored knowledge. USE WHEN: answering anything that could touch the user's own notes, people, " +
+    "projects, org knowledge, or past statements ('who/what did I…', 'what do we know about…', 'remind me…'). " +
+    "Call this BEFORE answering from your own assumptions. Returns ranked, cited, permission-filtered snippets " +
+    "(graph ACL → semantic vector search → GraphRAG expansion). DON'T USE for general world knowledge.",
+  inputSchema: {
+    type: "object" as const,
+    properties: { query: { type: "string", description: "what to recall - phrase it as the information need" } },
+    required: ["query"],
+  },
+}
+
+async function handler(args: Record<string, unknown>, backend: ContextBackend): Promise<ToolResult> {
+  const query = String((args as any).query ?? "")
+  // KGQA first: if the question maps to an exact fact in the typed graph,
+  // answer precisely (with citation) instead of returning a ranked list.
+  if (backend.ask) {
+    const exact = await backend.ask(query)
+    if (exact && exact.confidence >= 0.7) {
+      const cite = exact.citations.length ? ` (source: ${exact.citations.join(", ")})` : ""
+      const t = exact.triple
+      // Multiple facts → list them as bullets (a query can match several typed facts);
+      // a single fact stays inline.
+      const facts = exact.facts?.length ? exact.facts : [exact.answer]
+      const body = facts.length > 1 ? facts.map((f) => `• ${f}`).join("\n") : facts[0]
+      // Only show the triple bracket for a SINGLE genuine relational fact (a real verb).
+      const isRelational = facts.length === 1 && t.predicate && !["info", "facts", "mentioned_as", "prefer"].includes(t.predicate)
+      const tripleLine = isRelational ? `\n[${t.subject} -${t.predicate}→ ${t.object}]` : ""
+      return { content: [{ type: "text", text: `${body}${cite}${tripleLine}` }] }
+    }
+  }
+  const res = await backend.query(query)
+  const text =
+    res.status === RetrievalStatus.SUCCESS && res.searchResults.length
+      ? render(res.searchResults)
+      : res.status === RetrievalStatus.ACCESSIBLE_RECORDS_NOT_FOUND
+        ? "The knowledge graph is empty or you have no access yet."
+        : "No relevant context found."
+  return { content: [{ type: "text", text }] }
+}
+
+export const getContextTool: ToolModule = { schema, handler }

package/src/mcp/tools/index.ts

@@ -0,0 +1,40 @@
+// Aggregates the per-tool modules into the ListTools schema array and a
+// name→handler dispatch map, applying each tool's capability gate against the
+// active backend. Order matches the original inline TOOLS array exactly so the
+// ListTools response and the context_about "## Tools" section are unchanged.
+
+import type { ContextBackend } from "../backend"
+import { getContextTool } from "./get-context"
+import { contextIngestTool } from "./context-ingest"
+import { contextGraphTool } from "./context-graph"
+import { contextRebuildTool } from "./context-rebuild"
+import { contextRelateTool } from "./context-relate"
+import { contextAboutTool, setAboutToolList } from "./context-about"
+import type { ToolModule, ToolResult, ToolSchema } from "./types"
+
+const ALL: ToolModule[] = [
+  getContextTool,
+  contextIngestTool,
+  contextGraphTool,
+  contextRebuildTool,
+  contextRelateTool,
+  contextAboutTool,
+]
+
+export interface ResolvedTools {
+  /** Capability-gated schemas, for ListTools (and the about report). */
+  schemas: ToolSchema[]
+  /** name → handler for CallTool dispatch (only available tools are present). */
+  dispatch: Map<string, ToolModule["handler"]>
+}
+
+export function resolveTools(backend: ContextBackend): ResolvedTools {
+  const active = ALL.filter((t) => (t.available ? t.available(backend) : true))
+  const schemas = active.map((t) => t.schema)
+  const dispatch = new Map(active.map((t) => [t.schema.name, t.handler]))
+  // Keep context_about's "## Tools" listing in sync with what's actually exposed.
+  setAboutToolList(schemas)
+  return { schemas, dispatch }
+}
+
+export type { ToolModule, ToolResult, ToolSchema }

package/src/mcp/tools/types.ts

@@ -0,0 +1,33 @@
+// Shared shapes for the modular MCP tools. Each tool module exports its name,
+// its JSON input schema (the entry that used to live in server.ts's TOOLS array),
+// and an async handler `(args, backend) => result`. A tool may be GATED behind a
+// backend capability via `available(backend)` - when it returns false the tool is
+// not listed and not dispatchable (identical to the old `...(backend.x ? [...] : [])`).
+
+import type { ContextBackend } from "../backend"
+
+export interface ToolResult {
+  content: Array<{ type: "text"; text: string }>
+  isError?: boolean
+  // The MCP SDK's ServerResult union accepts an open record; this index signature
+  // lets ToolResult satisfy that branch (so handlers don't need the task-result fields).
+  [key: string]: unknown
+}
+
+export interface ToolSchema {
+  name: string
+  description: string
+  inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] }
+}
+
+export interface ToolModule {
+  schema: ToolSchema
+  handler: (args: Record<string, unknown>, backend: ContextBackend) => Promise<ToolResult>
+  /** Optional capability gate; defaults to always-available when omitted. */
+  available?: (backend: ContextBackend) => boolean
+}
+
+/** Slugify a title into a record-id prefix. */
+export function slug(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "note"
+}

package/src/permission.ts

@@ -0,0 +1,72 @@
+// Ported from PipesHub `backend/python/app/models/permission.py`.
+// The ACL primitive: a permission is an edge from a principal (user/group/role/
+// domain/org/team/anyone) to a record, carrying a role. Mirrors the sharing
+// semantics of the source systems (Drive/Slack), so enforcement at query time is
+// just a graph traversal over these edges.
+
+export enum PermissionType {
+  READ = "READER",
+  WRITE = "WRITER",
+  OWNER = "OWNER",
+  COMMENT = "COMMENTER",
+  OTHER = "OTHERS",
+}
+
+export enum EntityType {
+  USER = "USER",
+  GROUP = "GROUP",
+  ROLE = "ROLE",
+  DOMAIN = "DOMAIN",
+  ORG = "ORG",
+  TEAM = "TEAM",
+  ANYONE = "ANYONE",
+  ANYONE_WITH_LINK = "ANYONE_WITH_LINK",
+}
+
+export interface Permission {
+  externalId?: string
+  email?: string
+  type: PermissionType
+  entityType: EntityType
+  createdAt: number
+  updatedAt: number
+}
+
+/** Generic permission-edge shape consumed by the graph store. */
+export interface PermissionEdge {
+  from_id: string
+  from_collection: string
+  to_id: string
+  to_collection: string
+  role: PermissionType
+  type: EntityType
+  createdAtTimestamp: number
+  updatedAtTimestamp: number
+}
+
+export function toGraphPermission(
+  perm: Permission,
+  fromId: string,
+  fromCollection: string,
+  toId: string,
+  toCollection: string,
+): PermissionEdge {
+  return {
+    from_id: fromId,
+    from_collection: fromCollection,
+    to_id: toId,
+    to_collection: toCollection,
+    role: perm.type,
+    type: perm.entityType,
+    createdAtTimestamp: perm.createdAt,
+    updatedAtTimestamp: perm.updatedAt,
+  }
+}
+
+export interface AccessControl {
+  owners: string[]
+  editors: string[]
+  viewers: string[]
+  domains: string[]
+  anyoneWithLink: boolean
+}

package/src/provider.ts

@@ -0,0 +1,65 @@
+// The seams. The ACL + retrieval *logic* is native TS (graph-provider.ts /
+// retrieval.ts); the actual datastores plug in behind these interfaces so the
+// moat stays runtime-agnostic (ArangoDB today, anything tomorrow).
+
+import type { AccessibleMap, RecordDoc, RetrievalFilters, UserDoc } from "./types"
+
+/** Thin transport to ArangoDB. Implement with arangojs or the org's HTTP client. */
+export interface ArangoClient {
+  executeAql(query: string, bindVars: Record<string, unknown>): Promise<any[]>
+}
+
+/** Graph store: identity, the ACL traversal, and record fetches. */
+export interface GraphProvider {
+  /** THE moat: virtualRecordId -> recordId for everything the user may access. */
+  getAccessibleVirtualRecordIds(args: {
+    userId: string
+    orgId: string
+    filters?: RetrievalFilters
+  }): Promise<AccessibleMap>
+
+  getRecordsByRecordIds(recordIds: string[], orgId: string): Promise<RecordDoc[]>
+  getUserByUserId(userId: string): Promise<UserDoc | null>
+  getUserApps(userKey: string): Promise<Array<{ _key?: string; id?: string }>>
+  getDocument(recordId: string, collection: string): Promise<RecordDoc | null>
+}
+
+/** Vector store contract - hybrid (dense + sparse, RRF) search over Qdrant-shaped
+ *  payloads. `filterCollection` builds the must/should filter restricting the
+ *  search to ACL-approved virtualRecordIds. */
+export interface VectorPoint {
+  id: string | number
+  score: number
+  payload: { page_content?: string; metadata?: Record<string, unknown> }
+}
+
+export interface VectorQueryResult {
+  points: VectorPoint[]
+}
+
+export interface VectorDBService {
+  filterCollection(args: {
+    must?: Record<string, unknown>
+    should?: Record<string, unknown>
+  }): Promise<unknown>
+
+  queryNearestPoints(args: {
+    collectionName: string
+    requests: unknown[]
+  }): Promise<VectorQueryResult[]>
+}
+
+/** Embedding provider - dense + sparse (BM25) for hybrid retrieval. `embedDense`
+ *  embeds DOCUMENTS (chunks); `embedQuery` embeds the QUERY. They differ for
+ *  asymmetric models (e.g. EmbeddingGemma's task prefixes); symmetric models leave
+ *  `embedQuery` undefined and callers fall back to `embedDense`. */
+export interface EmbeddingProvider {
+  embedDense(query: string): Promise<number[]>
+  embedQuery?(query: string): Promise<number[]>
+  embedSparse(query: string): Promise<{ indices: number[]; values: number[] }>
+}
+
+/** Embed a QUERY with the asymmetric path when the provider has one, else the doc path. */
+export function embedQueryWith(emb: EmbeddingProvider, text: string): Promise<number[]> {
+  return emb.embedQuery ? emb.embedQuery(text) : emb.embedDense(text)
+}

package/src/qdrant-vector.ts

@@ -0,0 +1,76 @@
+// VectorDBService adapter over Qdrant's HTTP API (no SDK dependency).
+// `filterCollection` builds a Qdrant filter; `queryNearestPoints` runs the hybrid
+// (dense + sparse, RRF) batch query the retrieval spine assembles.
+
+import type { VectorDBService, VectorQueryResult } from "./provider"
+
+export interface QdrantConfig {
+  /** e.g. http://localhost:6333 */
+  url: string
+  apiKey?: string
+  /** payload key prefix for metadata fields (Qdrant stores them under `metadata`). */
+  metadataPrefix?: string
+  fetchImpl?: typeof fetch
+}
+
+/** Qdrant filter condition: match any of the given values for a payload key. */
+interface QdrantCondition {
+  key: string
+  match: { any: unknown[] } | { value: unknown }
+}
+interface QdrantFilter {
+  must?: QdrantCondition[]
+  should?: QdrantCondition[]
+}
+
+export class QdrantVectorService implements VectorDBService {
+  private readonly fetch: typeof fetch
+  private readonly prefix: string
+  constructor(private readonly cfg: QdrantConfig) {
+    this.fetch = cfg.fetchImpl ?? fetch
+    this.prefix = cfg.metadataPrefix ?? "metadata."
+  }
+
+  private headers(): Record<string, string> {
+    const h: Record<string, string> = { "content-type": "application/json" }
+    if (this.cfg.apiKey) h["api-key"] = this.cfg.apiKey
+    return h
+  }
+
+  private conditions(spec?: Record<string, unknown>): QdrantCondition[] {
+    if (!spec) return []
+    return Object.entries(spec).map(([key, val]) => ({
+      key: `${this.prefix}${key}`,
+      match: Array.isArray(val) ? { any: val } : { value: val },
+    }))
+  }
+
+  async filterCollection(args: {
+    must?: Record<string, unknown>
+    should?: Record<string, unknown>
+  }): Promise<QdrantFilter> {
+    const filter: QdrantFilter = {}
+    const must = this.conditions(args.must)
+    const should = this.conditions(args.should)
+    if (must.length) filter.must = must
+    if (should.length) filter.should = should
+    return filter
+  }
+
+  async queryNearestPoints(args: {
+    collectionName: string
+    requests: unknown[]
+  }): Promise<VectorQueryResult[]> {
+    const url = `${this.cfg.url.replace(/\/$/, "")}/collections/${encodeURIComponent(
+      args.collectionName,
+    )}/points/query/batch`
+    const res = await this.fetch(url, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ searches: args.requests }),
+    })
+    const body = (await res.json()) as { result?: Array<{ points: VectorQueryResult["points"] }>; status?: unknown }
+    if (!res.ok) throw new Error(`qdrant query failed: ${res.status} ${JSON.stringify(body.status)}`)
+    return (body.result ?? []).map((r) => ({ points: r.points ?? [] }))
+  }
+}

package/src/retrieval.ts

@@ -0,0 +1,218 @@
+// Ported from PipesHub `modules/retrieval/retrieval_service.py::search_with_filters`.
+//
+// The security-critical invariant, preserved exactly:
+//   1. Compute the user's accessible {virtualRecordId -> recordId} map from the
+//      GRAPH first (ACL). 2. Restrict the vector search to those virtual ids.
+//   3. For every hit, resolve the recordId from the ACCESSIBLE MAP - never from
+//      the vector payload. That step is the cross-connector leak guard: a shared
+//      virtualRecordId only ever resolves to the record THIS user may see.
+//
+// The cosmetic webUrl/mime fallback enrichment for file/mail records
+// (retrieval_service.py:462-532) is intentionally omitted here - it is
+// presentation, not access control. Port it later if you need source links.
+
+import { embedQueryWith, type EmbeddingProvider, type GraphProvider, type VectorDBService, type VectorPoint } from "./provider"
+import {
+  ACCESSIBLE_RECORDS_NOT_FOUND_MESSAGE,
+  RetrievalStatus,
+  type RecordDoc,
+  type RetrievalFilters,
+  type RetrievalResponse,
+  type SearchResult,
+  type UserDoc,
+} from "./types"
+
+const REQUIRED_FIELDS = ["origin", "recordName", "recordId", "mimeType", "orgId"] as const
+
+export interface RetrievalDeps {
+  graph: GraphProvider
+  vector: VectorDBService
+  embeddings: EmbeddingProvider
+  collectionName: string
+  log?: { info: (m: string) => void; debug: (m: string) => void; error: (m: string) => void }
+}
+
+export class RetrievalService {
+  constructor(private readonly deps: RetrievalDeps) {}
+  private get log() {
+    return this.deps.log ?? { info() {}, debug() {}, error() {} }
+  }
+
+  async searchWithFilters(args: {
+    queries: string[]
+    userId: string
+    orgId: string
+    filterGroups?: RetrievalFilters
+    limit?: number
+    virtualRecordIdsFromTool?: string[]
+  }): Promise<RetrievalResponse> {
+    const { queries, userId, orgId } = args
+    const limit = args.limit ?? 20
+    const filterGroups = args.filterGroups ?? {}
+    const kbIds = filterGroups.kb
+
+    try {
+      // (1) ACL + user, in parallel.
+      const [accessibleMap, user] = await Promise.all([
+        this.deps.graph.getAccessibleVirtualRecordIds({ userId, orgId, filters: filterGroups }),
+        this.deps.graph.getUserByUserId(userId),
+      ])
+
+      if (Object.keys(accessibleMap).length === 0) {
+        this.log.error(`No accessible documents for user ${userId} org ${orgId}`)
+        return this.empty(ACCESSIBLE_RECORDS_NOT_FOUND_MESSAGE, RetrievalStatus.ACCESSIBLE_RECORDS_NOT_FOUND)
+      }
+
+      // (2) Vector filter restricted to ACL-approved virtual ids.
+      const filter = args.virtualRecordIdsFromTool
+        ? await this.deps.vector.filterCollection({
+            must: { orgId, virtualRecordId: args.virtualRecordIdsFromTool },
+          })
+        : await this.deps.vector.filterCollection({
+            must: { orgId },
+            should: { virtualRecordId: Object.keys(accessibleMap) },
+          })
+
+      const searchResults = await this.executeParallelSearches(queries, filter, limit)
+      if (searchResults.length === 0)
+        return this.empty(
+          "No relevant documents found for your search query. Try different keywords.",
+          RetrievalStatus.EMPTY_RESPONSE,
+        )
+
+      const returnedVirtualIds = [
+        ...new Set(
+          searchResults
+            .map((r) => r.metadata?.virtualRecordId)
+            .filter((v): v is string => v != null),
+        ),
+      ]
+      if (returnedVirtualIds.length === 0)
+        return this.empty(ACCESSIBLE_RECORDS_NOT_FOUND_MESSAGE, RetrievalStatus.ACCESSIBLE_RECORDS_NOT_FOUND)
+
+      // (3) THE leak guard: resolve recordIds ONLY through the accessible map.
+      const recordIdsToFetch = [
+        ...new Set(returnedVirtualIds.filter((v) => v in accessibleMap).map((v) => accessibleMap[v])),
+      ]
+
+      const fetched = await this.deps.graph.getRecordsByRecordIds(recordIdsToFetch, orgId)
+      if (!fetched || fetched.length === 0)
+        return this.empty(ACCESSIBLE_RECORDS_NOT_FOUND_MESSAGE, RetrievalStatus.ACCESSIBLE_RECORDS_NOT_FOUND)
+
+      const recordById = new Map<string, RecordDoc>()
+      for (const r of fetched) if (r?._key) recordById.set(r._key, r)
+
+      // Enrich each result with its (permission-verified) record metadata.
+      const enriched: SearchResult[] = []
+      for (const result of searchResults) {
+        const vid = result.metadata?.virtualRecordId
+        if (vid == null || !(vid in accessibleMap)) continue // not permitted → drop
+        const recordId = accessibleMap[vid]
+        const record = recordById.get(recordId)
+        result.metadata.recordId = recordId
+        if (record) {
+          result.metadata.origin = record.origin
+          result.metadata.connector = record.connectorName ?? null
+          result.metadata.connectorId = record.connectorId ?? null
+          result.metadata.kbId = record.kbId ?? null
+          result.metadata.recordName = record.recordName
+          result.metadata.orgId = orgId
+          let weburl = record.webUrl
+          if (weburl?.startsWith("https://mail.google.com/mail?authuser=") && (user as UserDoc | null)?.email)
+            weburl = weburl.replace("{user.email}", (user as UserDoc).email!)
+          if (weburl) result.metadata.webUrl = weburl
+          if (record.mimeType) result.metadata.mimeType = record.mimeType
+        }
+        enriched.push(result)
+      }
+
+      enriched.sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+
+      // Drop results missing fields citation validation requires.
+      const complete = enriched.filter((r) => {
+        if (!r.content) return false
+        return REQUIRED_FIELDS.every((f) => (r.metadata as Record<string, unknown>)[f] != null)
+      })
+
+      const records = recordIdsToFetch.map((id) => recordById.get(id)).filter((r): r is RecordDoc => Boolean(r))
+
+      if (complete.length === 0 && records.length === 0)
+        return this.empty(
+          "No relevant documents found for your search query.",
+          RetrievalStatus.EMPTY_RESPONSE,
+        )
+
+      const resp: RetrievalResponse = {
+        searchResults: complete,
+        records,
+        status: RetrievalStatus.SUCCESS,
+        statusCode: 200,
+        message: "Query processed successfully. Relevant records retrieved.",
+      }
+      if (kbIds?.length) resp.appliedFilters = { kb: kbIds, kb_count: kbIds.length }
+      return resp
+    } catch (e) {
+      this.log.error(`Filtered search failed: ${String(e)}`)
+      return this.empty("Unexpected server error during search.", RetrievalStatus.ERROR)
+    }
+  }
+
+  // Hybrid dense+sparse retrieval with RRF fusion. The request shape is
+  // Qdrant-flavored; the VectorDBService adapter forwards it to the client.
+  private async executeParallelSearches(
+    queries: string[],
+    filter: unknown,
+    limit: number,
+  ): Promise<SearchResult[]> {
+    const requests = await Promise.all(
+      queries.map(async (q) => {
+        const [dense, sparse] = await Promise.all([
+          embedQueryWith(this.deps.embeddings, q), // QUERY embedding (asymmetric-aware)
+          this.deps.embeddings.embedSparse(q),
+        ])
+        return {
+          prefetch: [
+            { query: dense, using: "dense", limit: limit * 2, filter },
+            { query: sparse, using: "sparse", limit: limit * 2, filter },
+          ],
+          query: { fusion: "RRF" },
+          with_payload: true,
+          limit,
+          filter,
+        }
+      }),
+    )
+
+    const results = await this.deps.vector.queryNearestPoints({
+      collectionName: this.deps.collectionName,
+      requests,
+    })
+
+    const seen = new Set<string | number>()
+    const out: SearchResult[] = []
+    for (const r of results)
+      for (const p of r.points as VectorPoint[]) {
+        if (seen.has(p.id)) continue
+        seen.add(p.id)
+        const metadata = { ...(p.payload.metadata ?? {}), point_id: p.id }
+        out.push({
+          score: p.score,
+          citationType: "vectordb|document",
+          metadata,
+          content: p.payload.page_content ?? "",
+        })
+      }
+    return out
+  }
+
+  private empty(message: string, status: RetrievalStatus): RetrievalResponse {
+    const codes: Record<RetrievalStatus, number> = {
+      [RetrievalStatus.SUCCESS]: 200,
+      [RetrievalStatus.ERROR]: 500,
+      [RetrievalStatus.ACCESSIBLE_RECORDS_NOT_FOUND]: 404,
+      [RetrievalStatus.VECTOR_DB_EMPTY]: 503,
+      [RetrievalStatus.EMPTY_RESPONSE]: 200,
+    }
+    return { searchResults: [], records: [], status, statusCode: codes[status] ?? 500, message }
+  }
+}