@100xprompt/chitta 0.1.0

package/src/embedded/reranker.ts

@@ -0,0 +1,62 @@
+// Cross-encoder reranker - the final, highest-precision retrieval stage. After RRF
+// fuses BM25+dense+graph into a high-RECALL candidate pool, a cross-encoder fixes the
+// ORDERING: it jointly attends over (query, passage) and scores true relevance -
+// exactly the dimension rank-only RRF is weakest at (+5-15 pts ranking precision in
+// 2026 benchmarks). We use the distilled ms-marco-MiniLM-L-6-v2 (~22M params) via
+// transformers.js/ONNX, int8 - same in-process, no-server footprint as our embedder.
+//
+// OPTIONAL (like @huggingface/transformers): if the model can't load, rank() returns
+// null and the caller keeps the RRF order. Never throws, never blocks retrieval.
+
+export interface Reranker {
+  /** Score each doc's relevance to the query (higher = better). null ⇒ unavailable. */
+  rank(query: string, docs: string[]): Promise<number[] | null>
+}
+
+const DEFAULT_MODEL = process.env.CONTEXT_RERANK_MODEL || "Xenova/ms-marco-MiniLM-L-6-v2"
+
+export class CrossEncoderReranker implements Reranker {
+  private model: unknown | null = null
+  private tokenizer: unknown | null = null
+  private failed = false
+  private loading: Promise<void> | null = null
+  constructor(private readonly modelId: string = DEFAULT_MODEL) {}
+
+  private async ensure(): Promise<boolean> {
+    if (this.failed) return false
+    if (this.model && this.tokenizer) return true
+    if (!this.loading) {
+      this.loading = (async () => {
+        try {
+          const t: any = await import("@huggingface/transformers")
+          this.tokenizer = await t.AutoTokenizer.from_pretrained(this.modelId)
+          this.model = await t.AutoModelForSequenceClassification.from_pretrained(this.modelId, { quantized: true })
+        } catch {
+          this.failed = true // model unavailable (not downloaded / offline) → graceful no-op
+        }
+      })()
+    }
+    await this.loading
+    return !this.failed && !!this.model
+  }
+
+  async rank(query: string, docs: string[]): Promise<number[] | null> {
+    if (docs.length === 0) return []
+    if (!(await this.ensure())) return null
+    try {
+      const tok = this.tokenizer as any
+      const model = this.model as any
+      // cross-encoder: each example is (query, doc) via text_pair
+      const inputs = tok(new Array(docs.length).fill(query), { text_pair: docs, padding: true, truncation: true })
+      const { logits } = await model(inputs)
+      const data = Array.from(logits.data as Iterable<number>)
+      const cols = logits.dims[logits.dims.length - 1] as number
+      // relevance logit: single-logit head → that value; 2-logit → positive class.
+      const out: number[] = []
+      for (let i = 0; i < docs.length; i++) out.push(cols === 1 ? data[i] : data[i * cols + (cols - 1)])
+      return out
+    } catch {
+      return null
+    }
+  }
+}

package/src/embedded/retrieval/decay-stage.ts

