DL-3: Manage Facts & Events

[spuentesp]

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

Summary

Implement CRUD operations for Fact and Event nodes in Neo4j with full provenance
tracking. Facts represent canonical truth about the world; Events are temporal
facts with timestamps. Both support SUPPORTED_BY edges to Sources/Snippets/Scenes
and INVOLVES/ABOUT edges to entities.

Acceptance Criteria

• neo4j_create_fact creates Fact node with required fields
• neo4j_create_fact validates universe_id and entity references exist
• neo4j_create_fact supports all fact_type values (state, relationship, attribute, event)
• neo4j_create_fact creates SUPPORTED_BY edges to sources/snippets/scenes
• neo4j_create_fact creates INVOLVES edges to referenced entities
• neo4j_create_event creates Event node with temporal properties (start_time, end_time)
• neo4j_create_event supports timeline ordering (NEXT, BEFORE, AFTER edges)
• neo4j_get_fact returns fact with all relationships and provenance chain
• neo4j_update_fact allows updating mutable fields and canon_level
• neo4j_list_facts supports filtering by universe_id, entity_id, fact_type, canon_level
• neo4j_delete_fact prevents deletion of confirmed facts unless force=true
• All operations enforce CanonKeeper authority for writes
• Unit tests achieve >= 80% coverage

Dependencies

This use case depends on:

• DL-1
• DL-2

Blocks

This use case blocks:

• DL-6
• DL-7
• Q-1
• Q-2

Implementation

Layer: 1

Files to create:

• packages/data-layer/src/monitor_data/schemas/facts.py
• packages/data-layer/tests/test_tools/test_fact_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_fact (authority: CanonKeeper)
• neo4j_create_event (authority: CanonKeeper)
• neo4j_get_fact (authority: *)
• neo4j_list_facts (authority: *)
• neo4j_update_fact (authority: CanonKeeper)
• neo4j_delete_fact (authority: CanonKeeper)

Notes:

• Fact vs Event: Events have explicit timestamps, Facts are timeless assertions
• SUPPORTED_BY creates provenance chain for canonization verification
• confidence is 0.0-1.0, canon_level is the authoritative status
• Timeline edges (NEXT, BEFORE, AFTER) only apply to Events

Testing Requirements

Minimum coverage: 80%

Unit tests:

• test_create_fact_success: valid params → Fact node created
• test_create_fact_with_provenance: source_ids → SUPPORTED_BY edges
• test_create_fact_with_entities: entity_ids → INVOLVES edges
• test_create_event_with_timeline: timeline params → ordering edges
• test_get_fact_with_relationships: returns full provenance chain
• ... and 4 more

Integration tests:

• test_fact_lifecycle: create with provenance → update → delete
• test_event_timeline: create events → establish ordering → query timeline

References

Documentation:

• docs/ontology/ONTOLOGY.md#25-facts-events
• docs/architecture/DATABASE_INTEGRATION.md
  Code:
• packages/data-layer/src/monitor_data/schemas/base.py

---

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