Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
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.scalanew file mode 100644index 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.scalanew file mode 100644index 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.scalanew file mode 100644index 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+ }+ }+ }+}