@100xprompt/chitta 0.1.0

package/src/embedded/graph/acl-paths.ts

@@ -0,0 +1,96 @@
+// ACL permission paths - the Arango-AQL traversal ported to SQL over the generic
+// node/edge tables. These eight-path-collapsed-to-five helpers are the access
+// moat; the provider unions their results and dedupes first-writer-wins.
+//
+//   • 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.
+// Same invariant as the Arango port; only the query language differs.
+
+import type { UserDoc } from "../../types"
+import { COMPLETED, type Pair, type SqlAccess } from "./sql-access"
+
+export function userRow(sql: SqlAccess, userId: string): (UserDoc & { id: string }) | null {
+  const r = sql.rows<{ id: string; data: string }>(
+    "SELECT id, data FROM nodes WHERE coll = 'users' AND json_extract(data, '$.userId') = ? LIMIT 1",
+    [userId],
+  )[0]
+  if (!r) return null
+  return { ...(JSON.parse(r.data) as UserDoc), id: r.id, _key: r.id }
+}
+
+export function principalIds(sql: SqlAccess, userId: string): string[] {
+  const belongs = sql.rows<{ dst: string }>("SELECT dst FROM edges WHERE src = ? AND label = 'belongsTo'", [userId])
+  const permPrincipals = sql.rows<{ dst: string }>(
+    `SELECT e.dst AS dst FROM edges e JOIN nodes n ON n.id = e.dst
+       WHERE e.src = ? AND e.label = 'permissions'
+         AND n.coll IN ('groups','roles','organizations','teams')`,
+    [userId],
+  )
+  return [...new Set([userId, ...belongs.map((r) => r.dst), ...permPrincipals.map((r) => r.dst)])]
+}
+
+export function recordsPermissionedTo(sql: SqlAccess, principals: string[], apps?: string[]): Pair[] {
+  if (principals.length === 0) return []
+  const appClause = apps?.length ? ` AND json_extract(r.data,'$.connectorId') IN (${sql.ph(apps.length)})` : ""
+  return sql.rows<Pair>(
+    `SELECT r.id AS rid, json_extract(r.data,'$.virtualRecordId') AS vid
+       FROM edges e JOIN nodes r ON r.id = e.dst AND r.coll = 'records'
+       WHERE e.label = 'permissions' AND e.src IN (${sql.ph(principals.length)})
+         AND json_extract(r.data,'$.indexingStatus') = ?${appClause}`,
+    [...principals, COMPLETED, ...(apps ?? [])],
+  )
+}
+
+export function recordGroupsPermissionedTo(sql: SqlAccess, principals: string[], kb?: string[]): string[] {
+  if (principals.length === 0) return []
+  const kbClause = kb?.length ? ` AND n.id IN (${sql.ph(kb.length)})` : ""
+  return sql
+    .rows<{ id: string }>(
+      `SELECT DISTINCT n.id AS id FROM edges e JOIN nodes n ON n.id = e.dst AND n.coll = 'recordGroups'
+       WHERE e.label = 'permissions' AND e.src IN (${sql.ph(principals.length)})${kbClause}`,
+      [...principals, ...(kb ?? [])],
+    )
+    .map((r) => r.id)
+}
+
+export function recordsInheritingFrom(sql: SqlAccess, recordGroups: string[]): Pair[] {
+  if (recordGroups.length === 0) return []
+  return sql.rows<Pair>(
+    `WITH RECURSIVE descend(id) AS (
+         SELECT src FROM edges WHERE label = 'inheritPermissions' AND dst IN (${sql.ph(recordGroups.length)})
+         UNION
+         SELECT e.src FROM edges e JOIN descend d ON e.dst = d.id WHERE e.label = 'inheritPermissions'
+       )
+       SELECT r.id AS rid, json_extract(r.data,'$.virtualRecordId') AS vid
+       FROM nodes r JOIN descend ON r.id = descend.id
+       WHERE r.coll = 'records' AND json_extract(r.data,'$.indexingStatus') = ?`,
+    [...recordGroups, COMPLETED],
+  )
+}
+
+export function kbRecords(sql: SqlAccess, recordGroups: string[]): Pair[] {
+  if (recordGroups.length === 0) return []
+  return sql.rows<Pair>(
+    `SELECT r.id AS rid, json_extract(r.data,'$.virtualRecordId') AS vid
+       FROM edges e JOIN nodes r ON r.id = e.src AND r.coll = 'records'
+       WHERE e.label = 'belongsTo' AND e.dst IN (${sql.ph(recordGroups.length)})
+         AND json_extract(r.data,'$.origin') = 'UPLOAD'
+         AND json_extract(r.data,'$.indexingStatus') = ?`,
+    [...recordGroups, COMPLETED],
+  )
+}
+
+export function anyoneRecords(sql: SqlAccess, orgId: string): Pair[] {
+  return sql.rows<Pair>(
+    `SELECT r.id AS rid, json_extract(r.data,'$.virtualRecordId') AS vid
+       FROM nodes a JOIN nodes r ON r.id = json_extract(a.data,'$.file_key') AND r.coll = 'records'
+       WHERE a.coll = 'anyone' AND json_extract(a.data,'$.organization') = ?
+         AND json_extract(r.data,'$.indexingStatus') = ?`,
+    [orgId, COMPLETED],
+  )
+}

