@100xprompt/chitta 0.1.0

package/src/embedded/graph-query.ts

@@ -0,0 +1,126 @@
+// Graph-query layer - turns the entity graph into something you can QUERY as a
+// graph, not just semantically search. Ported from Graphify's serve.py query
+// ergonomics (neighbors / shortest_path / impact / central) but, unlike Graphify:
+//   • every traversal is ACL-FILTERED per caller (we only ever build the subgraph of
+//     entities mentioned by records the user may access), and
+//   • seeds are resolved against entity labels (and can be vector-seeded by the caller),
+//     not Graphify's lexical IDF scoring.
+// Pure in-memory traversal over the already-ACL-scoped {entities, relations} the
+// provider returns - instant at personal/enterprise note scale, and ACL-safe by
+// construction because the subgraph never contains an inaccessible entity.
+//
+// This file is the ORCHESTRATOR: scope() builds the ACL-scoped subgraph and each
+// public method delegates to a pure algorithm module under ./graph/.
+
+import { buildAdjacency, resolveIds } from "./graph/adjacency"
+import { centralEntities } from "./graph/centrality"
+import { detectCommunities } from "./graph/communities"
+import { toCypher as renderCypher } from "./graph/cypher"
+import { connectedEntities } from "./graph/impact"
+import { personalizedPageRank } from "./graph/pagerank"
+import { neighborsOf, shortestPath } from "./graph/traversal"
+import type { ScopedGraph } from "./graph/types"
+import type { SqliteGraphProvider } from "./sqlite-graph-provider"
+
+export interface NeighborResult {
+  entity: string
+  neighbors: Array<{ label: string; relation: string; direction: "out" | "in"; weight: number }>
+}
+export interface PathResult {
+  found: boolean
+  hops: number
+  steps: Array<{ from: string; relation: string; to: string }>
+}
+export interface ImpactResult {
+  entity: string
+  records: string[]
+  connectedEntities: Array<{ label: string; relation: string }>
+}
+
+export class GraphQueryService {
+  constructor(private readonly graph: SqliteGraphProvider) {}
+
+  // The ACL-scoped subgraph: entities + LIVE relations the user may see. Everything
+  // below traverses ONLY this, so no query can reach across a permission boundary.
+  private async scope(userId: string, orgId: string): Promise<ScopedGraph> {
+    const accessible = await this.graph.getAccessibleVirtualRecordIds({ userId, orgId })
+    const recordIds = [...new Set(Object.values(accessible))]
+    const { entities, relations } = this.graph.getKnowledgeGraph(recordIds)
+    const { byId, adj } = buildAdjacency(entities, relations)
+    return { entities, relations, byId, adj, recordIds }
+  }
+
+  /** Direct neighbors of an entity, optionally filtered by relation, heaviest first. */
+  async neighbors(name: string, userId: string, orgId: string, relation?: string): Promise<NeighborResult | null> {
+    const { entities, byId, adj } = await this.scope(userId, orgId)
+    const ids = resolveIds(name, entities)
+    if (ids.length === 0) return null
+    return neighborsOf(ids, byId, adj, relation)
+  }
+
+  /** Shortest relation chain between two entities (undirected BFS, hub-avoiding).
+   *  Answers "how are X and Y related?" - the single most useful graph query. */
+  async pathBetween(a: string, b: string, userId: string, orgId: string): Promise<PathResult> {
+    const { entities, byId, adj } = await this.scope(userId, orgId)
+    const startIds = resolveIds(a, entities)
+    const goalIds = new Set(resolveIds(b, entities))
+    return shortestPath(startIds, goalIds, byId, adj)
+  }
+
+  /** Impact / reverse-reference: which accessible records mention the entity, and
+   *  which entities it connects to. "What references / depends on X." */
+  async impactOf(name: string, userId: string, orgId: string): Promise<ImpactResult | null> {
+    const { entities, byId, adj, recordIds } = await this.scope(userId, orgId)
+    const ids = resolveIds(name, entities)
+    if (ids.length === 0) return null
+    const records = new Set<string>()
+    for (const name2 of this.graph.recordsMentioning(ids, recordIds)) records.add(name2)
+    const connected = connectedEntities(ids, byId, adj)
+    return { entity: byId.get(ids[0])?.label ?? ids[0], records: [...records], connectedEntities: connected }
+  }
+
+  /** Hub entities - highest total edge weight (most-connected concepts) in the
+   *  accessible graph. "What are the central things I know about." */
+  async central(userId: string, orgId: string, limit = 10): Promise<Array<{ label: string; degree: number; strength: number }>> {
+    const { byId, adj } = await this.scope(userId, orgId)
+    return centralEntities(byId, adj, limit)
+  }
+
+  /** Personalized PageRank multi-hop walk (HippoRAG-style). Seeds activation mass on
+   *  the query's entities and spreads it over the ACL-scoped, weighted typed graph;
+   *  a node reachable via MANY paths scores higher than a near dead-end. This is true
+   *  multi-hop relevance - strictly better than fixed-depth neighbor expansion - and
+   *  it's pure TS power-iteration (sub-ms at our scale). Returns ranked related
+   *  entities (seeds excluded). Edge weight (frequency≈confidence) steers the flow. */
+  async walk(
+    seedNames: string[],
+    userId: string,
+    orgId: string,
+    opts: { alpha?: number; iters?: number; limit?: number } = {},
+  ): Promise<Array<{ label: string; score: number; type: string }>> {
+    const alpha = opts.alpha ?? 0.85
+    const iters = opts.iters ?? 30
+    const limit = opts.limit ?? 15
+    const { entities, byId, adj } = await this.scope(userId, orgId)
+    if (entities.length === 0) return []
+    const seedIds = new Set<string>()
+    for (const name of seedNames) for (const id of resolveIds(name, entities)) seedIds.add(id)
+    if (seedIds.size === 0) return []
+    return personalizedPageRank(entities, byId, adj, seedIds, { alpha, iters, limit })
+  }
+
+  /** Communities - connected clusters of related entities (Graphify's god-node /
+   *  community view), via union-find over live edges. Each cluster's `hub` is its
+   *  most-connected member. ACL-scoped. */
+  async communities(userId: string, orgId: string, minSize = 2): Promise<Array<{ size: number; hub: string; members: string[] }>> {
+    const { entities, relations, byId, adj } = await this.scope(userId, orgId)
+    return detectCommunities(entities, relations, byId, adj, minSize)
+  }
+
+  /** Export the accessible graph as Cypher (Neo4j interop) - Graphify's to_cypher,
+   *  but ACL-filtered to exactly what this user may see. Uses MERGE so it's idempotent. */
+  async toCypher(userId: string, orgId: string): Promise<string> {
+    const { entities, relations, byId } = await this.scope(userId, orgId)
+    return renderCypher(entities, relations, byId)
+  }
+}

