Unify graph edge direction reporting

Author: shisoft

GRAPH_DSL.md

@@ -106,6 +106,16 @@ Hybrid search uses **Reciprocal Rank Fusion (RRF)** to merge the two result list
 "undirected"  — follow edges in either role
 ```
 
+### Edge Response Semantics
+
+All graph DSL edge lists use the same contract:
+
+- `from` / `to` describe the edge itself, using the stored edge orientation.
+- `direction` describes how that edge was traversed relative to the current vertex:
+    - `"out"`  — traversed from source to target
+    - `"in"`   — traversed from target to source
+    - `"none"` — undirected edge
+
 ### Field Projection (`select` / `edge_select`)
 
 All graph DSL operations that return vertices or edges support optional field-projection fields at the top level of their
@@ -368,6 +378,7 @@ Extracts all vertices and edges reachable from a set of seed vertices within a b
         {
             "from": "3mFx...",
             "to":   "7kLp...",
+            "direction": "out",
             "schema": "Knows",
             "fields": { "since": 2019 }
         }
@@ -524,9 +535,9 @@ the endpoint vertices.
         { "id": "7kLp...", "schema": "Person", "fields": { "name": "Bob" }   }
     ],
     "edges": [
-        { "from": "3mFx...", "to": "9qRz...", "schema": "Knows",    "fields": {} },
-        { "from": "9qRz...", "to": "2pNw...", "schema": "WorksAt",  "fields": {} },
-        { "from": "2pNw...", "to": "7kLp...", "schema": "Employs",  "fields": {} }
+        { "from": "3mFx...", "to": "9qRz...", "direction": "out",  "schema": "Knows",    "fields": {} },
+        { "from": "9qRz...", "to": "2pNw...", "direction": "out",  "schema": "WorksAt",  "fields": {} },
+        { "from": "2pNw...", "to": "7kLp...", "direction": "out",  "schema": "Employs",  "fields": {} }
     ]
 }
 ```
@@ -870,7 +881,7 @@ The `expand` clause is identical to the one in the [Subgraph DSL](#subgraph-dsl-
 
     // Edges discovered during expansion.
     "edges": [
-        { "from": "6hYw...", "to": "1cZa...", "schema": "NextChunk", "fields": {} }
+        { "from": "6hYw...", "to": "1cZa...", "direction": "out", "schema": "NextChunk", "fields": {} }
     ]
 }
 ```

HTTP_API.md

@@ -347,7 +347,9 @@ Query edge body cells using the same request shape as `/v1/query`:
 ```
 
 - Edge query currently supports edge schemas with body fields.
-- Response includes `cell_id`, `from_id`, `to_id`, `schema_id`, `edge_type`, and `body`.
+- Response includes `cell_id`, `from_id`, `to_id`, `direction`, `schema_id`, `edge_type`, and `body`.
+- `direction` uses the same wire values as graph DSL edge lists: `out`, `in`, `none`.
+- For `/v1/graph/query/edges`, `direction` is `out` for directed edges and `none` for undirected edges.
 
 `POST /v1/graph/query/traverse`
 
@@ -373,6 +375,8 @@ Request:
 - `max_depth` defaults to `1` when omitted.
 - Traversal runs in two stages: Neb lookup for seed IDs first, then graph BFS expansion from those seeds.
 - Duplicate discovered vertices are de-duplicated before vertex materialization in the final response.