package/src/embedded/graph/adjacency.ts

@@ -0,0 +1,61 @@
+// Adjacency / scope helpers - build the ACL-scoped subgraph and the small
+// resolution utilities (free-text → entity ids, label lookup, hub threshold)
+// that every traversal shares. Pure over the provider-returned {entities,
+// relations}; the ACL filtering itself happens upstream in the provider.
+
+import { slugify, entityId } from "../extract"
+import type { Adj, Entity, Relation } from "./types"
+
+/** Build id→entity map and the typed-first adjacency list from live relations.
+ *  Edges whose endpoints aren't both present are dropped. Each adjacency list is
+ *  ordered TYPED-first (generic "relates_to" last), then by descending weight, so
+ *  neighbors lead with real relationships and BFS reconstructs precise predicates. */
+export function buildAdjacency(
+  entities: Entity[],
+  relations: Relation[],
+): { byId: Map<string, Entity>; adj: Map<string, Adj[]> } {
+  const byId = new Map(entities.map((e) => [e.id, e]))
+  const adj = new Map<string, Adj[]>()
+  const push = (a: string, edge: Adj) => {
+    const list = adj.get(a) ?? []
+    list.push(edge)
+    adj.set(a, list)
+  }
+  for (const r of relations) {
+    if (!byId.has(r.from) || !byId.has(r.to)) continue
+    push(r.from, { to: r.to, type: r.type, weight: r.weight, dir: "out" })
+    push(r.to, { to: r.from, type: r.type, weight: r.weight, dir: "in" })
+  }
+  // Prefer TYPED edges over generic co-occurrence ("relates_to"): order each
+  // adjacency list typed-first so neighbors lead with real relationships and BFS
+  // paths are reconstructed through the precise predicate, not "relates_to".
+  const generic = (t: string) => (t === "relates_to" ? 1 : 0)
+  for (const list of adj.values()) list.sort((a, b) => generic(a.type) - generic(b.type) || b.weight - a.weight)
+  return { byId, adj }
+}
+
+/** Resolve a free-text name to entity id(s) within the accessible set: exact id /
+ *  exact label first, then substring/slug containment. Returns [] if unknown. */
+export function resolveIds(name: string, entities: Entity[]): string[] {
+  const q = name.trim().toLowerCase()
+  if (!q) return []
+  const slug = slugify(name)
+  const id = entityId(slug)
+  const exact = entities.filter((e) => e.id === id || e.label.toLowerCase() === q)
+  if (exact.length) return [...new Set(exact.map((e) => e.id))]
+  const partial = entities.filter((e) => e.label.toLowerCase().includes(q) || (slug.length >= 3 && e.id.includes(slug)))
+  return [...new Set(partial.map((e) => e.id))]
+}
+
+export function labelOf(id: string, byId: Map<string, Entity>): string {
+  return byId.get(id)?.label ?? id
+}
+
+/** hub threshold (Graphify _bfs): refuse to EXPAND through a super-connected node so
+ *  one mega-entity can't blow up traversal / context. max(50, p99 degree). */
+export function hubThreshold(adj: Map<string, Adj[]>): number {
+  const degrees = [...adj.values()].map((l) => l.length).sort((a, b) => a - b)
+  if (degrees.length === 0) return 50
+  const p99 = degrees[Math.min(degrees.length - 1, Math.floor(degrees.length * 0.99))]
+  return Math.max(50, p99)
+}

package/src/embedded/graph/centrality.ts