@@ -0,0 +1,59 @@
+// Re-rank stage: PERSONAL BOOST + MEMORY DECAY / SALIENCE.
+//
+// Personal boost: a multiplier on the RRF score for records the user owns.
+// NB: no magnet penalty by RECORD SIZE - that wrongly punishes a record for being
+// thoroughly chunked (a 20-fact news page is not a "magnet"). Flooding is handled
+// structurally by the DIVERSITY CAP (≤ maxPerRecord per record in results), and BM25
+// already favors the term-matching chunk over generic ones.
+//
+// MEMORY DECAY / SALIENCE (Generative-Agents / ACT-R): gently re-weight by recency
+// × access-frequency × importance so fresh/important/often-used memories surface
+// over stale ones - NEVER deletes. Records with no timestamp (legacy) stay neutral.
+import type { SqliteStore } from "../sqlite-store"
+import type { FusedResult } from "./fuse"
+
+export interface DecayConfig {
+  personalBoost: number
+  maxPerRecord: number
+  decayOn: boolean
+  lambda: number
+  decayFloor: number
+  accessW: number
+}
+
+export function decayConfig(): DecayConfig {
+  const decayOn = !/^(0|false|off)$/i.test(process.env.CONTEXT_DECAY ?? "1")
+  return {
+    personalBoost: Number(process.env.CONTEXT_PERSONAL_BOOST ?? 1.2),
+    maxPerRecord: Number(process.env.CONTEXT_MAX_PER_RECORD ?? 2),
+    decayOn,
+    lambda: Math.LN2 / Math.max(1, Number(process.env.CONTEXT_DECAY_HALFLIFE_DAYS ?? 60)),
+    decayFloor: Number(process.env.CONTEXT_DECAY_FLOOR ?? 0.5),
+    accessW: Number(process.env.CONTEXT_DECAY_ACCESS_W ?? 0.15),
+  }
+}
+
+// Mutates each merged item's `rrf` in place by personal boost + decay/salience, then
+// sorts the list descending by rrf.
+export function decayStage(store: SqliteStore, merged: FusedResult[], userId: string, cfg: DecayConfig): void {
+  const recIds = [...new Set(merged.map((r) => r.metadata.recordId).filter(Boolean) as string[])]
+  const ownerMap = new Map<string, string>()
+  if (recIds.length)
+    for (const row of store.db
+      .query(`SELECT id, json_extract(data,'$.ownerId') o FROM nodes WHERE id IN (${recIds.map(() => "?").join(",")})`)
+      .all(...recIds) as Array<{ id: string; o: string | null }>)
+      if (row.o) ownerMap.set(row.id, row.o)
+  const now = Date.now()
+  const salience = cfg.decayOn ? store.recordSalience(recIds) : null
+  for (const r of merged) {
+    if (ownerMap.get(r.metadata.recordId as string) === userId) r.rrf *= cfg.personalBoost
+    const s = salience?.get(r.metadata.recordId as string)
+    if (s && s.lastAccessedAt > 0) {
+      const ageDays = Math.max(0, (now - s.lastAccessedAt) / 86_400_000)
+      const recency = Math.exp(-cfg.lambda * ageDays)
+      const accessBoost = 1 + cfg.accessW * Math.log1p(s.accessCount)
+      r.rrf *= (s.importance || 1) * (cfg.decayFloor + (1 - cfg.decayFloor) * recency) * accessBoost
+    }
+  }
+  merged.sort((a, b) => b.rrf - a.rrf)
+}

package/src/embedded/retrieval/diversity.ts

@@ -0,0 +1,37 @@
+// Diversity cap + passage extraction - no more than maxPerRecord chunks from any
+// single record, with each surviving chunk reduced to its best matching passage.
+import type { SqliteStore } from "../sqlite-store"
+import type { SearchResult } from "../../types"
+import type { FusedResult } from "./fuse"
+import { bestPassage, queryTokens } from "./passage"
+
+export function diversityStage(
+  store: SqliteStore,
+  ordered: FusedResult[],
+  query: string,
+  cutoff: number,
+  maxPerRecord: number,
+  topk: number,
+  decayOn: boolean,
+): SearchResult[] {
+  const terms = queryTokens(query)
+  const keyOf = (r: SearchResult) => (r.metadata.point_id as string) ?? `${r.metadata.virtualRecordId ?? ""}|${r.content.slice(0, 80)}`
+  const perRecord = new Map<string, number>()
+  const relevant: SearchResult[] = []
+  for (const r of ordered) {
+    if (r.rrf < cutoff) continue
+    // passage extraction: the exact matching line, not the whole digest chunk.
+    // Empty ⇒ the chunk was all boilerplate (cookie/nav) ⇒ drop it entirely.
+    const passage = bestPassage(r.content, terms)
+    if (!passage) continue
+    const recKey = (r.metadata.recordId as string) ?? (r.metadata.virtualRecordId as string) ?? keyOf(r)
+    const n = perRecord.get(recKey) ?? 0
+    if (n >= maxPerRecord) continue
+    perRecord.set(recKey, n + 1)
+    relevant.push({ score: r.score, citationType: r.citationType, content: passage, metadata: r.metadata })
+    if (relevant.length >= topk) break
+  }
+  // record the access (recency + frequency) of what we actually returned.
+  if (decayOn) store.touchRecords([...new Set(relevant.map((r) => r.metadata.recordId as string).filter(Boolean))])
+  return relevant
+}

