DL-5: Manage Proposed Changes

[spuentesp]

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

Summary

Implement CRUD operations for ProposedChange documents in MongoDB. These are
staging documents for canonical changes that CanonKeeper evaluates at scene end.
Supports different change types (fact, entity, relationship, state_change, event)
and status transitions (pending → accepted/rejected).

Acceptance Criteria

• mongodb_create_proposed_change creates ProposedChange document
• mongodb_create_proposed_change validates change_type enum
• mongodb_create_proposed_change stores content payload as flexible JSON
• mongodb_create_proposed_change links to scene_id or story_id
• mongodb_get_proposed_change returns full document with evidence
• mongodb_list_proposed_changes supports filtering by status, change_type, scene_id
• mongodb_update_proposed_change allows status transitions
• mongodb_update_proposed_change validates status transitions (pending only → accepted/rejected)
• mongodb_update_proposed_change records decision metadata (decided_by, decided_at, reason)
• Accepted changes include reference to created canonical entity
• All operations track timestamps and proposer identity
• Unit tests achieve >= 80% coverage

Dependencies

This use case depends on:

• DL-4

Blocks

This use case blocks:

• P-3
• CF-3

Implementation

Layer: 1

Files to create:

• packages/data-layer/src/monitor_data/schemas/proposed_changes.py
• packages/data-layer/tests/test_tools/test_proposed_change_tools.py
  Files to modify:
• packages/data-layer/src/monitor_data/tools/mongodb_tools.py
• packages/data-layer/src/monitor_data/middleware/auth.py

MONGODB Operations:

• mongodb_create_proposed_change (authority: *)
• mongodb_get_proposed_change (authority: *)
• mongodb_list_proposed_changes (authority: *)
• mongodb_update_proposed_change (authority: CanonKeeper)

Notes:

• Any agent can propose changes (authority: *)
• Only CanonKeeper can accept/reject (update status)
• Accepted changes should include canonical_ref pointing to created node
• Consider indexing by scene_id for efficient batch retrieval

Testing Requirements

Minimum coverage: 80%

Unit tests:

• test_create_proposed_change_fact: change_type=fact → valid doc
• test_create_proposed_change_entity: change_type=entity → valid doc
• test_create_proposed_change_relationship: change_type=relationship → valid doc
• test_list_by_scene: scene_id filter returns relevant proposals
• test_list_by_status: pending filter works
• ... and 3 more

Integration tests:

• test_proposal_lifecycle: create → list → accept → verify canonical created
• test_batch_canonization: multiple proposals → batch accept/reject

References

Documentation:

• docs/ontology/ONTOLOGY.md#27-proposed-changes
• docs/architecture/AGENT_ORCHESTRATION.md
  Code:
• packages/data-layer/src/monitor_data/db/mongodb.py

---

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