+- `edges[*].from_id` / `to_id` describe the edge itself rather than the traversal step.
+- `edges[*].direction` reports how traversal reached that edge: `out`, `in`, or `none`.
 
 Response:
 ```json
@@ -385,6 +389,7 @@ Response:
         "id": "3Yv8v4Cw1W5Hk9p2LxQw9Q",
         "from_id": "5QqkMJFr5s7J9wB8Q2kN1J",
         "to_id": "2m8JqZfC2MbgQfE7x4oP6R",
+        "direction": "out",
         "schema_id": 77,
         "edge_type": "Directed"
       }

crates/morpheus-http-client/src/types.rs

@@ -629,6 +629,7 @@ pub struct GraphTraverseEdgeDto {
     pub id: Option<String>,
     pub from_id: String,
     pub to_id: String,
+    pub direction: String,
     pub schema_id: u32,
     pub edge_type: Value,
 }
@@ -692,6 +693,7 @@ pub struct GraphLookupEdgeDto {
     pub cell_id: String,
     pub from_id: String,
     pub to_id: String,
+    pub direction: String,
     pub schema_id: u32,
     pub edge_type: Value,
     pub body: Value,
@@ -714,6 +716,7 @@ pub struct DslSubgraphVertex {
 pub struct DslSubgraphEdge {
     pub from: String,
     pub to: String,
+    pub direction: String,
     pub schema: String,
     pub fields: serde_json::Map<String, Value>,
 }

src/dsl/graph/exec_context.rs

@@ -9,14 +9,14 @@ use crate::dsl::exec_helpers::{
     build_field_names, cell_data_to_json_map, distributed_directions_for_edge_schemas,
     id_to_base58, project_fields,
 };
-use crate::dsl::graph::json::{GraphRAGResult, GraphRAGSeedVertex, SubgraphEdge, SubgraphVertex};
+use crate::dsl::graph::json::{GraphRAGResult, GraphRAGSeedVertex, SubgraphVertex};
+use crate::dsl::graph::path_materialize::{expand_edge_report_key, materialize_expand_edges};
 use crate::dsl::query::bind::{extract_root_seed_ids, BoundGraphRAGQuery, BoundPredicate};
 use crate::graph::edge::EdgeType;
 use crate::server::schema::GraphSchema;
 use crate::server::MorpheusRuntime;
 use crate::traversal::dist::adjacency::{AdjacencyConfig, WeightSpec};
-use crate::traversal::expand::distributed::{ExpandJobOptions, ExpandRunConfig};
-use serde_json::Map as JsonMap;
+use crate::traversal::expand::distributed::{ExpandEdge, ExpandJobOptions, ExpandRunConfig};
 
 pub async fn execute_context(
     runtime: &Arc<MorpheusRuntime>,
@@ -34,7 +34,7 @@ pub async fn execute_context(
 
     // 2. BFS expand from seeds across all edge schemas.
     let mut expanded_vertex_ids: HashSet<Id> = HashSet::new();
-    let mut all_edges: Vec<(Id, Id, u32, Option<Id>)> = Vec::new();
+    let mut all_edges: Vec<ExpandEdge> = Vec::new();
     let directions = distributed_directions_for_edge_schemas(
         runtime,
         &query.expand.edge_schema_ids,
@@ -71,9 +71,7 @@ pub async fn execute_context(
                 expanded_vertex_ids.insert(*id);
             }
         }
-        for e in result.edges {
-            all_edges.push((e.from, e.to, e.schema_id, e.edge_id));
-        }
+        all_edges.extend(result.edges);
     }
 
     // 3. Build seed vertices with scores.
@@ -154,67 +152,21 @@ pub async fn execute_context(
     }
 
     // Deduplicate and build edges.
-    let mut seen_edges: HashSet<(Id, Id, u32)> = HashSet::new();
+    let mut seen_edges = HashSet::new();
     let deduped: Vec<_> = all_edges
         .into_iter()
-        .filter(|(from, to, schema_id, _)| {
+        .filter(|edge| {
             let edge_type = runtime
                 .schema_container()
-                .schema_type(*schema_id)
+                .schema_type(edge.schema_id)
                 .and_then(|gs| match gs {
                     GraphSchema::Edge(attrs) => Some(attrs.edge_type),
                     _ => None,
                 });
-            let key = match edge_type {
-                Some(EdgeType::Undirected) => {
-                    let (a, b) = if from.higher < to.higher
-                        || (from.higher == to.higher && from.lower <= to.lower)
-                    {
-                        (*from, *to)
-                    } else {
-                        (*to, *from)
-                    };
-                    (a, b, *schema_id)
-                }
-                _ => (*from, *to, *schema_id),
-            };
-            seen_edges.insert(key)
+            seen_edges.insert(expand_edge_report_key(edge, edge_type))
         })
         .collect();
-
-    let mut edges: Vec<SubgraphEdge> = Vec::with_capacity(deduped.len());
-    for (from, to, schema_id, edge_body_id) in deduped {
-        let schema_name = runtime
-            .schema_container()
-            .get_neb_schema(schema_id)
-            .map(|s| s.name.clone())
-            .unwrap_or_default();
-
-        let fields = if let Some(cell_id) = edge_body_id {
-            match runtime.neb_client().read_cell(cell_id).await {
-                Ok(Ok(cell)) => {
-                    let field_names = runtime
-                        .schema_container()
-                        .get_neb_schema(cell.header.schema)
-                        .map(|s| build_field_names(&s.fields));
-                    project_fields(
-                        cell_data_to_json_map(&cell.data, field_names.as_ref()),
-                        query.edge_select.as_deref(),
-                    )
-                }
-                _ => JsonMap::new(),
-            }
-        } else {
-            JsonMap::new()
-        };
-
-        edges.push(SubgraphEdge {
-            from: id_to_base58(&from),
-            to: id_to_base58(&to),
-            schema: schema_name,
-            fields,
-        });
-    }
+    let edges = materialize_expand_edges(runtime, &deduped, query.edge_select.as_deref()).await?;
 
     Ok(GraphRAGResult {
         seeds: seed_vertices,

src/dsl/graph/exec_path.rs

@@ -330,9 +330,10 @@ pub async fn execute_paths(
         }
         for edge in &path.edges {
             let edge_key = format!(
-                "{}|{}|{}|{}",
+                "{}|{}|{:?}|{}|{}",
                 edge.from,
                 edge.to,
+                edge.direction,
                 edge.schema,
                 serde_json::to_string(&edge.fields).unwrap_or_default()
             );

src/dsl/graph/exec_subgraph.rs

@@ -8,13 +8,14 @@ use crate::dsl::exec_helpers::{
     build_field_names, cell_data_to_json_map, distributed_directions_for_edge_schemas,
     id_to_base58, project_fields, rrf_rerank_ids,
 };
-use crate::dsl::graph::json::{SubgraphEdge, SubgraphResult, SubgraphVertex};
+use crate::dsl::graph::json::{SubgraphResult, SubgraphVertex};
+use crate::dsl::graph::path_materialize::{expand_edge_report_key, materialize_expand_edges};
 use crate::dsl::query::bind::{extract_root_seed_ids, BoundPredicate, BoundSubgraphQuery};
 use crate::graph::edge::EdgeType;
 use crate::server::schema::GraphSchema;
 use crate::server::MorpheusRuntime;
 use crate::traversal::dist::adjacency::{AdjacencyConfig, WeightSpec};
-use crate::traversal::expand::distributed::{ExpandJobOptions, ExpandRunConfig};
+use crate::traversal::expand::distributed::{ExpandEdge, ExpandJobOptions, ExpandRunConfig};
 
 pub async fn execute_subgraph(
     runtime: &Arc<MorpheusRuntime>,
@@ -37,7 +38,7 @@ pub async fn execute_subgraph(
     // Also include the seed vertices themselves
     all_vertex_ids.extend(seeds.iter().copied());
 
-    let mut all_edges: Vec<(Id, Id, u32, Option<Id>)> = Vec::new();
+    let mut all_edges: Vec<ExpandEdge> = Vec::new();
     let directions = distributed_directions_for_edge_schemas(
         runtime,
         &query.expand.edge_schema_ids,
@@ -70,9 +71,7 @@ pub async fn execute_subgraph(
             .map_err(|e| format!("subgraph expand failed: {e}"))?;
 
         all_vertex_ids.extend(result.vertices.iter().copied());
-        for e in result.edges {
-            all_edges.push((e.from, e.to, e.schema_id, e.edge_id));
-        }
+        all_edges.extend(result.edges);
     }
 
     // 3. Fetch vertex cells and serialize to SubgraphVertex
@@ -116,66 +115,22 @@ pub async fn execute_subgraph(
     // Deduplicate by canonical (from, to, schema_id).
     // For undirected schemas, (A,B) and (B,A) represent the same edge; normalise
     // them so that the smaller Id comes first before inserting into the seen set.
-    let mut seen_edges: HashSet<(Id, Id, u32)> = HashSet::new();
+    let mut seen_edges = HashSet::new();
     let deduped_edges: Vec<_> = all_edges
         .into_iter()
-        .filter(|(from, to, schema_id, _)| {
+        .filter(|edge| {
             let edge_type = runtime
                 .schema_container()
-                .schema_type(*schema_id)
+                .schema_type(edge.schema_id)
                 .and_then(|gs| match gs {
                     GraphSchema::Edge(attrs) => Some(attrs.edge_type),
                     _ => None,
                 });
-            let key = match edge_type {
-                Some(EdgeType::Undirected) => {
-                    let (a, b) = if from.higher < to.higher
-                        || (from.higher == to.higher && from.lower <= to.lower)
-                    {
-                        (*from, *to)
-                    } else {
-                        (*to, *from)
-                    };
-                    (a, b, *schema_id)
-                }
-                _ => (*from, *to, *schema_id),
-            };
-            seen_edges.insert(key)
+            seen_edges.insert(expand_edge_report_key(edge, edge_type))
         })
         .collect();
-    let mut edges = Vec::new();
-    for (from, to, schema_id, edge_body_id) in deduped_edges {
-        let schema_name = runtime
-            .schema_container()
-            .get_neb_schema(schema_id)
-            .map(|s| s.name.clone())
-            .unwrap_or_default();
-
-        let fields = if let Some(cell_id) = edge_body_id {
-            match runtime.neb_client().read_cell(cell_id).await {
-                Ok(Ok(cell)) => {
-                    let field_names = runtime
-                        .schema_container()
-                        .get_neb_schema(cell.header.schema)
-                        .map(|s| build_field_names(&s.fields));
-                    project_fields(
-                        cell_data_to_json_map(&cell.data, field_names.as_ref()),
-                        query.edge_select.as_deref(),
-                    )
-                }
-                _ => serde_json::Map::new(),
-            }
-        } else {
-            serde_json::Map::new()
-        };
-
-        edges.push(SubgraphEdge {
-            from: id_to_base58(&from),
-            to: id_to_base58(&to),
-            schema: schema_name,
-            fields,
-        });
-    }
+    let edges = materialize_expand_edges(runtime, &deduped_edges, query.edge_select.as_deref())
+        .await?;
 
     Ok(SubgraphResult { vertices, edges })
 }

src/dsl/graph/json.rs

@@ -232,10 +232,21 @@ pub struct SubgraphVertex {
     pub fields: serde_json::Map<String, serde_json::Value>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum SubgraphEdgeDirection {
+    #[serde(rename = "in")]
+    In,
+    #[serde(rename = "out")]
+    Out,
+    #[serde(rename = "none")]
+    None,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SubgraphEdge {
     pub from: String,
     pub to: String,
+    pub direction: SubgraphEdgeDirection,
     pub schema: String,
     pub fields: serde_json::Map<String, serde_json::Value>,
 }