DL-14: Manage Relationships & State Tags

[spuentesp]

Category: data-layer | Epic: 0 | Priority: medium

Summary

Implement CRUD operations for relationships between entities and state tag
management. Relationships include membership, ownership, social, spatial,
and participation types. State tags track dynamic entity status (alive, dead,
wounded, hidden, etc.).

Acceptance Criteria

• neo4j_create_relationship creates typed edge between entities
• neo4j_create_relationship validates both entity IDs exist
• neo4j_create_relationship supports all rel_type values
• neo4j_create_relationship stores properties on edge
• neo4j_get_relationship returns relationship with entities
• neo4j_list_relationships supports filtering by entity_id, rel_type
• neo4j_update_relationship allows updating properties
• neo4j_delete_relationship removes edge
• neo4j_update_state_tags adds/removes tags atomically
• neo4j_update_state_tags validates entity is an instance (not archetype)
• All operations enforce CanonKeeper authority for writes
• Unit tests achieve >= 80% coverage

Dependencies

This use case depends on:

• DL-2

Blocks

This use case blocks:

• Q-6
• M-14

Implementation

Layer: 1

Files to create:

• packages/data-layer/src/monitor_data/schemas/relationships.py
• packages/data-layer/tests/test_tools/test_relationship_tools.py
  Files to modify:
• packages/data-layer/src/monitor_data/tools/neo4j_tools.py
• packages/data-layer/src/monitor_data/middleware/auth.py

NEO4J Operations:

• neo4j_create_relationship (authority: CanonKeeper)
• neo4j_get_relationship (authority: *)
• neo4j_list_relationships (authority: *)
• neo4j_update_relationship (authority: CanonKeeper)
• neo4j_delete_relationship (authority: CanonKeeper)
• neo4j_update_state_tags (authority: CanonKeeper)
• neo4j_get_state_tags (authority: *)

Notes:

• Relationships are edges, not nodes
• State tags only on EntityInstance, not EntityArchetype
• Consider temporal properties (valid_from, valid_to)
• Common patterns: faction membership, location containment

Testing Requirements

Minimum coverage: 80%

Unit tests:

• test_create_relationship_success: valid params → edge created
• test_create_relationship_types: each rel_type works
• test_list_relationships_by_entity: entity filter works
• test_list_relationships_by_type: rel_type filter works
• test_list_relationships_direction: direction filter works
• ... and 5 more

Integration tests:

• test_relationship_lifecycle: create → update → delete
• test_state_tag_lifecycle: add tags → verify → remove tags

References

Documentation:

• docs/ontology/ONTOLOGY.md#24-entities
• docs/ontology/ENTITY_TAXONOMY.md
  Code:
• packages/data-layer/src/monitor_data/db/neo4j.py
• packages/data-layer/src/monitor_data/schemas/entities.py

---

Generated from /home/sebas/monitor2/docs/use-cases/data-layer/DL-14.yml