DL-6: Manage Story Outlines & Plot Threads

[spuentesp]

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

Summary

Implement CRUD operations for story_outline documents (MongoDB) and PlotThread
nodes (Neo4j). Story outlines contain narrative beats and planning. Plot threads
are canonical tracking of narrative arcs that advance through scenes and link
to facts/events.

Acceptance Criteria

• mongodb_create_story_outline creates outline document linked to story
• mongodb_create_story_outline validates story_id exists
• mongodb_get_story_outline returns outline with all beats
• mongodb_update_story_outline allows updating beats and status
• neo4j_create_plot_thread creates PlotThread node linked to story
• neo4j_create_plot_thread supports thread_type enum (main, subplot, character_arc)
• neo4j_list_plot_threads supports filtering by story_id, status
• neo4j_update_plot_thread allows status transitions
• neo4j_advance_plot_thread creates ADVANCED_BY edge to scene
• neo4j_link_plot_to_fact creates relationship between thread and fact/event
• All operations enforce CanonKeeper authority for writes
• Unit tests achieve >= 80% coverage

Dependencies

This use case depends on:

• DL-3
• DL-4

Blocks

This use case blocks:

• P-6
• CF-4

Implementation

Layer: 1

Files to create:

• packages/data-layer/src/monitor_data/schemas/outlines.py
• packages/data-layer/src/monitor_data/schemas/plot_threads.py
• packages/data-layer/tests/test_tools/test_outline_tools.py
• packages/data-layer/tests/test_tools/test_plot_thread_tools.py
  Files to modify:
• packages/data-layer/src/monitor_data/tools/neo4j_tools.py
• packages/data-layer/src/monitor_data/tools/mongodb_tools.py
• packages/data-layer/src/monitor_data/middleware/auth.py

MONGODB Operations:

• mongodb_create_story_outline (authority: CanonKeeper, Narrator)
• mongodb_get_story_outline (authority: *)
• mongodb_update_story_outline (authority: CanonKeeper, Narrator)

NEO4J Operations:

• neo4j_create_plot_thread (authority: CanonKeeper)
• neo4j_list_plot_threads (authority: *)
• neo4j_update_plot_thread (authority: CanonKeeper)
• neo4j_advance_plot_thread (authority: CanonKeeper)
• neo4j_link_plot_to_fact (authority: CanonKeeper)

Notes:

• Beats in outline are ordered list with status tracking
• Plot threads track canonical narrative arc progression
• ADVANCED_BY edges create scene-to-thread links
• Consider linking to Facts/Events for provenance

Testing Requirements

Minimum coverage: 80%

Unit tests:

• test_create_outline_success: valid params → outline doc
• test_update_outline_beats: modify beats list
• test_create_plot_thread: valid params → PlotThread node
• test_advance_plot_thread: creates ADVANCED_BY edge
• test_link_plot_to_fact: creates relationship edge
• ... and 2 more

Integration tests:

• test_outline_lifecycle: create → update beats → complete
• test_plot_thread_progression: create → advance through scenes → resolve

References

Documentation:

• docs/ontology/ONTOLOGY.md#26-narrative-structures
  Code:
• packages/data-layer/src/monitor_data/db/neo4j.py
• packages/data-layer/src/monitor_data/db/mongodb.py

---

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