Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat: add GraphQueryApi with getNode, expand, search, and MVCC visibility

riley0227944e57c5c4e9
diff --git a/memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala b/memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala
new file mode 100644
index 00000000..f47f5413
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala
@@ -0,0 +1,251 @@
+package ix.memory.db
+
+import java.time.Instant
+import java.util.UUID
+
+import cats.effect.IO
+import cats.syntax.traverse._
+import io.circe.Json
+
+import ix.memory.model._
+
+class ArangoGraphQueryApi(client: ArangoClient) extends GraphQueryApi {
+
+ // ── Public API ──────────────────────────────────────────────────────
+
+ override def getNode(tenant: TenantId, id: NodeId, asOfRev: Option[Rev] = None): IO[Option[GraphNode]] =
+ for {
+ rev <- asOfRev.fold(getLatestRev(tenant))(IO.pure)
+ result <- client.queryOne(
+ """FOR n IN nodes
+ | FILTER n._key == @id
+ | AND n.tenant == @tenant
+ | AND n.created_rev <= @rev
+ | AND (n.deleted_rev == null OR @rev < n.deleted_rev)
+ | RETURN n""".stripMargin,
+ Map(
+ "id" -> id.value.toString.asInstanceOf[AnyRef],
+ "tenant" -> tenant.value.toString.asInstanceOf[AnyRef],
+ "rev" -> Long.box(rev.value).asInstanceOf[AnyRef]
+ )
+ )
+ } yield result.flatMap(parseNode)
+
+ override def findNodesByKind(tenant: TenantId, kind: NodeKind, limit: Int = 100): IO[Vector[GraphNode]] =
+ client.query(
+ """FOR n IN nodes
+ | FILTER n.tenant == @tenant
+ | AND n.kind == @kind
+ | AND n.deleted_rev == null
+ | LIMIT @limit
+ | RETURN n""".stripMargin,
+ Map(
+ "tenant" -> tenant.value.toString.asInstanceOf[AnyRef],
+ "kind" -> nodeKindToString(kind).asInstanceOf[AnyRef],
+ "limit" -> Int.box(limit).asInstanceOf[AnyRef]
+ )
+ ).map(_.flatMap(parseNode).toVector)
+
+ override def searchNodes(tenant: TenantId, text: String, limit: Int = 20): IO[Vector[GraphNode]] =
+ client.query(
+ """FOR n IN nodes
+ | FILTER n.tenant == @tenant
+ | AND CONTAINS(LOWER(n.name), LOWER(@text))
+ | AND n.deleted_rev == null
+ | LIMIT @limit
+ | RETURN n""".stripMargin,
+ Map(
+ "tenant" -> tenant.value.toString.asInstanceOf[AnyRef],
+ "text" -> text.asInstanceOf[AnyRef],
+ "limit" -> Int.box(limit).asInstanceOf[AnyRef]
+ )
+ ).map(_.flatMap(parseNode).toVector)
+
+ override def expand(
+ tenant: TenantId,
+ nodeId: NodeId,
+ direction: Direction,
+ predicates: Option[Set[String]] = None,
+ hops: Int = 1,
+ asOfRev: Option[Rev] = None
+ ): IO[ExpandResult] = {
+ val predicateFilter = predicates.filter(_.nonEmpty) match {
+ case Some(_) => " AND e.predicate IN @predicates"
+ case None => ""
+ }
+
+ val deletedFilter = asOfRev match {
+ case Some(_) => " AND e.created_rev <= @rev AND (e.deleted_rev == null OR @rev < e.deleted_rev)"
+ case None => " AND e.deleted_rev == null"
+ }
+
+ def buildEdgeQuery(srcOrDst: String): String =
+ s"""FOR e IN edges
+ | FILTER e.tenant == @tenant
+ | AND e.$srcOrDst == @nodeId
+ | $deletedFilter
+ | $predicateFilter
+ | RETURN e""".stripMargin
+
+ def buildBindVars(rev: Option[Rev]): Map[String, AnyRef] = {
+ val base = Map(
+ "tenant" -> tenant.value.toString.asInstanceOf[AnyRef],
+ "nodeId" -> nodeId.value.toString.asInstanceOf[AnyRef]
+ )
+ val withRev = rev match {
+ case Some(r) => base + ("rev" -> Long.box(r.value).asInstanceOf[AnyRef])
+ case None => base
+ }
+ predicates.filter(_.nonEmpty) match {
+ case Some(ps) =>
+ val javaList = new java.util.ArrayList[String]()
+ ps.foreach(javaList.add)
+ withRev + ("predicates" -> javaList.asInstanceOf[AnyRef])
+ case None => withRev
+ }
+ }
+
+ for {
+ rev <- asOfRev.fold(IO.none[Rev])(r => IO.pure(Some(r)))
+ bindVars = buildBindVars(rev)
+
+ outEdges <- direction match {
+ case Direction.Out | Direction.Both =>
+ client.query(buildEdgeQuery("src"), bindVars).map(_.flatMap(parseEdge).toVector)
+ case Direction.In =>
+ IO.pure(Vector.empty[GraphEdge])
+ }
+
+ inEdges <- direction match {
+ case Direction.In | Direction.Both =>
+ client.query(buildEdgeQuery("dst"), bindVars).map(_.flatMap(parseEdge).toVector)
+ case Direction.Out =>
+ IO.pure(Vector.empty[GraphEdge])
+ }
+
+ allEdges = (outEdges ++ inEdges).distinctBy(_.id)
+
+ // Collect the "other side" node IDs
+ neighborIds = allEdges.flatMap { e =>
+ if (e.src == nodeId) Vector(e.dst)
+ else if (e.dst == nodeId) Vector(e.src)
+ else Vector(e.src, e.dst)
+ }.distinct
+
+ // Fetch the neighbor nodes
+ nodes <- neighborIds.traverse { nid =>
+ getNode(tenant, nid, asOfRev)
+ }.map(_.flatten)
+
+ } yield ExpandResult(nodes, allEdges)
+ }
+
+ override def getClaims(tenant: TenantId, entityId: NodeId): IO[Vector[Claim]] =
+ client.query(
+ """FOR c IN claims
+ | FILTER c.tenant == @tenant
+ | AND c.entity_id == @entityId
+ | AND c.deleted_rev == null
+ | RETURN c""".stripMargin,
+ Map(
+ "tenant" -> tenant.value.toString.asInstanceOf[AnyRef],
+ "entityId" -> entityId.value.toString.asInstanceOf[AnyRef]
+ )
+ ).map(_.flatMap(parseClaim).toVector)
+
+ override def getLatestRev(tenant: TenantId): IO[Rev] =
+ client.queryOne(
+ """FOR r IN revisions
+ | FILTER r._key == @key
+ | RETURN r.rev""".stripMargin,
+ Map("key" -> tenant.value.toString.asInstanceOf[AnyRef])
+ ).map(_.flatMap(_.as[Long].toOption).map(Rev(_)).getOrElse(Rev(0L)))
+
+ // ── JSON Parsers (snake_case → camelCase) ───────────────────────────
+
+ private def parseNode(json: Json): Option[GraphNode] = {
+ val c = json.hcursor
+ for {
+ id <- c.get[String]("id").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(NodeId(_))
+ kindStr <- c.get[String]("kind").toOption
+ kind <- NodeKind.decoder.decodeJson(Json.fromString(kindStr)).toOption
+ tenantStr <- c.get[String]("tenant").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(TenantId(_))
+ attrs <- c.get[Json]("attrs").toOption
+ provenance <- parseProvenance(c.downField("provenance").focus)
+ createdRev <- c.get[Long]("created_rev").toOption.map(Rev(_))
+ deletedRev = c.get[Long]("deleted_rev").toOption.map(Rev(_))
+ createdAt <- c.get[String]("created_at").toOption
+ .flatMap(s => scala.util.Try(Instant.parse(s)).toOption)
+ updatedAt <- c.get[String]("updated_at").toOption
+ .flatMap(s => scala.util.Try(Instant.parse(s)).toOption)
+ } yield GraphNode(id, kind, tenantStr, attrs, provenance, createdRev, deletedRev, createdAt, updatedAt)
+ }
+
+ private def parseEdge(json: Json): Option[GraphEdge] = {
+ val c = json.hcursor
+ for {
+ id <- c.get[String]("id").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(EdgeId(_))
+ src <- c.get[String]("src").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(NodeId(_))
+ dst <- c.get[String]("dst").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(NodeId(_))
+ predicate <- c.get[String]("predicate").toOption.map(EdgePredicate(_))
+ tenantStr <- c.get[String]("tenant").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(TenantId(_))
+ attrs <- c.get[Json]("attrs").toOption
+ provenance <- parseProvenance(c.downField("provenance").focus)
+ createdRev <- c.get[Long]("created_rev").toOption.map(Rev(_))
+ deletedRev = c.get[Long]("deleted_rev").toOption.map(Rev(_))
+ } yield GraphEdge(id, src, dst, predicate, tenantStr, attrs, provenance, createdRev, deletedRev)
+ }
+
+ private def parseClaim(json: Json): Option[Claim] = {
+ val c = json.hcursor
+ for {
+ key <- c.get[String]("_key").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(ClaimId(_))
+ entityId <- c.get[String]("entity_id").toOption
+ .flatMap(s => scala.util.Try(UUID.fromString(s)).toOption)
+ .map(NodeId(_))
+ field <- c.get[String]("field").toOption
+ statusStr <- c.get[String]("status").toOption
+ status <- statusStr.toLowerCase match {
+ case "active" => Some(ClaimStatus.Active)
+ case "stale" => Some(ClaimStatus.Stale)
+ case "retracted" => Some(ClaimStatus.Retracted)
+ case _ => None
+ }
+ provenance <- parseProvenance(c.downField("provenance").focus)
+ createdRev <- c.get[Long]("created_rev").toOption.map(Rev(_))
+ deletedRev = c.get[Long]("deleted_rev").toOption.map(Rev(_))
+ } yield Claim(key, entityId, field, status, provenance, createdRev, deletedRev)
+ }
+
+ private def parseProvenance(jsonOpt: Option[Json]): Option[Provenance] = {
+ jsonOpt.flatMap { json =>
+ val c = json.hcursor
+ for {
+ sourceUri <- c.get[String]("source_uri").toOption
+ sourceHash = c.get[String]("source_hash").toOption
+ extractor <- c.get[String]("extractor").toOption
+ stStr <- c.get[String]("source_type").toOption
+ sourceType <- SourceType.decoder.decodeJson(Json.fromString(stStr)).toOption
+ observedAt <- c.get[String]("observed_at").toOption
+ .flatMap(s => scala.util.Try(Instant.parse(s)).toOption)
+ } yield Provenance(sourceUri, sourceHash, extractor, sourceType, observedAt)
+ }
+ }
+
+ private def nodeKindToString(nk: NodeKind): String =
+ NodeKind.encoder.apply(nk).asString.getOrElse(nk.toString)
+}
diff --git a/memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala b/memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala
new file mode 100644
index 00000000..81979e89
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala
@@ -0,0 +1,24 @@
+package ix.memory.db
+
+import cats.effect.IO
+import ix.memory.model._
+
+trait GraphQueryApi {
+ def getNode(tenant: TenantId, id: NodeId, asOfRev: Option[Rev] = None): IO[Option[GraphNode]]
+ def findNodesByKind(tenant: TenantId, kind: NodeKind, limit: Int = 100): IO[Vector[GraphNode]]
+ def searchNodes(tenant: TenantId, text: String, limit: Int = 20): IO[Vector[GraphNode]]
+ def expand(tenant: TenantId, nodeId: NodeId, direction: Direction,
+ predicates: Option[Set[String]] = None, hops: Int = 1,
+ asOfRev: Option[Rev] = None): IO[ExpandResult]
+ def getClaims(tenant: TenantId, entityId: NodeId): IO[Vector[Claim]]
+ def getLatestRev(tenant: TenantId): IO[Rev]
+}
+
+sealed trait Direction
+object Direction {
+ case object Out extends Direction
+ case object In extends Direction
+ case object Both extends Direction
+}
+
+final case class ExpandResult(nodes: Vector[GraphNode], edges: Vector[GraphEdge])
diff --git a/memory-layer/src/test/scala/ix/memory/db/GraphQueryApiSpec.scala b/memory-layer/src/test/scala/ix/memory/db/GraphQueryApiSpec.scala
new file mode 100644
index 00000000..77cd3456
--- /dev/null
+++ b/memory-layer/src/test/scala/ix/memory/db/GraphQueryApiSpec.scala
@@ -0,0 +1,286 @@
+package ix.memory.db
+
+import java.time.Instant
+import java.util.UUID
+
+import cats.effect.IO
+import cats.effect.testing.scalatest.AsyncIOSpec
+import io.circe.Json
+import org.scalatest.flatspec.AsyncFlatSpec
+import org.scalatest.matchers.should.Matchers
+
+import ix.memory.model._
+
+class GraphQueryApiSpec extends AsyncFlatSpec with AsyncIOSpec with Matchers {
+
+ val clientResource = ArangoClient.resource(
+ host = "localhost", port = 8529,
+ database = "ix_memory_test", user = "root", password = ""
+ )
+
+ private def makePatch(
+ tenant: TenantId,
+ baseRev: Rev = Rev(0L),
+ ops: Vector[PatchOp] = Vector.empty,
+ patchId: PatchId = PatchId(UUID.randomUUID())
+ ): GraphPatch =
+ GraphPatch(
+ patchId = patchId,
+ tenant = tenant,
+ actor = "test-actor",
+ timestamp = Instant.parse("2025-06-01T12:00:00Z"),
+ source = PatchSource(
+ uri = "test://source",
+ sourceHash = Some("hash123"),
+ extractor = "test-extractor",
+ sourceType = SourceType.Code
+ ),
+ baseRev = baseRev,
+ ops = ops,
+ replaces = Vector.empty,
+ intent = Some("test intent")
+ )
+
+ // ── Test 1: getNode should return a committed node ──────────────────
+
+ "GraphQueryApi" should "getNode should return a committed node" in {
+ clientResource.use { client =>
+ for {
+ _ <- client.ensureSchema()
+ writeApi = new ArangoGraphWriteApi(client)
+ queryApi = new ArangoGraphQueryApi(client)
+ tenant = TenantId(UUID.randomUUID())
+ nodeId = NodeId(UUID.randomUUID())
+ patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(
+ id = nodeId,
+ kind = NodeKind.Function,
+ name = "billing_calc",
+ attrs = Map("lang" -> Json.fromString("scala"))
+ )
+ )
+ )
+ _ <- writeApi.commitPatch(patch)
+ result <- queryApi.getNode(tenant, nodeId)
+ } yield {
+ result shouldBe defined
+ val node = result.get
+ node.id shouldBe nodeId
+ node.kind shouldBe NodeKind.Function
+ node.tenant shouldBe tenant
+ node.attrs.hcursor.get[String]("lang") shouldBe Right("scala")
+ node.provenance.extractor shouldBe "test-extractor"
+ node.provenance.sourceType shouldBe SourceType.Code
+ node.deletedRev shouldBe None
+ }
+ }
+ }
+
+ // ── Test 2: getNode should respect MVCC visibility ──────────────────
+
+ it should "getNode should respect MVCC visibility" in {
+ clientResource.use { client =>
+ for {
+ _ <- client.ensureSchema()
+ writeApi = new ArangoGraphWriteApi(client)
+ queryApi = new ArangoGraphQueryApi(client)
+ tenant = TenantId(UUID.randomUUID())
+ nodeId = NodeId(UUID.randomUUID())
+ // Commit patch1: create the node
+ patch1 = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(
+ id = nodeId,
+ kind = NodeKind.Class,
+ name = "MyClass",
+ attrs = Map.empty[String, Json]
+ )
+ )
+ )
+ res1 <- writeApi.commitPatch(patch1)
+ rev1 = res1.newRev
+ // Commit patch2: delete the node
+ patch2 = makePatch(
+ tenant = tenant,
+ baseRev = rev1,
+ ops = Vector(PatchOp.DeleteNode(nodeId))
+ )
+ res2 <- writeApi.commitPatch(patch2)
+ rev2 = res2.newRev
+ // Query as of rev1 → should see the node
+ atRev1 <- queryApi.getNode(tenant, nodeId, asOfRev = Some(rev1))
+ // Query as of rev2 → should not see the node (deleted)
+ atRev2 <- queryApi.getNode(tenant, nodeId, asOfRev = Some(rev2))
+ } yield {
+ atRev1 shouldBe defined
+ atRev1.get.id shouldBe nodeId
+ atRev2 shouldBe None
+ }
+ }
+ }
+
+ // ── Test 3: findNodesByKind should return nodes of given kind ────────
+
+ it should "findNodesByKind should return nodes of given kind" in {
+ clientResource.use { client =>
+ for {
+ _ <- client.ensureSchema()
+ writeApi = new ArangoGraphWriteApi(client)
+ queryApi = new ArangoGraphQueryApi(client)
+ tenant = TenantId(UUID.randomUUID())
+ funcId1 = NodeId(UUID.randomUUID())
+ funcId2 = NodeId(UUID.randomUUID())
+ classId = NodeId(UUID.randomUUID())
+ patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(funcId1, NodeKind.Function, "func1", Map.empty[String, Json]),
+ PatchOp.UpsertNode(funcId2, NodeKind.Function, "func2", Map.empty[String, Json]),
+ PatchOp.UpsertNode(classId, NodeKind.Class, "cls1", Map.empty[String, Json])
+ )
+ )
+ _ <- writeApi.commitPatch(patch)
+ funcs <- queryApi.findNodesByKind(tenant, NodeKind.Function)
+ classes <- queryApi.findNodesByKind(tenant, NodeKind.Class)
+ } yield {
+ funcs.length shouldBe 2
+ funcs.map(_.kind).toSet shouldBe Set(NodeKind.Function)
+ classes.length shouldBe 1
+ classes.head.kind shouldBe NodeKind.Class
+ }
+ }
+ }
+
+ // ── Test 4: expand should return connected nodes and edges ──────────
+
+ it should "expand should return connected nodes and edges" in {
+ clientResource.use { client =>
+ for {
+ _ <- client.ensureSchema()
+ writeApi = new ArangoGraphWriteApi(client)
+ queryApi = new ArangoGraphQueryApi(client)
+ tenant = TenantId(UUID.randomUUID())
+ nodeA = NodeId(UUID.randomUUID())
+ nodeB = NodeId(UUID.randomUUID())
+ edgeId = EdgeId(UUID.randomUUID())
+ patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(nodeA, NodeKind.Function, "funcA", Map.empty[String, Json]),
+ PatchOp.UpsertNode(nodeB, NodeKind.Function, "funcB", Map.empty[String, Json]),
+ PatchOp.UpsertEdge(edgeId, nodeA, nodeB, EdgePredicate("calls"), Map.empty[String, Json])
+ )
+ )
+ _ <- writeApi.commitPatch(patch)
+ outRes <- queryApi.expand(tenant, nodeA, Direction.Out)
+ inRes <- queryApi.expand(tenant, nodeB, Direction.In)
+ bothRes <- queryApi.expand(tenant, nodeA, Direction.Both)
+ } yield {
+ // Out from nodeA should find nodeB via "calls" edge
+ outRes.edges.length shouldBe 1
+ outRes.edges.head.predicate shouldBe EdgePredicate("calls")
+ outRes.edges.head.src shouldBe nodeA
+ outRes.edges.head.dst shouldBe nodeB
+ outRes.nodes.length shouldBe 1
+ outRes.nodes.head.id shouldBe nodeB
+
+ // In to nodeB should find nodeA
+ inRes.edges.length shouldBe 1
+ inRes.nodes.length shouldBe 1
+ inRes.nodes.head.id shouldBe nodeA
+
+ // Both from nodeA should also find the edge/node
+ bothRes.edges.length shouldBe 1
+ bothRes.nodes.length shouldBe 1
+ }
+ }
+ }
+
+ // ── Test 5: searchNodes should find nodes by name ───────────────────
+
+ it should "searchNodes should find nodes by name" in {
+ clientResource.use { client =>
+ for {
+ _ <- client.ensureSchema()
+ writeApi = new ArangoGraphWriteApi(client)
+ queryApi = new ArangoGraphQueryApi(client)
+ tenant = TenantId(UUID.randomUUID())
+ node1 = NodeId(UUID.randomUUID())
+ node2 = NodeId(UUID.randomUUID())
+ patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(node1, NodeKind.Service, "billing_service", Map.empty[String, Json]),
+ PatchOp.UpsertNode(node2, NodeKind.Service, "payment_gateway", Map.empty[String, Json])
+ )
+ )
+ _ <- writeApi.commitPatch(patch)
+ results <- queryApi.searchNodes(tenant, "billing")
+ } yield {
+ results.length shouldBe 1
+ results.head.id shouldBe node1
+ }
+ }
+ }
+
+ // ── Test 6: getClaims should return active claims for entity ────────
+
+ it should "getClaims should return active claims for entity" in {
+ clientResource.use { client =>
+ for {
+ _ <- client.ensureSchema()
+ writeApi = new ArangoGraphWriteApi(client)
+ queryApi = new ArangoGraphQueryApi(client)
+ tenant = TenantId(UUID.randomUUID())
+ nodeId = NodeId(UUID.randomUUID())
+ patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(nodeId, NodeKind.Function, "myFunc", Map.empty[String, Json]),
+ PatchOp.AssertClaim(nodeId, "returns", Json.fromString("Int"), Some(0.9))
+ )
+ )
+ _ <- writeApi.commitPatch(patch)
+ claims <- queryApi.getClaims(tenant, nodeId)
+ } yield {
+ claims.length shouldBe 1
+ val claim = claims.head
+ claim.entityId shouldBe nodeId
+ claim.statement shouldBe "returns"
+ claim.status shouldBe ClaimStatus.Active
+ claim.provenance.extractor shouldBe "test-extractor"
+ }
+ }
+ }
+
+ // ── Test 7: getLatestRev should return current revision ─────────────
+
+ it should "getLatestRev should return current revision" in {
+ clientResource.use { client =>
+ for {
+ _ <- client.ensureSchema()
+ writeApi = new ArangoGraphWriteApi(client)
+ queryApi = new ArangoGraphQueryApi(client)
+ tenant = TenantId(UUID.randomUUID())
+ nodeId = NodeId(UUID.randomUUID())
+ // Before any commits, rev should be 0
+ rev0 <- queryApi.getLatestRev(tenant)
+ patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(nodeId, NodeKind.Module, "mod1", Map.empty[String, Json])
+ )
+ )
+ res <- writeApi.commitPatch(patch)
+ rev1 <- queryApi.getLatestRev(tenant)
+ } yield {
+ rev0 shouldBe Rev(0L)
+ rev1 shouldBe res.newRev
+ rev1.value should be > 0L
+ }
+ }
+ }
+}