Implement DL-14: Relationship CRUD and state tag operations for Neo4j entities

[Copilot]

Adds typed relationship management between entities and atomic state tag operations for entity instances.

Changes

Schemas (relationships.py)

• 7 relationship types: MEMBER_OF, OWNS, ALLY_OF, ENEMY_OF, LOCATED_IN, PARTICIPATED_IN, DERIVES_FROM
• Validation: prevents self-relationships, requires distinct entity IDs
• Filter support: entity_id, rel_type, direction (outgoing/incoming/both)

Neo4j Operations (neo4j_tools.py)

• neo4j_create_relationship: Creates typed edge, validates both entities exist
• neo4j_get_relationship: Returns relationship by Neo4j internal ID
• neo4j_list_relationships: Filters by entity, type, direction with pagination
• neo4j_update_relationship: Updates properties only (from/to/type immutable)
• neo4j_delete_relationship: Removes edge
• neo4j_update_state_tags: Alias for neo4j_set_state_tags (API consistency)
• neo4j_get_state_tags: Returns tags without full entity data

Authority (auth.py)

• Write operations: CanonKeeper only
• Read operations: All agents

Tests (test_relationship_tools.py)

• 30 tests covering all rel_types, validation, filtering, lifecycle
• All 111 data-layer tests pass

Usage

from monitor_data.tools.neo4j_tools import neo4j_create_relationship, neo4j_list_relationships
from monitor_data.schemas.relationships import RelationshipCreate, RelationshipType, RelationshipFilter

# Create relationship
rel = neo4j_create_relationship(RelationshipCreate(
    from_entity_id=gandalf_id,
    to_entity_id=fellowship_id,
    rel_type=RelationshipType.MEMBER_OF,
    properties={"role": "leader", "joined": "3018-10-25"}
))

# Query with filters
rels = neo4j_list_relationships(RelationshipFilter(
    entity_id=gandalf_id,
    direction="outgoing",
    rel_type=RelationshipType.MEMBER_OF
))

Implementation Notes

• Uses Neo4j internal IDs for relationships (integers, not UUIDs)
• Direction filter enables efficient graph traversal queries
• Entity names included in responses to reduce subsequent lookups
• State tags remain instance-only; archetypes return validation error

Original prompt

---

This section details on the original issue you should resolve

<issue_title>DL-14: Manage Relationships & State Tags</issue_title>
<issue_description>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</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes DL-14: Manage Relationships & State Tags #36

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

\nTests not detected in this PR. Please add/confirm coverage where applicable.

[spuentesp]

Closing stale draft PR - conflicts with current master. Will regenerate from current state when ready to implement.