Graph-lite DX: typed schema + typed query (nanograph-inspired)

[acgxv]

Summary

Improve graph/structured-memory developer experience by adding a typed schema + typed query surface for ELF's graph-lite pathway, inspired by nanograph's .pg + .gq ergonomics, without adopting an embedded graph DB or changing ELF's SoT model.

Why now

Our 2026-03-03 deep-dive refresh highlights that ELF's graph-lite direction exists, but the human/developer ergonomics are behind typed graph-first tools (nanograph).

Evidence

• README.md:132 (ELF graph-lite is present, optional relation_context)
• README.md:134 (nanograph scope isn't directly comparable; still useful for DX ideas)
• README.md:148 (nanograph signature strength: typed schema + typed query)
• docs/research/comparison_external_projects.md:479 (nanograph deep dive)

Primary upstream references

• https://github.com/aaltshuler/nanograph
• https://github.com/aaltshuler/nanograph/blob/main/docs/user/schema.md
• https://github.com/aaltshuler/nanograph/blob/main/docs/user/queries.md

Proposal (ELF)

• Define a typed graph-lite schema for entities/relations (Rust types + JSON schema) with explicit validation at ingest.
• Define a typed query surface for relation-heavy recall (start as structured JSON query / builder; only later consider a DSL).
• Provide explain/trace output for relation_context assembly (what relations, why included, any truncation).
• Keep it optional and additive: existing note search remains unchanged; this is an opt-in path.

Non-goals

• Adopting a graph database backend or embedding nanograph itself.
• Benchmark/performance claims; focus on correctness + DX + debuggability.

Acceptance (for first iteration)

• A concrete schema + validation rules documented in docs/spec and enforced in API boundary.
• A minimal query contract that can be used via HTTP + MCP without custom client code.
• Unit tests covering schema validation and a few query/explain cases.

[acgxv]

Implemented typed graph-lite query surface (nanograph-inspired):

• New public endpoint: POST /v2/graph/query (subject + optional predicate/scopes/as_of/limit/explain; read_profile via X-ELF-Read-Profile).
• New MCP tool: elf_graph_query -> POST /v2/graph/query.
• Ingest schema: structured.entities + structured.relations typed oneOf(entity|value) enforced + tests.
• Storage resolution helpers avoid predicate registration; surface->entity resolution detects ambiguity.
• Specs + version registry updated (elf.graph_query/v1) + research inventory/comparison refreshed with NanoGraph snapshot.

Commits:

• f4692ce feat(graph): code (service/storage/api/mcp)
• d04a2e4 docs: specs + research

Local gates: cargo make checks (clippy + vstyle + nextest + cargo test + fmt-check) passed; integration/acceptance tests remain ignored unless ELF_PG_DSN/ELF_QDRANT_URL are configured.

[acgxv]

Follow-up fixes after landing:

• Corrected research docs to reference the intended upstream aaltshuler/nanograph (previous commit mistakenly linked to nano-graphrag).
• Stabilized packages/elf-service/src/graph_query.rs tests after style automation (avoids std::io::Error shadowing).

Commits:

• 0925fe9 chore(packages/elf-service)
• d3a8f07 docs(docs/research)