package/src/embedded/retrieval/fuse.ts

@@ -0,0 +1,52 @@
+// Reciprocal Rank Fusion (RRF) - fuse the dense/sparse/graph signal lists into one
+// ranked list with no score-scale calibration. RRF score = Σ 1/(k + rank) across the
+// lists a chunk appears in (k=60), so a chunk strong in ANY signal surfaces, and one
+// strong in several rises to the top.
+import type { SqliteStore } from "../sqlite-store"
+import type { AccessibleMap, SearchResult } from "../../types"
+
+export type FusedResult = SearchResult & { rrf: number; legs: Set<string> }
+
+export function rrfFuse(
+  dense: SearchResult[],
+  bm25: SearchResult[],
+  graphList: SearchResult[],
+  K: number,
+): FusedResult[] {
+  const keyOf = (r: SearchResult) => (r.metadata.point_id as string) ?? `${r.metadata.virtualRecordId ?? ""}|${r.content.slice(0, 80)}`
+  const fused = new Map<string, FusedResult>()
+  // `leg` tags WHICH signal (vector / keyword / graph) found each item - captured for
+  // the retrieval trace so the UI can show how a result was retrieved.
+  const fuse = (list: SearchResult[], leg: string) =>
+    list.forEach((r, i) => {
+      const k = keyOf(r)
+      const ex = fused.get(k)
+      if (ex) {
+        ex.rrf += 1 / (K + i + 1)
+        ex.legs.add(leg)
+        if (!ex.metadata.recordName && r.metadata.recordName) ex.metadata = { ...ex.metadata, ...r.metadata }
+      } else fused.set(k, { ...r, rrf: 1 / (K + i + 1), legs: new Set([leg]) })
+    })
+  fuse(dense, "vector")
+  fuse(bm25, "keyword")
+  fuse(graphList, "graph")
+  return [...fused.values()]
+}
+
+// Backfill recordName/recordId for BM25-only items (so citations resolve).
+export function backfillMeta(store: SqliteStore, merged: FusedResult[], accMap: AccessibleMap): void {
+  const needMeta = merged.filter((r) => !r.metadata.recordName && r.metadata.virtualRecordId)
+  if (needMeta.length) {
+    const want = [...new Set(needMeta.map((r) => accMap[r.metadata.virtualRecordId as string]).filter(Boolean) as string[])]
+    const nameById = new Map<string, string>()
+    if (want.length)
+      for (const row of store.db
+        .query(`SELECT id, json_extract(data,'$.recordName') n FROM nodes WHERE id IN (${want.map(() => "?").join(",")})`)
+        .all(...want) as Array<{ id: string; n: string | null }>)
+        nameById.set(row.id, row.n ?? "")
+    for (const r of needMeta) {
+      const rid = accMap[r.metadata.virtualRecordId as string]
+      if (rid) r.metadata = { ...r.metadata, recordId: rid, recordName: nameById.get(rid) || r.metadata.recordName }
+    }
+  }
+}

package/src/embedded/retrieval/graph-stage.ts

