manual_slop/docs/MUTATION_MATRIX_PHASE5.md

Controller State Mutation Matrix

This document maps application methods to the state fields they modify and the locks that protect those mutations.

1. Mutation Matrix Table

Method Name	Class	State Field(s) Modified	Lock(s) Used	Thread Context
_process_event_queue	AppController	ai_status, mma_status	_pending_gui_tasks_lock	Event Thread
_handle_request_event	AppController	ai_status	_pending_gui_tasks_lock	AI Worker Thread
_set_status	AppController	ai_status	_pending_gui_tasks_lock	Any (Helper)
_set_mma_status	AppController	mma_status	_pending_gui_tasks_lock	Any (Helper)
_send_anthropic/gemini	ai_client	history (via callback)	_anthropic/deepseek/minimax_history_lock, _send_lock	AI Worker Thread
init_state	AppController	disc_entries	_disc_entries_lock	Main Thread (Init)
switch_discussion	AppController	active_discussion, disc_entries	_disc_entries_lock	Main/Event Thread
_process_pending_gui_tasks	App	disc_entries, ai_status, mma_status	_pending_gui_tasks_lock, _disc_entries_lock	Render Thread
_take_snapshot	App	_last_ui_snapshot	None (Single threaded UI)	Render Thread
_handle_history_logic	App	history (HistoryManager)	None (Single threaded UI)	Render Thread
_rebuild_rag_index	AppController	rag_status	_pending_gui_tasks_lock	RAG Worker Thread
_queue_put (FastAPI)	AppController	_api_event_queue	_api_event_queue_lock	FastAPI Thread

2. Lock Ownership Audit

2.1 The Foreground/Background Gate

The _pending_gui_tasks_lock is the most critical synchronization point. Background threads (AI, MMA, RAG) use this to queue state updates. The Render thread (Pipeline 2.3) drains this queue every frame.

• Risk: High lock contention if background threads queue too frequently (e.g., streaming status).

2.2 Global SDK Serializer

_send_lock in ai_client.py serializes all AI requests across the entire application, regardless of provider.

• Finding: This is a major bottleneck if multi-agent concurrency is desired, as it prevents parallel SDK calls.

2.3 History Data Integrity

_disc_entries_lock ensures that the UI doesn't render a partially-updated history list while a background thread is appending a new AI response.

3. State Lifecycle & Flushing

• Memory vs. Disk: State is held in memory (AppController attributes).
• Flushing: _last_autosave tracks the 60s interval. _process_event_queue (Event Thread) triggers the disk flush to history.toml or manual_slop.toml.
• Finding: The UI Thread (_handle_history_logic) also performs snapshots for Undo/Redo, creating a dual-layer state persistence model.