@@ -0,0 +1,23 @@
+// Centrality - hub entities ranked by total edge weight (then degree). Pure over
+// the scoped adjacency. "What are the central things I know about."
+
+import { labelOf } from "./adjacency"
+import type { Adj, Entity } from "./types"
+
+/** Most-connected concepts in the accessible graph, heaviest total weight first. */
+export function centralEntities(
+  byId: Map<string, Entity>,
+  adj: Map<string, Adj[]>,
+  limit = 10,
+): Array<{ label: string; degree: number; strength: number }> {
+  const out: Array<{ label: string; degree: number; strength: number }> = []
+  for (const [id, edges] of adj) {
+    out.push({
+      label: labelOf(id, byId),
+      degree: edges.length,
+      strength: edges.reduce((s, e) => s + e.weight, 0),
+    })
+  }
+  out.sort((a, b) => b.strength - a.strength || b.degree - a.degree)
+  return out.slice(0, limit)
+}

package/src/embedded/graph/communities.ts

@@ -0,0 +1,46 @@
+// 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. Pure over the scoped subgraph (ACL-scoped upstream).
+
+import { labelOf } from "./adjacency"
+import type { Adj, Entity, Relation } from "./types"
+
+export function detectCommunities(
+  entities: Entity[],
+  relations: Relation[],
+  byId: Map<string, Entity>,
+  adj: Map<string, Adj[]>,
+  minSize = 2,
+): Array<{ size: number; hub: string; members: string[] }> {
+  const parent = new Map<string, string>()
+  const find = (x: string): string => {
+    let r = x
+    while (parent.get(r) !== r) r = parent.get(r) as string
+    while (parent.get(x) !== r) {
+      const n = parent.get(x) as string
+      parent.set(x, r)
+      x = n
+    }
+    return r
+  }
+  for (const e of entities) parent.set(e.id, e.id)
+  for (const r of relations) {
+    if (!parent.has(r.from) || !parent.has(r.to)) continue
+    parent.set(find(r.from), find(r.to))
+  }
+  const groups = new Map<string, string[]>()
+  for (const e of entities) {
+    const root = find(e.id)
+    const g = groups.get(root) ?? []
+    g.push(e.id)
+    groups.set(root, g)
+  }
+  const out: Array<{ size: number; hub: string; members: string[] }> = []
+  for (const ids of groups.values()) {
+    if (ids.length < minSize) continue
+    const hub = ids.reduce((best, id) => ((adj.get(id)?.length ?? 0) > (adj.get(best)?.length ?? 0) ? id : best), ids[0])
+    out.push({ size: ids.length, hub: labelOf(hub, byId), members: ids.map((id) => labelOf(id, byId)) })
+  }
+  out.sort((a, b) => b.size - a.size)
+  return out
+}

package/src/embedded/graph/cypher.ts

@@ -0,0 +1,17 @@
+// Cypher export (Graphify's to_cypher) - render the already ACL-filtered subgraph
+// as idempotent MERGE statements for Neo4j interop. Pure; ACL filtering happens
+// upstream so this only ever sees what the user may access.
+
+import type { Entity, Relation } from "./types"
+
+export function toCypher(entities: Entity[], relations: Relation[], byId: Map<string, Entity>): string {
+  const esc = (s: string) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")
+  const lines: string[] = []
+  for (const e of entities) lines.push(`MERGE (n:${e.type.replace(/[^A-Za-z0-9_]/g, "_") || "Entity"} {id:'${esc(e.id)}', label:'${esc(e.label)}'});`)
+  for (const r of relations) {
+    if (!byId.has(r.from) || !byId.has(r.to)) continue
+    const rel = (r.type || "RELATES_TO").toUpperCase().replace(/[^A-Z0-9_]/g, "_")
+    lines.push(`MATCH (a {id:'${esc(r.from)}'}),(b {id:'${esc(r.to)}'}) MERGE (a)-[:${rel} {weight:${r.weight}}]->(b);`)
+  }
+  return lines.join("\n")
+}

package/src/embedded/graph/impact.ts

@@ -0,0 +1,24 @@
+// Impact / reverse-reference - given resolved entity ids, the directly connected
+// entities. The "which records mention it" half lives in the provider
+// (recordsMentioning); the orchestrator joins the two. Pure over the scoped adj.
+
+import type { ImpactResult } from "../graph-query"
+import { labelOf } from "./adjacency"
+import type { Adj, Entity } from "./types"
+
+/** The distinct entities the given ids connect to (first edge wins per neighbor). */
+export function connectedEntities(
+  ids: string[],
+  byId: Map<string, Entity>,
+  adj: Map<string, Adj[]>,
+): ImpactResult["connectedEntities"] {
+  const connected: ImpactResult["connectedEntities"] = []
+  const seen = new Set<string>()
+  for (const id of ids)
+    for (const e of adj.get(id) ?? []) {
+      if (seen.has(e.to)) continue
+      seen.add(e.to)
+      connected.push({ label: labelOf(e.to, byId), relation: e.type })
+    }
+  return connected
+}