@@ -0,0 +1,45 @@
+// Signal 3: GRAPH expansion (GraphRAG) - chunks reachable through related concepts.
+import type { SqliteGraphProvider } from "../sqlite-graph-provider"
+import type { SqliteStore } from "../sqlite-store"
+import { embedQueryWith, type EmbeddingProvider } from "../../provider"
+import type { AccessibleMap, SearchResult } from "../../types"
+import { cosine } from "./passage"
+
+export async function graphStage(
+  graph: SqliteGraphProvider,
+  store: SqliteStore,
+  embeddings: EmbeddingProvider,
+  query: string,
+  orgId: string,
+  dense: SearchResult[],
+  accMap: AccessibleMap,
+): Promise<SearchResult[]> {
+  const graphList: SearchResult[] = []
+  const seeds = [...new Set(dense.map((r) => r.metadata.recordId).filter(Boolean) as string[])]
+  if (seeds.length) {
+    const related = graph.getRelatedRecordIds(seeds, [...new Set(Object.values(accMap))], 5)
+    if (related.length) {
+      const q = await embedQueryWith(embeddings, query)
+      const seen = new Set(dense.map((r) => r.metadata.virtualRecordId))
+      const records = await graph.getRecordsByRecordIds(related, orgId)
+      for (const rec of records) {
+        const vid = (rec.virtualRecordId as string) ?? rec._key
+        if (seen.has(vid)) continue
+        const rows = store.db.query("SELECT content, embedding FROM chunks WHERE virtual_record_id = ?").all(vid) as Array<{ content: string; embedding: string }>
+        let best: { content: string; score: number } | null = null
+        for (const row of rows) {
+          const s = cosine(q, JSON.parse(row.embedding) as number[])
+          if (!best || s > best.score) best = { content: row.content, score: s }
+        }
+        if (best)
+          graphList.push({
+            score: best.score,
+            citationType: "graph|related",
+            content: best.content,
+            metadata: { recordName: rec.recordName, recordId: rec._key, virtualRecordId: vid, orgId, origin: rec.origin, mimeType: rec.mimeType },
+          })
+      }
+    }
+  }
+  return graphList
+}

package/src/embedded/retrieval/hybrid-retriever.ts

