Limitations of KuzuDB with CGC when using it with claude code #727

- Dead code analysis fails — KuzuDB type error ("Trying to create a vector with ANY type"), so we couldn't identify unused functions
- Inheritance edges not indexed — cgc analyze tree returns empty for all classes, meaning we can't trace the 11-class BaseChainedDialogueCoordinator inheritance hierarchy via CGC
- Module-level imports incomplete — some query patterns fail

       - Dead code analysis fails — KuzuDB type error ("Trying to create a vector with ANY type"), so we couldn't identify unused functions
       - Inheritance edges not indexed — cgc analyze tree returns empty for all classes, meaning we can't trace the 11-class BaseChainedDialogueCoordinator inheritance hierarchy via CGC
       - Module-level imports incomplete — some query patterns fail

CGC KuzuDB Limitations — Detailed Breakdown

1. Dead Code Analysis Failure

When running cgc analyze dead-code, KuzuDB throws: "Trying to create a vector with ANY type". This is a KuzuDB engine bug, not a CGC logic bug. The dead code query in CGC's code_finder.py works like this:

MATCH (func:Function)
WHERE func.is_dependency = false
  AND NOT func.name IN ['main', 'setup', 'run']
  AND NOT (func.name STARTS WITH '__' AND func.name ENDS WITH '__')
WITH func
OPTIONAL MATCH (caller:Function)-[:CALLS]->(func)
WHERE caller.is_dependency = false
WITH func, count(caller) as caller_count
WHERE caller_count = 0
RETURN func.name, func.path, func.line_number

The OPTIONAL MATCH + count() + WITH chaining triggers a KuzuDB type resolution issue where it can't determine the vector type for the intermediate aggregation. This works fine on Neo4j and FalkorDB but breaks specifically on KuzuDB's Cypher dialect. We're using KuzuDB because it's zero-config (embedded, no server needed) and the only backend that works on our 15GB RAM WSL2 environment without running a  separate database server.

Impact: We can't automatically identify the potentially thousands of unused functions across FFTT's 12,648 functions. This would be valuable for the projection layer — dead code shouldn't become Features/Functionalities in the mapping.

Workaround: We could write our own dead code detection using the data we can query. We successfully loaded 31,705 CALLS edges into the CGCGraph. A simple Python function could find functions with zero incoming call edges by iterating graph.function_calls — essentially reimplementing the Cypher query in Python against our in-memory graph.

2. Inheritance Edges Not Indexed

When running cgc analyze tree BaseChainedDialogueCoordinator, it returns "No parent classes found" and "No child classes found" despite FFTT having a clear 11-class inheritance hierarchy:

BaseChainedDialogueCoordinator
  ├── PhaseOneChainedDialogueCoordinator
  ├── PhaseTwoAChainedDialogueCoordinator
  ├── PhaseTwoBChainedDialogueCoordinator
  ├── ... (8 more subclasses)

The CGC graph schema defines INHERITS relationships (FROM Class TO Class), and the Python parser in CGC does have tree-sitter queries for inheritance. However, KuzuDB's indexer appears to not be creating the INHERITS edges during the indexing phase. The class hierarchy query:

MATCH (child:Class)-[:INHERITS]->(parent:Class)
WHERE parent.name = 'BaseChainedDialogueCoordinator'
RETURN child.name

...returns zero rows. But we verified that the Class nodes themselves ARE indexed (1,870 classes found), and methods ARE linked via CONTAINS. Just the INHERITS relationship edges are missing.

Impact for projection: Without inheritance data, the projection engine can't:
- Group related subclasses under a common parent Feature
- Understand polymorphic dispatch patterns (20 execute implementations across the hierarchy)
- Make smarter promotion decisions (a base class with 11 subclasses is architecturally more important than an isolated class)

Currently, each subclass is independently evaluated for promotion based on its own method count/complexity, which works but loses the hierarchical relationship.

Workaround: We could supplement with AST-based inheritance detection — parse class Foo(Bar): patterns directly from Python files using Python's ast module. FFTT's existing test infrastructure already does AST analysis in tests/wiring/.

3. Module-Level Imports Incomplete

Several CGC query methods that involve IMPORTS relationships fail:

- find_module_dependencies() → KuzuDB binder error
- who_imports_module() → alias resolution error

The IMPORTS edges (File → Module) ARE partially indexed — we successfully queried 7,926 import edges via raw Cypher, and our file_imports dict in CGCGraph is populated. But CGC's higher-level query wrappers that try to do things like:

MATCH (f:File)-[imp:IMPORTS]->(m:Module)
WHERE m.name = 'some_module'
RETURN f.path, imp.alias, imp.imported_name

...fail because KuzuDB handles the imp.alias property access differently than Neo4j. The Module node represents an import target (like ABC, logging, phase_one.orchestrator), not a file — so resolving "which component does this import come from?" requires heuristic matching of module names against file paths, which is what our DependencySeeder._resolve_module_to_component() does.

Impact: Our dependency seeding works (we found 36 cross-component dependency edges) but it's based on heuristic path matching rather than precise import resolution. Some dependencies might be missed or incorrectly attributed, particularly for re-exported symbols or relative imports.

Bottom Line

These are all KuzuDB backend limitations, not fundamental CGC design issues. If we switched to Neo4j (which requires running a separate server), all three would likely work. The tradeoffs we made — using  KuzuDB for zero-config embedded operation — come with these Cypher dialect gaps. Our workarounds (in-memory graph traversal, heuristic module resolution) cover the critical paths, but dead code detection  and inheritance-aware projection remain as future improvements.