DL-2: Manage Archetypes & Instances

[spuentesp]

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

Summary

Implement CRUD operations for EntityArchetype and EntityInstance nodes in Neo4j.
Archetypes are templates (e.g., "Wizard", "Orc"), Instances are specific entities
(e.g., "Gandalf", "Thrall"). Supports state_tags for dynamic status tracking
and DERIVES_FROM relationships between instances and archetypes.

Acceptance Criteria

• neo4j_create_entity creates EntityArchetype or EntityInstance based on type
• neo4j_create_entity validates universe_id exists
• neo4j_create_entity supports all entity_type values (character, faction, location, object, concept, organization)
• neo4j_create_entity links instance to archetype via DERIVES_FROM when archetype_id provided
• neo4j_get_entity returns full entity with relationships and state_tags
• neo4j_update_entity allows updating mutable fields and state_tags
• neo4j_list_entities supports filtering by universe_id, entity_type, state_tags
• neo4j_list_entities supports pagination and sorting
• neo4j_delete_entity prevents deletion if entity has dependent facts/events
• neo4j_set_state_tags adds/removes state tags atomically
• All operations enforce CanonKeeper authority for writes
• Unit tests achieve >= 80% coverage

Dependencies

This use case depends on:

• DL-1

Blocks

This use case blocks:

• DL-3
• DL-7
• DL-14
• M-12
• M-13

Implementation

Layer: 1

Files to create:

• packages/data-layer/src/monitor_data/schemas/entities.py
• packages/data-layer/tests/test_tools/test_entity_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_entity (authority: CanonKeeper)
• neo4j_get_entity (authority: *)
• neo4j_list_entities (authority: *)
• neo4j_update_entity (authority: CanonKeeper)
• neo4j_delete_entity (authority: CanonKeeper)
• neo4j_set_state_tags (authority: CanonKeeper)

Notes:

• EntityArchetype vs EntityInstance is distinguished by is_archetype boolean
• Properties map structure varies by entity_type (see ENTITY_TAXONOMY.md)
• Common state_tags: alive, dead, hostile, friendly, wounded, hidden

Testing Requirements

Minimum coverage: 80%

Unit tests:

• test_create_archetype: is_archetype=true → EntityArchetype node
• test_create_instance: is_archetype=false → EntityInstance node
• test_create_instance_with_archetype: archetype_id → DERIVES_FROM edge
• test_create_entity_all_types: each entity_type works
• test_list_entities_by_type: filter by entity_type
• ... and 4 more

Integration tests:

• test_entity_lifecycle: create archetype → create instance → update → delete
• test_entity_hierarchy: archetype with multiple instances

References

Documentation:

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

---

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