package/src/embedded/index.ts

@@ -0,0 +1,171 @@
+// Embedded context stack: one SQLite file, in-process embeddings, zero servers.
+// Wires the same RetrievalService (the moat) over embedded adapters - this is the
+// single-binary path. `bun build --compile` over a CLI that calls this yields one
+// self-contained executable.
+
+import { RetrievalService } from "../retrieval"
+import { SqliteStore } from "./sqlite-store"
+import { SqliteGraphProvider } from "./sqlite-graph-provider"
+import { SqliteVecService } from "./sqlite-vec-service"
+import { LocalHashEmbeddings } from "./local-embeddings"
+import { Ingestor, type IngestDoc } from "./ingest"
+import { DeterministicExtractor, type KnowledgeExtractor } from "./extract"
+import { Authorizer } from "./authorizer"
+import { KgqaService } from "./kgqa-service"
+import { GraphQueryService } from "./graph-query"
+import type { Reranker } from "./reranker"
+import type { LlmExtractor } from "./llm-extractor"
+import type { EmbeddingProvider } from "../provider"
+import type { RetrievalResponse } from "../types"
+import { hybridSearch } from "./retrieval/hybrid-retriever"
+import type { SearchTrace } from "./retrieval/trace"
+
+export { SqliteStore } from "./sqlite-store"
+export { SqliteGraphProvider } from "./sqlite-graph-provider"
+export { SqliteVecService } from "./sqlite-vec-service"
+export { LocalHashEmbeddings } from "./local-embeddings"
+export { TransformersEmbeddings } from "./transformers-embeddings"
+export { Ingestor, chunkText, type IngestDoc } from "./ingest"
+export { DeterministicExtractor, type KnowledgeExtractor } from "./extract"
+export { LlmExtractor, HybridExtractor } from "./llm-extractor"
+export { Authorizer, AuthorizationError, type Role } from "./authorizer"
+
+export interface EmbeddedOptions {
+  path?: string
+  collectionName?: string
+  embeddings?: EmbeddingProvider
+  extractor?: KnowledgeExtractor
+  llm?: LlmExtractor // enables LLM-based KGQA intent parsing
+  reranker?: Reranker // optional cross-encoder final stage (highest-precision reorder)
+  log?: { info: (m: string) => void; debug: (m: string) => void; error: (m: string) => void }
+}
+
+// Retrieval trace - how a query flowed through the pipeline, for the UI's "how it
+// retrieved" panel. Defined in retrieval/trace.ts; re-exported here as part of the
+// public API.
+export type { SearchTrace } from "./retrieval/trace"
+
+export function buildEmbeddedContext(opts: EmbeddedOptions = {}) {
+  const store = new SqliteStore(opts.path ?? ":memory:")
+  const graph = new SqliteGraphProvider(store)
+  const vector = new SqliteVecService(store)
+  const embeddings = opts.embeddings ?? new LocalHashEmbeddings()
+  const extractor = opts.extractor ?? new DeterministicExtractor()
+  const retrieval = new RetrievalService({
+    graph,
+    vector,
+    embeddings,
+    collectionName: opts.collectionName ?? "records",
+    log: opts.log,
+  })
+  const ingestor = new Ingestor(store, embeddings, extractor)
+  const authorizer = new Authorizer(store)
+  const kgqa = new KgqaService(graph, store, embeddings, opts.llm)
+  const graphQuery = new GraphQueryService(graph)
+  const reranker = opts.reranker // optional cross-encoder final stage
+
+  // Exact-answer first: try to answer the question precisely from the typed graph;
+  // returns null when it can't (caller then falls back to ranked retrieval).
+  async function ask(question: string, userId: string, orgId: string) {
+    return kgqa.answer(question, userId, orgId)
+  }
+
+  // Authorized write path: checks the acting user MAY create + may grant the
+  // requested sharing, stamps ownership, then ingests. Throws AuthorizationError.
+  async function authorizedIngest(actingUserId: string, doc: IngestDoc) {
+    authorizer.assertCanCreate(actingUserId, doc.orgId, doc.permittedPrincipals ?? [], doc.shareWithOrg)
+    const principals = [...new Set([...(doc.permittedPrincipals ?? []), actingUserId])] // owner can always read
+    return ingestor.ingest({ ...doc, ownerId: actingUserId, permittedPrincipals: principals })
+  }
+
+  // Authorized delete: only the owner or an admin may remove a record (+ its
+  // edges, chunks, and ANN rows).
+  function deleteRecord(actingUserId: string, recordId: string): void {
+    authorizer.assertCanModify(actingUserId, recordId)
+    const vids = store.db.query("SELECT json_extract(data,'$.virtualRecordId') v FROM nodes WHERE id = ?").all(recordId) as Array<{ v: string }>
+    store.db.query("DELETE FROM nodes WHERE id = ?").run(recordId)
+    store.db.query("DELETE FROM edges WHERE src = ? OR dst = ?").run(recordId, recordId)
+    store.db.query("DELETE FROM chunks WHERE point_id LIKE ?").run(`${recordId}#%`)
+    for (const { v } of vids) if (v) store.db.query("DELETE FROM chunks WHERE virtual_record_id = ?").run(v)
+  }
+
+  // HYBRID retrieval - 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).
+  // The pipeline lives in ./retrieval/* - this is a thin wrapper that threads the
+  // shared embedded state into the orchestrator.
+  async function searchWithGraph(query: string, userId: string, orgId: string, trace?: SearchTrace): Promise<RetrievalResponse> {
+    return hybridSearch({ retrieval, store, graph, embeddings, reranker }, query, userId, orgId, trace)
+  }
+
+  // Same retrieval, but also returns the pipeline TRACE (for the UI's explainability).
+  async function searchTraced(query: string, userId: string, orgId: string) {
+    const trace: SearchTrace = { counts: { vector: 0, keyword: 0, graph: 0, fused: 0 }, reranked: false, items: [] }
+    const response = await searchWithGraph(query, userId, orgId, trace)
+    return { response, trace }
+  }
+
+  // Re-embed every stored chunk with the current embedder and rebuild the ANN
+  // index. Needed when switching embedders (e.g. hash → transformers, different dim).
+  async function reindex(): Promise<number> {
+    store.resetVec()
+    store.resetFts()
+    const rows = store.db.query("SELECT point_id, virtual_record_id, org_id, content FROM chunks").all() as Array<{
+      point_id: string
+      virtual_record_id: string
+      org_id: string
+      content: string
+    }>
+    for (const r of rows) {
+      const emb = await embeddings.embedDense(r.content)
+      store.addChunk(r.point_id, r.virtual_record_id, r.org_id, r.content, emb)
+    }
+    return rows.length
+  }
+
+  // Re-extract the knowledge graph for EVERY existing record (e.g. after switching
+  // to an LLM extractor, or for data ingested before extraction existed). Clears
+  // the concept layer (entities + mentions + relates_to), keeps records/ACL/vectors.
+  async function rebuildGraph(): Promise<{ records: number; entities: number }> {
+    store.db.exec("DELETE FROM nodes WHERE coll = 'entities'")
+    store.db.exec("DELETE FROM edges WHERE label IN ('mentions','relates_to')")
+    const records = store.db.query("SELECT id, data FROM nodes WHERE coll = 'records'").all() as Array<{ id: string; data: string }>
+    let entities = 0
+    for (const rec of records) {
+      const chunks = store.db
+        .query("SELECT content FROM chunks WHERE point_id LIKE ? ORDER BY rowid")
+        .all(`${rec.id}#%`) as Array<{ content: string }>
+      const text = chunks.map((c) => c.content).join("\n\n")
+      const name = (JSON.parse(rec.data) as { recordName?: string }).recordName
+      if (text) entities += await ingestor.writeGraphFor(rec.id, text, name)
+    }
+    return { records: records.length, entities }
+  }
+
+  return {
+    store,
+    graph,
+    vector,
+    embeddings,
+    retrieval,
+    ingestor,
+    authorizer,
+    kgqa,
+    graphQuery,
+    ask,
+    authorizedIngest,
+    deleteRecord,
+    searchWithGraph,
+    searchTraced,
+    reindex,
+    rebuildGraph,
+  }
+}
+
+export type EmbeddedContext = ReturnType<typeof buildEmbeddedContext>