package/src/embedded/graph/knowledge-graph.ts

@@ -0,0 +1,108 @@
+// Knowledge-graph assembly + GraphRAG expansion over the ACL-filtered record set.
+//
+// SECURITY INVARIANT (provenance leak-guard): in `getKnowledgeGraph`, a relation
+// surfaces ONLY if a record the user may access ASSERTED it (provenance ∩
+// accessible ≠ ∅). Endpoint visibility is NOT enough - two visible entities can
+// still have a relationship stated only in a record the user can't see. Fail
+// closed: no provenance match ⇒ hidden. Preserve this exactly.
+
+import type { SqlAccess } from "./sql-access"
+
+/** Record names (within the accessible set) that mention any of the given entities. */
+export function recordsMentioning(sql: SqlAccess, entityIds: string[], accessibleRecordIds: string[]): string[] {
+  if (entityIds.length === 0 || accessibleRecordIds.length === 0) return []
+  const rows = sql.rows<{ data: string }>(
+    `SELECT DISTINCT n.data AS data
+       FROM edges m JOIN nodes n ON n.id = m.src AND n.coll = 'records'
+       WHERE m.label = 'mentions' AND m.dst IN (${sql.ph(entityIds.length)}) AND m.src IN (${sql.ph(accessibleRecordIds.length)})`,
+    [...entityIds, ...accessibleRecordIds],
+  )
+  return rows.map((r) => (JSON.parse(r.data) as { recordName?: string }).recordName ?? "").filter(Boolean)
+}
+
+/** 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. */
+export function getRelatedRecordIds(
+  sql: SqlAccess,
+  seedRecordIds: string[],
+  accessibleRecordIds: string[],
+  limit = 5,
+): string[] {
+  if (seedRecordIds.length === 0 || accessibleRecordIds.length === 0) return []
+  const seedEnts = sql
+    .rows<{ dst: string }>(
+      `SELECT DISTINCT dst FROM edges WHERE label = 'mentions' AND src IN (${sql.ph(seedRecordIds.length)})`,
+      seedRecordIds,
+    )
+    .map((r) => r.dst)
+  if (seedEnts.length === 0) return []
+  const ep = sql.ph(seedEnts.length)
+  const neighbors = new Set<string>(seedEnts)
+  // Follow entity→entity relation edges of ANY predicate (exclude structural
+  // labels), LIVE edges only - superseded facts don't drive current expansion.
+  for (const r of sql.rows<{ e: string }>(
+    `SELECT dst AS e FROM edges WHERE label NOT IN ('mentions','permissions','belongsTo','inheritPermissions') AND expired_at IS NULL AND src IN (${ep})
+       UNION SELECT src AS e FROM edges WHERE label NOT IN ('mentions','permissions','belongsTo','inheritPermissions') AND expired_at IS NULL AND dst IN (${ep})`,
+    [...seedEnts, ...seedEnts],
+  ))
+    neighbors.add(r.e)
+
+  const nb = [...neighbors]
+  const seeds = new Set(seedRecordIds)
+  const acc = new Set(accessibleRecordIds)
+  const related = sql
+    .rows<{ src: string }>(
+      `SELECT src, COUNT(*) c FROM edges
+       WHERE label = 'mentions' AND dst IN (${sql.ph(nb.length)})
+       GROUP BY src ORDER BY c DESC`,
+      nb,
+    )
+    .map((r) => r.src)
+    .filter((id) => acc.has(id) && !seeds.has(id))
+  return related.slice(0, 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. */
+export function getKnowledgeGraph(
+  sql: SqlAccess,
+  recordIds: string[],
+): {
+  entities: Array<{ id: string; label: string; type: string }>
+  relations: Array<{ from: string; to: string; type: string; weight: number }>
+} {
+  if (recordIds.length === 0) return { entities: [], relations: [] }
+  const ph = sql.ph(recordIds.length)
+  const ents = sql
+    .rows<{ id: string; data: string }>(
+      `SELECT DISTINCT e.id AS id, e.data AS data
+       FROM edges m JOIN nodes e ON e.id = m.dst AND e.coll = 'entities'
+       WHERE m.label = 'mentions' AND m.src IN (${ph})`,
+      recordIds,
+    )
+    .map((r) => {
+      const d = JSON.parse(r.data) as { label?: string; type?: string }
+      return { id: r.id, label: d.label ?? r.id, type: d.type ?? "CONCEPT" }
+    })
+  const ids = new Set(ents.map((e) => e.id))
+  const accessible = new Set(recordIds)
+  // Typed relations: entity→entity edges of any predicate (exclude structural labels).
+  // Only LIVE edges (expired_at IS NULL) - superseded facts stay in history but never
+  // surface as current. PERMISSION-FILTERED PER EDGE: an edge surfaces only if a record
+  // the user may access ASSERTED it (provenance ∩ accessible ≠ ∅). Endpoint visibility
+  // is NOT enough - two visible entities can still have a relationship stated only in a
+  // record the user can't see (fail-closed: no provenance match ⇒ hidden).
+  const relations = sql
+    .rows<{ src: string; dst: string; label: string; weight: number; provenance: string }>(
+      `SELECT DISTINCT src, dst, label, weight, provenance FROM edges
+       WHERE label NOT IN ('mentions','permissions','belongsTo','inheritPermissions') AND expired_at IS NULL
+       ORDER BY weight DESC`,
+      [],
+    )
+    .filter((r) => ids.has(r.src) && ids.has(r.dst) && (JSON.parse(r.provenance || "[]") as string[]).some((p) => accessible.has(p)))
+    .map((r) => ({ from: r.src, to: r.dst, type: r.label, weight: r.weight }))
+  return { entities: ents, relations }
+}

package/src/embedded/graph/pagerank.ts

@@ -0,0 +1,57 @@
+// 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. Pure TS
+// power-iteration (sub-ms at our scale). Returns ranked related entities (seeds
+// excluded). Edge weight (frequency≈confidence) steers the flow.
+
+import type { Adj, Entity } from "./types"
+
+export function personalizedPageRank(
+  entities: Entity[],
+  byId: Map<string, Entity>,
+  adj: Map<string, Adj[]>,
+  seedIds: Set<string>,
+  opts: { alpha: number; iters: number; limit: number },
+): Array<{ label: string; score: number; type: string }> {
+  const { alpha, iters, limit } = opts
+  if (entities.length === 0) return []
+  if (seedIds.size === 0) return []
+
+  const ids = entities.map((e) => e.id)
+  const n = ids.length
+  const idx = new Map(ids.map((id, i) => [id, i]))
+  // weighted out-degree (undirected: adj holds both directions)
+  const deg = new Float64Array(n)
+  for (const id of ids) {
+    let d = 0
+    for (const e of adj.get(id) ?? []) d += e.weight
+    deg[idx.get(id) as number] = d || 1
+  }
+  // personalization vector: mass on the seeds
+  const teleport = new Float64Array(n)
+  for (const s of seedIds) {
+    const i = idx.get(s)
+    if (i !== undefined) teleport[i] = 1 / seedIds.size
+  }
+  let r = Float64Array.from(teleport)
+  for (let it = 0; it < iters; it++) {
+    const next = new Float64Array(n)
+    for (let i = 0; i < n; i++) next[i] = (1 - alpha) * teleport[i] // restart to seeds
+    for (const id of ids) {
+      const i = idx.get(id) as number
+      if (r[i] === 0) continue
+      const share = (alpha * r[i]) / deg[i]
+      for (const e of adj.get(id) ?? []) {
+        const j = idx.get(e.to)
+        if (j !== undefined) next[j] += share * e.weight
+      }
+    }
+    r = next
+  }
+  return ids
+    .map((id, i) => ({ id, label: byId.get(id)?.label ?? id, type: byId.get(id)?.type ?? "", score: r[i] }))
+    .filter((x) => !seedIds.has(x.id) && x.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ label, score, type }) => ({ label, score, type }))
+}