@@ -0,0 +1,80 @@
+// HYBRID retrieval orchestrator - three complementary signals fused with Reciprocal
+// Rank Fusion (the 2026 production default), then re-ranked. Signals:
+//   • DENSE  (vector + ACL) - semantic similarity (paraphrase, meaning).
+//   • SPARSE (BM25 / FTS5)  - exact tokens dense misses (acronyms "SAP", "£230M").
+//   • GRAPH  (GraphRAG)     - chunks reachable through related concepts.
+// RRF score = Σ 1/(k + rank) across the lists a chunk appears in (k=60), so a chunk
+// strong in ANY signal surfaces, and one strong in several rises to the top - with no
+// score-scale calibration between cosine and BM25. Then: personal boost (ownership),
+// memory decay/salience, cross-encoder rerank, passage extraction, diversity cap (MMR).
+// All tunable via CONTEXT_* env.
+import type { RetrievalService } from "../../retrieval"
+import type { SqliteStore } from "../sqlite-store"
+import type { SqliteGraphProvider } from "../sqlite-graph-provider"
+import type { Reranker } from "../reranker"
+import type { EmbeddingProvider } from "../../provider"
+import type { RetrievalResponse } from "../../types"
+import { vectorStage } from "./vector-stage"
+import { keywordStage } from "./keyword-stage"
+import { graphStage } from "./graph-stage"
+import { rrfFuse, backfillMeta } from "./fuse"
+import { decayConfig, decayStage } from "./decay-stage"
+import { rerankStage } from "./rerank-stage"
+import { diversityStage } from "./diversity"
+import { populateTrace, type SearchTrace } from "./trace"
+
+export interface HybridDeps {
+  retrieval: RetrievalService
+  store: SqliteStore
+  graph: SqliteGraphProvider
+  embeddings: EmbeddingProvider
+  reranker?: Reranker
+}
+
+export async function hybridSearch(
+  deps: HybridDeps,
+  query: string,
+  userId: string,
+  orgId: string,
+  trace?: SearchTrace,
+): Promise<RetrievalResponse> {
+  const { retrieval, store, graph, embeddings, reranker } = deps
+  const retrieveLimit = Number(process.env.CONTEXT_RETRIEVE_LIMIT ?? 20)
+  const accMap = await graph.getAccessibleVirtualRecordIds({ userId, orgId })
+  const accessibleVids = new Set(Object.keys(accMap))
+
+  // ── signal 1: DENSE (vector + ACL) ──
+  const { dense, res } = await vectorStage(retrieval, query, userId, orgId, retrieveLimit)
+
+  // ── signal 2: SPARSE (BM25) ──
+  const bm25 = keywordStage(store, query, orgId, accessibleVids, retrieveLimit)
+
+  // ── signal 3: GRAPH expansion (concept-connected chunks) ──
+  const graphList = await graphStage(graph, store, embeddings, query, orgId, dense, accMap)
+
+  // ── Reciprocal Rank Fusion ──
+  const K = Number(process.env.CONTEXT_RRF_K ?? 60)
+  const merged = rrfFuse(dense, bm25, graphList, K)
+  backfillMeta(store, merged, accMap)
+
+  // ── re-rank: personal boost + memory decay/salience (sorts merged) ──
+  const cfg = decayConfig()
+  decayStage(store, merged, userId, cfg)
+
+  const topk = Number(process.env.CONTEXT_TOPK ?? 6)
+  const ratio = Number(process.env.CONTEXT_RRF_RATIO ?? 0.3) // relative cutoff on fused score
+  const initialCutoff = (merged[0]?.rrf ?? 0) * ratio
+
+  // ── final stage: CROSS-ENCODER RERANK (optional) ──
+  const { ordered, cutoff, rerankerUsed } = await rerankStage(reranker, query, merged, initialCutoff)
+
+  // ── passage extraction + diversity cap + topk (+ access touch) ──
+  const relevant = diversityStage(store, ordered, query, cutoff, cfg.maxPerRecord, topk, cfg.decayOn)
+
+  // retrieval trace for the UI: counts per signal + which legs found each top item.
+  if (trace) populateTrace(trace, dense, bm25, graphList, merged, ordered, rerankerUsed)
+
+  return { ...res, searchResults: relevant }
+}
+
+export type { SearchTrace } from "./trace"

package/src/embedded/retrieval/keyword-stage.ts

@@ -0,0 +1,27 @@
+// Signal 2: SPARSE (BM25 / FTS5) - exact tokens dense misses (acronyms "SAP", "£230M").
+// ACL-filtered to accessible records, fts rank order kept.
+import type { SqliteStore } from "../sqlite-store"
+import type { SearchResult } from "../../types"
+
+export function keywordStage(
+  store: SqliteStore,
+  query: string,
+  orgId: string,
+  accessibleVids: Set<string>,
+  retrieveLimit: number,
+): SearchResult[] {
+  const bm25: SearchResult[] = []
+  const ftsRowids = store.ftsSearch(query, retrieveLimit)
+  if (ftsRowids.length) {
+    const rows = store.db
+      .query(`SELECT rowid, point_id, virtual_record_id v, org_id o, content FROM chunks WHERE rowid IN (${ftsRowids.map(() => "?").join(",")})`)
+      .all(...ftsRowids) as Array<{ rowid: number; point_id: string; v: string; o: string; content: string }>
+    const byRow = new Map(rows.map((r) => [r.rowid, r]))
+    for (const rid of ftsRowids) {
+      const r = byRow.get(rid)
+      if (!r || r.o !== orgId || !accessibleVids.has(r.v)) continue // ACL
+      bm25.push({ score: 0, citationType: "bm25", content: r.content, metadata: { virtualRecordId: r.v, orgId, point_id: r.point_id } })
+    }
+  }
+  return bm25
+}

