background pitfalls

Pitfalls

The riskiest changes are the ones that alter fact shape, graph resolution, or public JSON output. These areas feed most agent workflows.

Parser facts affect many systems

Changing src/lode/indexer.py can affect storage rows, FTS search, context packs, graph resolution, embedding queueing, and Kuzu projection. Add tests in both tests/test_lode.py and tests/test_graph.py when parser facts change.

Resolved edges are rebuilt

resolve_graph() in src/lode/graph.py deletes and rebuilds edges with resolved confidence. If a new edge kind should persist across resolution, make sure it is emitted with the right confidence and owner path.

External placeholders can be noisy

src/lode/indexer.py creates ExternalSymbol placeholders when local resolution is not yet known. src/lode/graph.py filters shadowed external placeholders in impact output so local definitions stay visible.

Daemon docs must stay synced

Endpoint changes in src/lode/daemon.py need matching updates to openapi/loded.openapi.yml and generated docs/api/loded.md. CI runs scripts/generate_openapi_docs.py --check.

Related pages

• Testing
• Graph and impact
• Daemon endpoints