ed/manual_slop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(conductor): Complete Controller State Mutation Matrix track

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-05-07 23:11:26 -04:00
parent 1b5f51a17b
commit ba1d5c76c0
4 changed files with 80 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks.md
+1 -1
View File
@@ -14,7 +14,7 @@ This file tracks all major tracks for the project. Each track has its own detail
*Link: [./tracks/ai_interaction_call_graph_20260507/](./tracks/ai_interaction_call_graph_20260507/)* *Link: [./tracks/ai_interaction_call_graph_20260507/](./tracks/ai_interaction_call_graph_20260507/)*
*Goal: Automated and manual derivation of all major code paths and pipelines in the system.* *Goal: Automated and manual derivation of all major code paths and pipelines in the system.*
2. [ ] **Track: Controller State Mutation Matrix** 2. [x] **Track: Controller State Mutation Matrix**
*Link: [./tracks/controller_state_mutation_matrix_20260507/](./tracks/controller_state_mutation_matrix_20260507/)* *Link: [./tracks/controller_state_mutation_matrix_20260507/](./tracks/controller_state_mutation_matrix_20260507/)*
*Goal: Comprehensive map of all methods that modify the `AppController` and `App` state.* *Goal: Comprehensive map of all methods that modify the `AppController` and `App` state.*
conductor/tracks/controller_state_mutation_matrix_20260507/MUTATION_MATRIX.md
+38
View File
@@ -0,0 +1,38 @@
# 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.
conductor/tracks/controller_state_mutation_matrix_20260507/STATE_INVENTORY.md
+36
View File
@@ -0,0 +1,36 @@
# State Inventory: App & AppController
This document lists all identified state fields and threading locks within the core Manual Slop classes.
## 1. Threading Locks (AppController)
| Lock Name | Purpose | Usage Pattern |
| :--- | :--- | :--- |
| `_send_thread_lock` | Protects AI request thread spawning | Prevents multiple concurrent sends in some contexts. |
| `_disc_entries_lock` | Protects discussion history | Guards `disc_entries` during AI responses and user input. |
| `_pending_comms_lock` | Protects communication logs | Guards `_comms_log` and `_pending_comms`. |
| `_pending_tool_calls_lock` | Protects tool execution state | Guards `_pending_tool_calls` and `_tool_log`. |
| `_pending_history_adds_lock` | Protects deferred history updates | Guards `_pending_history_adds`. |
| `_pending_gui_tasks_lock` | Primary Background-to-Foreground gate | Guards `_pending_gui_tasks`. Extremely high frequency. |
| `_pending_dialog_lock` | Protects modal state (HITL) | Guards `_pending_dialog` and `_pending_actions`. |
| `_api_event_queue_lock` | Guards the FastAPI event bus | Protects `_api_event_queue` for external clients. |
## 2. Core State Fields
### 2.1 AppController (Master State)
- **Active Context:** `config`, `project`, `active_project_path`, `project_paths`.
- **Discussion:** `active_discussion`, `disc_entries`, `disc_roles`.
- **Resources:** `files`, `screenshots`.
- **Async Infra:** `event_queue`, `_loop_thread`.
- **MMA / Conductor:** `tracks`, `active_track`, `engines`, `mma_streams`, `_worker_status`, `mma_status`.
- **Metrics/Logs:** `_tool_log`, `_tool_stats`, `_token_history`, `session_usage`, `mma_tier_usage`.
- **HITL/Modals:** `_pending_dialog`, `_pending_gui_tasks`, `_pending_mma_approvals`.
- **AI Settings:** `_current_provider`, `_current_model`, `temperature`, `top_p`, `max_tokens`.
- **Status:** `ai_status`, `rag_status`.
### 2.2 App (UI-Specific & Delegated)
- **Delegated to Controller:** `ai_status`, `mma_status`, `ui_ai_input`, `disc_entries`, etc. (See `__getattr__` logic).
- **Undo/Redo:** `history` (HistoryManager), `_last_ui_snapshot`.
- **Layout/UI State:** `show_windows`, `show_preset_manager_window`, `ui_multi_viewport`, `shader_uniforms`.
- **Performance:** `perf_history`, `_token_stats`.
- **Theme FX:** `_nerv_crt`, `_nerv_alert`, `_nerv_flicker`.
conductor/tracks/controller_state_mutation_matrix_20260507/plan.md
+5 -5
View File
@@ -1,10 +1,10 @@
# Implementation Plan: Controller State Mutation Matrix (controller_state_mutation_matrix_20260507) # Implementation Plan: Controller State Mutation Matrix (controller_state_mutation_matrix_20260507)
## Phase 1: State Inventory ## Phase 1: State Inventory
- [ ] Task: List all public and private properties in `AppController` and `App`. - [x] Task: List all public and private properties in `AppController` and `App`.
- [ ] Task: Identify all threading locks and their current usage patterns. - [x] Task: Identify all threading locks and their current usage patterns.
## Phase 2: Mutation Mapping ## Phase 2: Mutation Mapping
- [ ] Task: Use grep/AST tools to find all assignments to identified state fields. - [x] Task: Use grep/AST tools to find all assignments to identified state fields.
- [ ] Task: Populate the mutation matrix table. - [x] Task: Populate the mutation matrix table.
- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md) - [x] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md)