package/src/embedded/graph/sql-access.ts

@@ -0,0 +1,13 @@
+// Tiny SQL-access seam shared by the provider's decomposed query modules. The
+// provider passes itself (its `rows` + `ph` helpers over bun:sqlite) so the
+// permission-path and knowledge-graph functions stay pure of any class state.
+
+export interface SqlAccess {
+  /** Run `sql` with positional params, return all rows typed as T[]. */
+  rows<T = any>(sql: string, params: unknown[]): T[]
+  /** Build a comma-joined run of `n` positional placeholders ("?,?,?"). */
+  ph(n: number): string
+}
+
+export const COMPLETED = "COMPLETED"
+export type Pair = { rid: string; vid: string | null }

package/src/embedded/graph/traversal.ts

@@ -0,0 +1,73 @@
+// Traversal - direct neighbors and shortest relation chains (undirected,
+// hub-avoiding BFS). Pure over the scoped subgraph; results are labeled by the
+// caller-provided byId map. ACL-safe by construction (the subgraph already
+// excludes inaccessible entities/edges).
+
+import type { NeighborResult, PathResult } from "../graph-query"
+import { hubThreshold, labelOf } from "./adjacency"
+import type { Adj, Entity } from "./types"
+
+/** Direct neighbors of the resolved entity ids, optionally filtered by relation,
+ *  typed-relationships-first then heaviest first. */
+export function neighborsOf(
+  ids: string[],
+  byId: Map<string, Entity>,
+  adj: Map<string, Adj[]>,
+  relation?: string,
+): NeighborResult {
+  const seen = new Set<string>()
+  const neighbors: NeighborResult["neighbors"] = []
+  for (const id of ids) {
+    for (const e of adj.get(id) ?? []) {
+      if (relation && e.type !== relation) continue
+      const key = `${e.to}|${e.type}|${e.dir}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      neighbors.push({ label: labelOf(e.to, byId), relation: e.type, direction: e.dir, weight: e.weight })
+    }
+  }
+  // Typed relationships first, then by weight - so real predicates lead over "relates_to".
+  neighbors.sort((a, b) => (a.relation === "relates_to" ? 1 : 0) - (b.relation === "relates_to" ? 1 : 0) || b.weight - a.weight)
+  return { entity: labelOf(ids[0], byId), neighbors }
+}
+
+/** Shortest relation chain between two id sets (undirected BFS, hub-avoiding).
+ *  Answers "how are X and Y related?" - the single most useful graph query. */
+export function shortestPath(
+  startIds: string[],
+  goalIds: Set<string>,
+  byId: Map<string, Entity>,
+  adj: Map<string, Adj[]>,
+): PathResult {
+  if (startIds.length === 0 || goalIds.size === 0) return { found: false, hops: 0, steps: [] }
+  const hub = hubThreshold(adj)
+  const prev = new Map<string, { from: string; type: string }>()
+  const queue: string[] = [...startIds]
+  const visited = new Set<string>(startIds)
+  let hitGoal: string | null = null
+  while (queue.length) {
+    const cur = queue.shift() as string
+    if (goalIds.has(cur)) {
+      hitGoal = cur
+      break
+    }
+    // don't EXPAND through a hub (but it can still be a goal, handled above)
+    if ((adj.get(cur)?.length ?? 0) > hub && !startIds.includes(cur)) continue
+    for (const e of adj.get(cur) ?? []) {
+      if (visited.has(e.to)) continue
+      visited.add(e.to)
+      prev.set(e.to, { from: cur, type: e.type })
+      queue.push(e.to)
+    }
+  }
+  if (!hitGoal) return { found: false, hops: 0, steps: [] }
+  // reconstruct
+  const chain: Array<{ from: string; relation: string; to: string }> = []
+  let node = hitGoal
+  while (prev.has(node)) {
+    const p = prev.get(node) as { from: string; type: string }
+    chain.unshift({ from: labelOf(p.from, byId), relation: p.type, to: labelOf(node, byId) })
+    node = p.from
+  }
+  return { found: true, hops: chain.length, steps: chain }
+}

package/src/embedded/graph/types.ts

@@ -0,0 +1,35 @@
+// Shared in-memory graph shapes used across the decomposed graph-query modules.
+// These mirror the structures GraphQueryService builds from the provider's
+// ACL-scoped {entities, relations}; kept here so the pure-function modules can
+// be typed without depending on the orchestrating class.
+
+export interface Entity {
+  id: string
+  label: string
+  type: string
+}
+
+export interface Relation {
+  from: string
+  to: string
+  type: string
+  weight: number
+}
+
+export interface Adj {
+  to: string
+  type: string
+  weight: number
+  dir: "out" | "in"
+}
+
+/** The ACL-scoped subgraph: entities + LIVE relations the user may see, plus the
+ *  derived id→entity map, adjacency, and the accessible record id set. Every
+ *  traversal works ONLY over this, so no query crosses a permission boundary. */
+export interface ScopedGraph {
+  entities: Entity[]
+  relations: Relation[]
+  byId: Map<string, Entity>
+  adj: Map<string, Adj[]>
+  recordIds: string[]
+}