GIA/artifacts/plans/01-canonical-conversation-events.md

Feature Plan: Canonical Conversation Events (Append-Only Timeline)

Goal

Introduce a canonical append-only event log for conversations so adapters remain stateless and replay/debugging become deterministic.

Why This Fits GIA

• GIA already has Person, PersonIdentifier, ChatSession, Message and multi-transport routing.
• This adds a durable event backbone without replacing current UI/features.

Scope

• Add ConversationEvent model (append-only).
• Event types: message_created, message_edited, message_deleted, reaction_added, reaction_removed, read_receipt, media_attached, participant_added, participant_removed.
• Persist source metadata: transport, upstream IDs, timestamps, actor, payload.
• Write events from transport ingress and internal compose actions.
• Build replay utility for one chat/session.

Implementation

1. Add model + migration + indexes (session, event_type, created_at, origin_transport+origin_message_id).
2. Add write helper in a new module (core/events/ledger.py).
3. Update signal/whatsapp/xmpp ingress handlers to emit canonical events.
4. Update compose send/reaction/edit/delete paths to emit canonical events.
5. Add admin/diagnostic read view for event stream by session.
6. Add replay command to regenerate derived projections.

Acceptance Criteria

• Every new message/reaction/edit/delete creates exactly one canonical event.
• Event ordering is deterministic per session.
• Replay reproduces message projection for a selected session.
• No adapter requires business logic to infer missing event state.

Risks

• Double-write races during transition.
• Backfill complexity for old messages.

Out of Scope

• Full migration of all legacy records in one release.