package/src/embedded/retrieval/passage.ts

@@ -0,0 +1,44 @@
+// Passage-extraction helpers - shared across rerank, diversity and trace stages.
+import { cleanLine, isBoilerplate } from "../extract"
+
+export function cosine(a: number[], b: number[]): number {
+  let dot = 0
+  let na = 0
+  let nb = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    dot += a[i] * b[i]
+    na += a[i] * a[i]
+    nb += b[i] * b[i]
+  }
+  return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0
+}
+
+// Query tokenizer for passage scoring - meaningful tokens only (acronyms/numbers kept).
+export function queryTokens(query: string): string[] {
+  return [...new Set((query.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((t) => t.length >= 3))]
+}
+
+// PASSAGE EXTRACTION - a retrieved chunk can be a coarse multi-fact digest (a whole
+// scraped page), so returning the whole chunk buries the answer. We split it into
+// sentences/lines, drop markdown + boilerplate, and return the line that best matches
+// the query terms (term-length-weighted, so specific/rare terms dominate). This turns
+// "matched the right digest" into "returned the exact fact" - at read time, no
+// re-ingest, and it transparently skips any leftover cookie/nav line in a chunk.
+export function bestPassage(content: string, terms: string[]): string {
+  const lines = content
+    .trim()
+    .split(/\n|(?<=[.!?])\s+/)
+    .map((l) => cleanLine(l))
+    .filter((l) => l.length > 0 && !isBoilerplate(l))
+  if (lines.length === 0) return "" // all boilerplate / no substance → caller drops it
+  if (lines.length === 1) return lines[0]
+  let best: { line: string; score: number } | null = null
+  for (const line of lines) {
+    const low = line.toLowerCase()
+    let score = 0
+    for (const t of terms) if (low.includes(t)) score += t.length // rarer/longer terms weigh more
+    if (score > 0 && (!best || score > best.score)) best = { line, score }
+  }
+  return best ? best.line : lines[0]
+}

package/src/embedded/retrieval/rerank-stage.ts

@@ -0,0 +1,31 @@
+// Final stage: CROSS-ENCODER RERANK (optional).
+// RRF maximizes recall; the cross-encoder fixes ORDERING by jointly scoring
+// (query, passage). Rerank only the top-K candidates (cost is linear), reorder, and
+// drop the rrf-relative cutoff (rerank logits aren't on the rrf scale).
+import type { Reranker } from "../reranker"
+import type { FusedResult } from "./fuse"
+import { bestPassage, queryTokens } from "./passage"
+
+export async function rerankStage(
+  reranker: Reranker | undefined,
+  query: string,
+  merged: FusedResult[],
+  initialCutoff: number,
+): Promise<{ ordered: FusedResult[]; cutoff: number; rerankerUsed: boolean }> {
+  let ordered = merged
+  let cutoff = initialCutoff
+  let rerankerUsed = false
+  if (reranker && merged.length > 1) {
+    const rerankK = Number(process.env.CONTEXT_RERANK_K ?? 20)
+    const cand = merged.slice(0, rerankK)
+    const scores = await reranker.rank(query, cand.map((c) => bestPassage(c.content, queryTokens(query)) || c.content))
+    if (scores) {
+      cand.forEach((c, i) => (c.rrf = scores[i]))
+      cand.sort((a, b) => b.rrf - a.rrf)
+      ordered = [...cand, ...merged.slice(rerankK)]
+      cutoff = -Infinity // reranker decided relevance; keep its order, no rrf cutoff
+      rerankerUsed = true
+    }
+  }
+  return { ordered, cutoff, rerankerUsed }
+}

package/src/embedded/retrieval/trace.ts

@@ -0,0 +1,31 @@
+// Retrieval trace - how a query flowed through the pipeline, for the UI's "how it
+// retrieved" panel. counts = items each signal returned; items = the top fused/reranked
+// results tagged with WHICH signals (vector / keyword / graph) found them.
+import type { SearchResult } from "../../types"
+import type { FusedResult } from "./fuse"
+
+export interface SearchTrace {
+  counts: { vector: number; keyword: number; graph: number; fused: number }
+  reranked: boolean
+  items: Array<{ label: string; recordId?: string; legs: string[]; rrf: number; rank: number }>
+}
+
+export function populateTrace(
+  trace: SearchTrace,
+  dense: SearchResult[],
+  bm25: SearchResult[],
+  graphList: SearchResult[],
+  merged: FusedResult[],
+  ordered: FusedResult[],
+  rerankerUsed: boolean,
+): void {
+  trace.counts = { vector: dense.length, keyword: bm25.length, graph: graphList.length, fused: merged.length }
+  trace.reranked = rerankerUsed
+  trace.items = ordered.slice(0, 8).map((r, i) => ({
+    label: (r.metadata.recordName as string) ?? (r.metadata.recordId as string) ?? "?",
+    recordId: r.metadata.recordId as string,
+    legs: [...r.legs],
+    rrf: r.rrf,
+    rank: i,
+  }))
+}

package/src/embedded/retrieval/vector-stage.ts

@@ -0,0 +1,15 @@
+// Signal 1: DENSE (vector + ACL) - semantic similarity (paraphrase, meaning).
+import type { RetrievalService } from "../../retrieval"
+import type { SearchResult } from "../../types"
+
+export async function vectorStage(
+  retrieval: RetrievalService,
+  query: string,
+  userId: string,
+  orgId: string,
+  retrieveLimit: number,
+): Promise<{ dense: SearchResult[]; res: Awaited<ReturnType<RetrievalService["searchWithFilters"]>> }> {
+  const res = await retrieval.searchWithFilters({ queries: [query], userId, orgId, limit: retrieveLimit })
+  const dense: SearchResult[] = [...res.searchResults]
+  return { dense, res }
+}

package/src/embedded/sqlite-graph-provider.ts

@@ -0,0 +1,119 @@
+// GraphProvider over bun:sqlite - the ACL traversal ported from AQL to SQL.
+//
+// The Arango version ran eight permission paths; here they collapse to the same
+// access semantics expressed over the generic node/edge tables:
+//   • principals = the user + every group/role/org/team they belong to or are
+//     permissioned to (one hop).
+//   • directRecords = records permissioned to any principal.
+//   • recordGroups  = record-groups permissioned to any principal, then both:
+//       - inheritedRecords (recursive descent over inheritPermissions), and
+//       - kbRecords (records that belong to those groups, origin=UPLOAD).
+//   • anyoneRecords = org-wide shared records.
+// All unioned, then deduped first-writer-wins → { virtualRecordId: recordId }.
+// Same invariant as the Arango port; only the query language differs.
+//
+// This file is the ORCHESTRATOR: it owns the bun:sqlite handle and the row/
+// placeholder helpers, and delegates the permission-path SQL to ./graph/acl-paths
+// and the entity/edge assembly to ./graph/knowledge-graph (where the per-edge
+// provenance leak-guard lives).
+
+import type { GraphProvider } from "../provider"
+import type { AccessibleMap, RecordDoc, RetrievalFilters, UserDoc } from "../types"
+import * as acl from "./graph/acl-paths"
+import * as kg from "./graph/knowledge-graph"
+import type { Pair, SqlAccess } from "./graph/sql-access"
+import type { SqliteStore } from "./sqlite-store"
+
+export class SqliteGraphProvider implements GraphProvider {
+  constructor(private readonly store: SqliteStore) {}
+  private get db() {
+    return this.store.db
+  }
+  private rows<T = any>(sql: string, params: unknown[]): T[] {
+    return this.db.query(sql).all(...(params as any[])) as T[]
+  }
+  private ph(n: number): string {
+    return Array.from({ length: n }, () => "?").join(",")
+  }
+  // The SQL-access seam handed to the decomposed query modules.
+  private get sql(): SqlAccess {
+    return { rows: this.rows.bind(this), ph: this.ph.bind(this) }
+  }
+
+  async getAccessibleVirtualRecordIds(args: {
+    userId: string
+    orgId: string
+    filters?: RetrievalFilters
+  }): Promise<AccessibleMap> {
+    const user = acl.userRow(this.sql, args.userId)
+    if (!user) return {} // deny by default
+    const f = args.filters ?? {}
+
+    const principals = acl.principalIds(this.sql, user.id)
+    const recordGroups = acl.recordGroupsPermissionedTo(this.sql, principals, f.kb)
+
+    const all: Pair[] = [
+      ...acl.recordsPermissionedTo(this.sql, principals, f.apps),
+      ...acl.recordsInheritingFrom(this.sql, recordGroups),
+      ...acl.kbRecords(this.sql, recordGroups),
+      ...acl.anyoneRecords(this.sql, args.orgId),
+    ]
+
+    const map: AccessibleMap = {}
+    for (const { vid, rid } of all) if (vid && rid && !(vid in map)) map[vid] = rid
+    return map
+  }
+
+  async getRecordsByRecordIds(recordIds: string[], orgId: string): Promise<RecordDoc[]> {
+    if (recordIds.length === 0) return []
+    const rows = this.rows<{ id: string; data: string }>(
+      `SELECT id, data FROM nodes WHERE coll = 'records' AND id IN (${this.ph(recordIds.length)})
+         AND json_extract(data,'$.orgId') = ?`,
+      [...recordIds, orgId],
+    )
+    return rows.map((r) => ({ ...(JSON.parse(r.data) as RecordDoc), _key: r.id }))
+  }
+
+  async getUserByUserId(userId: string): Promise<UserDoc | null> {
+    return acl.userRow(this.sql, userId)
+  }
+
+  async getUserApps(userKey: string): Promise<Array<{ _key?: string; id?: string }>> {
+    return this.rows<{ id: string }>(
+      `SELECT n.id AS id FROM edges e JOIN nodes n ON n.id = e.dst AND n.coll = 'apps'
+       WHERE e.src = ? AND e.label = 'permissions'`,
+      [userKey],
+    ).map((r) => ({ _key: r.id, id: r.id }))
+  }
+
+  /** Record names (within the accessible set) that mention any of the given entities. */
+  recordsMentioning(entityIds: string[], accessibleRecordIds: string[]): string[] {
+    return kg.recordsMentioning(this.sql, entityIds, accessibleRecordIds)
+  }
+
+  async getDocument(recordId: string, collection: string): Promise<RecordDoc | null> {
+    const r = this.rows<{ id: string; data: string }>("SELECT id, data FROM nodes WHERE id = ? AND coll = ? LIMIT 1", [
+      recordId,
+      collection,
+    ])[0]
+    return r ? { ...(JSON.parse(r.data) as RecordDoc), _key: r.id } : null
+  }
+
+  /** GraphRAG hop: records connected to the seeds through shared/related concepts.
+   *  seed records → their entities → relates_to neighbors → other records that
+   *  mention those neighbors. Constrained to `accessibleRecordIds` (ACL-safe) and
+   *  excluding the seeds themselves. */
+  getRelatedRecordIds(seedRecordIds: string[], accessibleRecordIds: string[], limit = 5): string[] {
+    return kg.getRelatedRecordIds(this.sql, seedRecordIds, accessibleRecordIds, limit)
+  }
+
+  /** The knowledge graph the given (already ACL-filtered) records expose:
+   *  entities those records mention + relationships among them. ACL-safe because
+   *  the caller passes only recordIds the user may access. */
+  getKnowledgeGraph(recordIds: string[]): {
+    entities: Array<{ id: string; label: string; type: string }>
+    relations: Array<{ from: string; to: string; type: string; weight: number }>
+  } {
+    return kg.getKnowledgeGraph(this.sql, recordIds)
+  }
+}