From ba1d5c76c0a2d06c300b2cd2802dc9d45e311277 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 7 May 2026 23:11:26 -0400 Subject: [PATCH] chore(conductor): Complete Controller State Mutation Matrix track --- conductor/tracks.md | 2 +- .../MUTATION_MATRIX.md | 38 +++++++++++++++++++ .../STATE_INVENTORY.md | 36 ++++++++++++++++++ .../plan.md | 10 ++--- 4 files changed, 80 insertions(+), 6 deletions(-) create mode 100644 conductor/tracks/controller_state_mutation_matrix_20260507/MUTATION_MATRIX.md create mode 100644 conductor/tracks/controller_state_mutation_matrix_20260507/STATE_INVENTORY.md diff --git a/conductor/tracks.md b/conductor/tracks.md index 980ace6..850a79a 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -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/)* *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/)* *Goal: Comprehensive map of all methods that modify the `AppController` and `App` state.* diff --git a/conductor/tracks/controller_state_mutation_matrix_20260507/MUTATION_MATRIX.md b/conductor/tracks/controller_state_mutation_matrix_20260507/MUTATION_MATRIX.md new file mode 100644 index 0000000..35a6eae --- /dev/null +++ b/conductor/tracks/controller_state_mutation_matrix_20260507/MUTATION_MATRIX.md @@ -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. diff --git a/conductor/tracks/controller_state_mutation_matrix_20260507/STATE_INVENTORY.md b/conductor/tracks/controller_state_mutation_matrix_20260507/STATE_INVENTORY.md new file mode 100644 index 0000000..e10d5e7 --- /dev/null +++ b/conductor/tracks/controller_state_mutation_matrix_20260507/STATE_INVENTORY.md @@ -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`. diff --git a/conductor/tracks/controller_state_mutation_matrix_20260507/plan.md b/conductor/tracks/controller_state_mutation_matrix_20260507/plan.md index a97c735..d999c66 100644 --- a/conductor/tracks/controller_state_mutation_matrix_20260507/plan.md +++ b/conductor/tracks/controller_state_mutation_matrix_20260507/plan.md @@ -1,10 +1,10 @@ # Implementation Plan: Controller State Mutation Matrix (controller_state_mutation_matrix_20260507) ## Phase 1: State Inventory -- [ ] Task: List all public and private properties in `AppController` and `App`. -- [ ] Task: Identify all threading locks and their current usage patterns. +- [x] Task: List all public and private properties in `AppController` and `App`. +- [x] Task: Identify all threading locks and their current usage patterns. ## Phase 2: Mutation Mapping -- [ ] Task: Use grep/AST tools to find all assignments to identified state fields. -- [ ] Task: Populate the mutation matrix table. -- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md) +- [x] Task: Use grep/AST tools to find all assignments to identified state fields. +- [x] Task: Populate the mutation matrix table. +- [x] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md)