Refine bounded traversal contracts

src/docforge/index.py

@@ -34,7 +34,7 @@ from .models import (
 )
 from .project import project_root_fingerprint
 
-INDEX_SCHEMA_VERSION = 2
+INDEX_SCHEMA_VERSION = 3
 APPLICATION_ID = 1_146_683_778
 
 
@@ -265,6 +265,8 @@ class ProjectIndex:
                         PRIMARY KEY (source_id, relation, target_id)
                     );
                     CREATE INDEX edges_target ON edges(target_id, relation, source_id);
+                    CREATE INDEX edges_target_source
+                        ON edges(target_id, source_id, relation);
                     CREATE TABLE logic_owners (
                         owner_node_id TEXT PRIMARY KEY,
                         source_id TEXT NOT NULL
@@ -838,6 +840,7 @@ class ProjectIndex:
                 count=len(results),
                 limit=bounded,
                 truncated=len(rows) > bounded,
+                truncation_reason="result_limit" if len(rows) > bounded else None,
                 results=results,
             )
 
@@ -871,6 +874,7 @@ class ProjectIndex:
                 count=len(results),
                 limit=bounded,
                 truncated=len(rows) > bounded,
+                truncation_reason="result_limit" if len(rows) > bounded else None,
                 results=results,
             )
 
@@ -942,9 +946,12 @@ class ProjectIndex:
             truncated = len(rows) > bounded
             edges = [Edge(*row).as_dict() for row in rows[:bounded]]
             return snapshot.result(
+                root=node_id,
+                relation=relation,
                 count=len(edges),
                 limit=bounded,
                 truncated=truncated,
+                truncation_reason="result_limit" if truncated else None,
                 edges=edges,
             )
 
@@ -973,13 +980,16 @@ class ProjectIndex:
             queue: deque[tuple[str, int, tuple[str, ...]]] = deque([(node_id, 0, (node_id,))])
             seen = {node_id}
             results: list[dict[str, object]] = []
-            truncated = False
-            examined_edges = 0
-            while queue and len(results) <= bounded and examined_edges < examined_limit:
+            truncation_reason: str | None = None
+            candidate_edges_consumed = 0
+            while queue and truncation_reason is None:
                 current, current_depth, path = queue.popleft()
                 if current_depth >= depth:
                     continue
-                remaining = examined_limit - examined_edges
+                remaining = examined_limit - candidate_edges_consumed
+                if remaining <= 0:
+                    truncation_reason = "edge_examination_limit"
+                    break
                 values: tuple[object, ...] = (
                     (current, relation, remaining + 1)
                     if relation is not None
@@ -990,18 +1000,18 @@ class ProjectIndex:
                     f"WHERE {source_column} = ?{relation_clause} "
                     "ORDER BY source_id, relation, target_id LIMIT ?",
                     values,
-                ).fetchall()
-                if len(candidates) > remaining:
-                    truncated = True
-                    candidates = candidates[:remaining]
-                examined_edges += len(candidates)
+                )
                 for row in candidates:
+                    if candidate_edges_consumed >= examined_limit:
+                        truncation_reason = "edge_examination_limit"
+                        break
+                    candidate_edges_consumed += 1
                     edge = Edge(*row)
                     target = edge.source_id if incoming else edge.target_id
                     if target in seen:
                         continue
                     if len(results) >= bounded:
-                        truncated = True
+                        truncation_reason = "result_limit"
                         break
                     seen.add(target)
                     target_path = (*path, target)
@@ -1014,16 +1024,15 @@ class ProjectIndex:
                         }
                     )
                     queue.append((target, current_depth + 1, target_path))
-            if queue and examined_edges >= examined_limit:
-                truncated = True
             return snapshot.result(
                 root=node_id,
                 depth=depth,
                 count=len(results),
                 limit=bounded,
-                truncated=truncated,
-                examined_edges=examined_edges,
-                examined_edges_limit=examined_limit,
+                truncated=truncation_reason is not None,
+                truncation_reason=truncation_reason,
+                candidate_edges_consumed=candidate_edges_consumed,
+                candidate_edges_limit=examined_limit,
                 results=results,
             )