Summary
The mentions relationship currently stores properties.root_id on the relationship edge to speed up backlinks queries. This is denormalized/cached data that can become stale and adds complexity. We should compute roots dynamically using recursive graph traversal.
Current Behavior
When creating a mention:
create_mention() computes the root of the source node via get_root_id() traversal
- Stores it as
properties.root_id on the relationship
get_mentioning_containers() reads properties.root_id to find backlink sources
Proposed Change
Phase 1: Implement dynamic root lookup
Refactor get_mentioning_containers() to compute roots dynamically:
- Get mentions where
out = target_node
- For each mention's
in (source), recursively traverse UP via has_child relationships to find the root
- Use the same recursive traversal pattern used for parent-child fetching (but going UP instead of DOWN)
- Return unique root nodes
Phase 2: Update frontend integration
Ensure the backlinks panel uses the refactored get_mentioning_containers():
- Backlinks query runs in parallel with descendant loading (not awaiting each other)
- Both update different parts of the UI independently
Phase 3: Remove properties.root_id from mention creation
- Remove
root_id parameter from create_mention() in surreal_store.rs
- Remove root_id computation and storage in
node_service.rs
- Simplify the mention relationship to just
in (source) → out (target)
Phase 4: Migration cleanup (post-release consideration)
For existing installations, optionally clean up old data:
UPDATE relationship SET properties.root_id = NONE WHERE relationship_type = 'mentions';
Or leave it - the field becomes ignored dead data (no schema change needed since properties is flexible).
Benefits
- Always accurate (reflects current hierarchy)
- Simpler data model
- No stale data if nodes move
- Cleaner
create_mention logic
- Consistent pattern with other recursive traversals
Files to Modify
packages/core/src/db/surreal_store.rs - get_mentioning_containers(), create_mention()
packages/core/src/services/node_service.rs - create_mention()
Summary
The mentions relationship currently stores
properties.root_idon the relationship edge to speed up backlinks queries. This is denormalized/cached data that can become stale and adds complexity. We should compute roots dynamically using recursive graph traversal.Current Behavior
When creating a mention:
create_mention()computes the root of the source node viaget_root_id()traversalproperties.root_idon the relationshipget_mentioning_containers()readsproperties.root_idto find backlink sourcesProposed Change
Phase 1: Implement dynamic root lookup
Refactor
get_mentioning_containers()to compute roots dynamically:out = target_nodein(source), recursively traverse UP viahas_childrelationships to find the rootPhase 2: Update frontend integration
Ensure the backlinks panel uses the refactored
get_mentioning_containers():Phase 3: Remove
properties.root_idfrom mention creationroot_idparameter fromcreate_mention()insurreal_store.rsnode_service.rsin(source) →out(target)Phase 4: Migration cleanup (post-release consideration)
For existing installations, optionally clean up old data:
Or leave it - the field becomes ignored dead data (no schema change needed since
propertiesis flexible).Benefits
create_mentionlogicFiles to Modify
packages/core/src/db/surreal_store.rs-get_mentioning_containers(),create_mention()packages/core/src/services/node_service.rs-create_mention()