package/src/embedded/ingest.ts

@@ -0,0 +1,262 @@
+// Ingestion - the WRITE side that CREATES the graph + vectors from real input.
+// Phase 1 of the lifecycle: parse → chunk → embed → write record node + permission
+// edges + chunk vectors. After this runs, retrieval (Phase 2) can resolve the doc.
+
+import type { EmbeddingProvider } from "../provider"
+import type { SqliteStore, Json } from "./sqlite-store"
+import { DeterministicExtractor, stripBoilerplate, slugify, entityId, type KnowledgeExtractor } from "./extract"
+import { CodeExtractor } from "./code-extractor"
+
+export interface IngestDoc {
+  recordId: string
+  text: string
+  orgId: string
+  recordName: string
+  virtualRecordId?: string
+  mimeType?: string
+  connectorId?: string
+  origin?: "CONNECTOR" | "UPLOAD"
+  /** Principal ids (users/groups) that may see this doc → permission edges. */
+  permittedPrincipals?: string[]
+  /** If set, the doc is visible to anyone in this org (the "anyone" path). */
+  shareWithOrg?: string
+  /** Extract a knowledge graph (entities + relations) at ingest. Default true. */
+  extractGraph?: boolean
+  /** The creator/owner of the record (set by the authorized write path). */
+  ownerId?: string
+  /** Pre-extracted TYPED graph supplied by the CALLING model (the frontier LLM that
+   *  already understood the content). When present, it is stored directly INSTEAD of
+   *  running the built-in extractor - so the graph is precise typed triples with NO
+   *  separate LLM endpoint needed. */
+  entities?: Array<{ name: string; type?: string }>
+  relations?: Array<{ from: string; to: string; type: string; confidence?: number }>
+}
+
+/** Structure-aware chunker. The old greedy-merge packed many DISTINCT facts into one
+ *  chunk → "embedding dilution": a 20-headline chunk has a muddy average vector that
+ *  matches no specific query (the Reuters-news failure). Research (2026): recursive
+ *  ~512-token chunks are the best general default; FACT-LIST documents (news
+ *  headlines, bullet lists) want per-FACT granularity, while flowing prose wants
+ *  sentences grouped up to the target. So:
+ *   • list-like block (≥4 newline lines, short median) → one chunk PER LINE (no
+ *     cross-fact merging) - kills dilution for dense news pages.
+ *   • prose block → split into sentences, pack up to `size`.
+ *   • a short heading (no terminal punctuation) carries forward and attaches to the
+ *     next chunk's content (so "PRICING TIERS:" isn't a useless standalone).
+ *  Oversized units are hard-split. No overlap (2026 benchmarks: no measurable gain). */
+export function chunkText(text: string, size = 512, minChunk = 80): string[] {
+  const blocks = text.split(/\n\s*\n/).map((b) => b.trim()).filter(Boolean)
+  const out: string[] = []
+  let carry = "" // a short heading held to prepend to the following content
+  const median = (ns: number[]): number => {
+    if (!ns.length) return 0
+    const s = [...ns].sort((a, b) => a - b)
+    return s[s.length >> 1]
+  }
+  const flush = (s: string) => {
+    let t = (carry ? `${carry} ` : "") + s.trim()
+    carry = ""
+    while (t.length > size) {
+      out.push(t.slice(0, size).trim())
+      t = t.slice(size)
+    }
+    if (t.trim()) out.push(t.trim())
+  }
+  for (const b of blocks) {
+    const lines = b.split("\n").map((l) => l.trim()).filter(Boolean)
+    const listLike = lines.length >= 4 && median(lines.map((l) => l.length)) < 120
+    if (listLike) {
+      for (const l of lines) {
+        if (l.length < 30 && !/[.!?]$/.test(l)) carry = (carry ? `${carry} ` : "") + l // tiny fragment → heading
+        else flush(l) // each list item / headline becomes its own focused chunk
+      }
+    } else if (b.length < minChunk && !/[.!?]$/.test(b)) {
+      carry = (carry ? `${carry} ` : "") + b // short heading → attach to next block
+    } else {
+      const sents = b.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean)
+      let cur = ""
+      for (const s of sents) {
+        if (cur && cur.length + s.length + 1 > size) {
+          flush(cur)
+          cur = s
+        } else cur = cur ? `${cur} ${s}` : s
+      }
+      if (cur) flush(cur)
+    }
+  }
+  if (carry) out.push(carry)
+  return out.length ? out : [text.trim()].filter(Boolean)
+}
+
+// FUNCTIONAL (single-valued) relations: a subject has at most ONE current value, so
+// a newer fact SUPERSEDES the old (user moved cities; company changed CEO). Anything
+// not here is multi-valued (partners_with, mentions, knows…) and simply accumulates.
+// Only the typed/LLM path emits these predicates; the deterministic path uses
+// "relates_to" (symmetric, never functional), so supersession is a no-op there.
+const FUNCTIONAL_PREDICATES = new Set([
+  "lives_in", "located_in", "based_in", "works_at", "employed_by", "ceo_of", "led_by",
+  "born_in", "current_role", "role_is", "status_is", "owns", "owned_by", "married_to",
+  "reports_to", "headquartered_in", "capital_of", "member_of",
+])
+
+// Entity ids are namespaced (`entity:`) so a slug of free text can never collide with a
+// principal (user/org/group) or record id and corrupt the ACL graph via INSERT OR
+// REPLACE. The scheme + `entityId()` helper are defined once in extractors/text-hygiene
+// (imported above) so every writer here and every resolver (kgqa/entity-link,
+// graph/adjacency) agree on it.
+
+export class Ingestor {
+  // Code files (detected by extension) are parsed with tree-sitter into a code graph;
+  // everything else goes through the configured text/LLM extractor.
+  private readonly codeExtractor = new CodeExtractor()
+  constructor(
+    private readonly store: SqliteStore,
+    private readonly embeddings: EmbeddingProvider,
+    private readonly extractor: KnowledgeExtractor = new DeterministicExtractor(),
+  ) {}
+
+  // --- identity surface (normally fed by an IdP/SCIM sync) ---
+  registerOrg(orgId: string, data: Json = {}): void {
+    this.store.addNode(orgId, "organizations", data)
+  }
+  registerUser(userId: string, orgId: string, email?: string, role: "admin" | "editor" | "viewer" = "editor"): void {
+    this.store.addNode(userId, "users", { userId, email, role })
+    this.store.addNode(orgId, "organizations", {}) // idempotent (INSERT OR REPLACE)
+    this.store.addEdge(userId, orgId, "belongsTo")
+  }
+  registerGroup(groupId: string): void {
+    this.store.addNode(groupId, "groups", {})
+  }
+  addMembership(userId: string, groupId: string): void {
+    this.store.addEdge(userId, groupId, "belongsTo")
+  }
+
+  // --- the document ingestion pipeline ---
+  async ingest(doc: IngestDoc): Promise<{ recordId: string; chunks: number; entities: number }> {
+    const vid = doc.virtualRecordId ?? doc.recordId
+
+    // (1) GRAPH: the record node.
+    this.store.addNode(doc.recordId, "records", {
+      virtualRecordId: vid,
+      orgId: doc.orgId,
+      recordName: doc.recordName,
+      mimeType: doc.mimeType ?? "text/plain",
+      connectorId: doc.connectorId ?? "upload",
+      connectorName: doc.connectorId ?? "upload",
+      origin: doc.origin ?? "UPLOAD",
+      indexingStatus: "COMPLETED",
+      ownerId: doc.ownerId, // creator - used for write/delete authorization
+      createdAt: Date.now(), // memory recency baseline (decay/salience re-ranking)
+    })
+
+    // (2) GRAPH: permission edges (the ACL) - captured from the source at ingest.
+    for (const principal of doc.permittedPrincipals ?? []) {
+      this.store.addEdge(principal, doc.recordId, "permissions")
+    }
+    if (doc.shareWithOrg) {
+      this.store.addNode(`anyone:${doc.recordId}`, "anyone", {
+        organization: doc.shareWithOrg,
+        file_key: doc.recordId,
+      })
+    }
+
+    // Drop web boilerplate (cookie banners, nav, subscribe CTAs) from PROSE before
+    // chunking/extraction so it never becomes a noisy chunk or junk entity. Code is
+    // left untouched (a line like "accept" can be real source).
+    const isCode = !!CodeExtractor.detectLanguage(doc.recordName)
+    const cleanText = isCode ? doc.text : stripBoilerplate(doc.text)
+
+    // (3) VECTORS: chunk → embed → store.
+    const chunks = chunkText(cleanText)
+    for (let i = 0; i < chunks.length; i++) {
+      const embedding = await this.embeddings.embedDense(chunks[i])
+      this.store.addChunk(`${doc.recordId}#${i}`, vid, doc.orgId, chunks[i], embedding)
+    }
+
+    // (4) KNOWLEDGE GRAPH: extract concepts → entity nodes + relationship edges.
+    // record --mentions--> entity, entity --relates_to--> entity. Entity ids are
+    // shared across docs, so two records that mention "Pro" link through it.
+    let entities = 0
+    if (doc.extractGraph !== false) {
+      // If the calling (frontier) model supplied a typed graph, store THAT - precise
+      // triples, no built-in extractor, no separate LLM. Otherwise fall back to the
+      // text/code extractor.
+      entities =
+        doc.entities?.length || doc.relations?.length
+          ? this.writeProvidedGraph(doc.recordId, doc.entities ?? [], doc.relations ?? [])
+          : await this.writeGraphFor(doc.recordId, cleanText, doc.recordName)
+    }
+
+    return { recordId: doc.recordId, chunks: chunks.length, entities }
+  }
+
+  /** Store a TYPED graph supplied by the calling model (the frontier LLM that read
+   *  the content). This is the precise path - no built-in extractor, no separate LLM.
+   *  Normalizes relation predicates, stamps confidence + provenance, and applies
+   *  bi-temporal supersession for single-valued (functional) relations. Returns the
+   *  number of entities written. */
+  writeProvidedGraph(
+    recordId: string,
+    ents: Array<{ name: string; type?: string }>,
+    rels: Array<{ from: string; to: string; type: string; confidence?: number }>,
+  ): number {
+    this.store.clearRecordContributions(recordId)
+    const added = new Set<string>()
+    const addEntity = (name: string, type?: string) => {
+      const slug = slugify(name)
+      if (!slug || added.has(slug)) return slug && entityId(slug)
+      added.add(slug)
+      const id = entityId(slug)
+      this.store.addNode(id, "entities", { label: name.trim(), type: type ?? "ENTITY" })
+      this.store.addEdge(recordId, id, "mentions", { recordId })
+      return id
+    }
+    for (const e of ents) addEntity(e.name, e.type)
+    const now = Date.now()
+    for (const r of rels) {
+      const from = addEntity(r.from) // ensure endpoint nodes exist + are mentioned
+      const to = addEntity(r.to)
+      if (!from || !to || from === to) continue
+      const label = (r.type || "relates_to").trim().toLowerCase().replace(/\s+/g, "_")
+      this.store.addEdge(from, to, label, { recordId, validAt: now, confidence: r.confidence })
+      if (FUNCTIONAL_PREDICATES.has(label)) this.store.supersedeEdge(from, label, to, now)
+    }
+    return added.size
+  }
+
+  /** Extract concepts from text (or CODE) and attach them to a record (shared by
+   *  ingest and rebuildGraph). Code files (detected from `name`) are parsed with
+   *  tree-sitter; everything else uses the configured text/LLM extractor. Returns
+   *  the number of entities written. */
+  async writeGraphFor(recordId: string, text: string, name?: string): Promise<number> {
+    // Source-keyed replace (Graphify): if this record was ingested before, drop its
+    // prior graph contributions first so facts it no longer asserts are GC'd, weights
+    // stay accurate, and re-ingest is idempotent rather than weight-inflating.
+    this.store.clearRecordContributions(recordId)
+
+    // Route: code → tree-sitter AST graph; prose → text/LLM extractor.
+    const lang = CodeExtractor.detectLanguage(name)
+    const extractor = lang ? this.codeExtractor : this.extractor
+    const { entities, relations } = await extractor.extract(text, { name, language: lang ?? undefined })
+    for (const e of entities) {
+      const id = entityId(e.id)
+      this.store.addNode(id, "entities", { label: e.label, type: e.type })
+      this.store.addEdge(recordId, id, "mentions", { recordId })
+    }
+    // Store the TYPED predicate as the edge label (calls/defines/imports for code;
+    // loves/is_a/… for prose). weight ACCUMULATES across re-mentions (frequency≈
+    // confidence); per-edge `confidence` is the EXTRACTED/INFERRED tier; the source
+    // record is recorded as provenance so we can trace and supersede a fact later.
+    const now = Date.now()
+    for (const r of relations) {
+      const label = r.type || "relates_to"
+      const from = entityId(r.from)
+      const to = entityId(r.to)
+      this.store.addEdge(from, to, label, { recordId, validAt: now, confidence: r.confidence })
+      // Bi-temporal supersession (Graphiti): for a single-valued relation, a newer
+      // value closes the prior one - non-destructively (history kept, marked expired).
+      if (FUNCTIONAL_PREDICATES.has(label)) this.store.supersedeEdge(from, label, to, now)
+    }
+    return entities.length
+  }
+}