# Manual Slop: Architectural Technical Reference

A deep-dive into the asynchronous orchestration, state synchronization, and the "Linear Execution Clutch" of the Manual Slop engine. This document is designed to move the reader from a high-level mental model to a low-level implementation understanding.

---

## 1. Philosophy: The Decoupled State Machine

Manual Slop is built on a single, core realization: **AI reasoning is high-latency and non-deterministic, while GUI interaction must be low-latency and responsive.** 

To solve this, the engine enforces a strict decoupling between three distinct boundaries:

*   **The GUI Boundary (Main Thread):** A retained-mode loop (ImGui) that must never block. It handles visual telemetry and user "Seal of Approval" actions.
*   **The AI Boundary (Daemon Threads):** Stateless execution loops that handle the "heavy lifting" of context aggregation, LLM communication, and tool reasoning.
*   **The Orchestration Boundary (Asyncio):** A background thread that manages the flow of data between the other two, ensuring thread-safe communication without blocking the UI.

---

## 2. System Lifetime & Initialization

The application lifecycle, managed by `App` in `gui_2.py`, follows a precise sequence to ensure the environment is ready before the first frame:

1.  **Context Hydration:** The engine reads `config.toml` (global) and `<project>.toml` (local). This builds the initial "world view" of the project—what files are tracked, what the discussion history is, and which AI models are active.
2.  **Thread Bootstrapping:**
    *   The `Asyncio` event loop thread is started (`_loop_thread`).
    *   The `HookServer` (FastAPI) is started as a daemon to handle IPC.
3.  **UI Entry:** The main thread enters `immapp.run()`. At this point, the GUI is "alive," and the background threads are ready to receive tasks.
4.  **The Dual-Flush Shutdown:** On exit, the system commits state back to both project and global configs. This ensures that your window positions, active discussions, and even pending tool results are preserved for the next session.

---

## 3. The Task Pipeline: Producer-Consumer Synchronization

Because ImGui state cannot be safely modified from a background thread, Manual Slop uses a **Producer-Consumer** model for all updates.

### The Flow of an AI Request
1.  **Produce:** When you click "Gen + Send," the GUI thread produces a `UserRequestEvent` and pushes it into the `AsyncEventQueue`.
2.  **Consume:** The background `asyncio` loop pops this event and dispatches it to the `ai_client`. The GUI thread remains free to render and respond to other inputs.
3.  **Task Backlog:** When the AI responds, the background thread *cannot* update the UI text boxes directly. Instead, it appends a **Task Dictionary** to the `_pending_gui_tasks` list.
4.  **Sync:** On every frame, the GUI thread checks this list. If tasks exist, it acquires a lock, clears the list, and executes the updates (e.g., "Set AI response text," "Blink the terminal indicator").

---

## 4. The Execution Clutch: Human-In-The-Loop (HITL)

The "Execution Clutch" is our answer to the "Black Box" problem of AI. It allows you to shift from automatic execution to a manual, deterministic step-through mode.

### How the "Shifting" Works
When the AI requests a destructive action (like running a PowerShell script), the background execution thread is **suspended** using a `threading.Condition`:

1.  **The Pause:** The thread enters a `.wait()` state. It is physically blocked.
2.  **The Modal:** A task is sent to the GUI to open a modal dialog.
3.  **The Mutation:** The user can read the script, edit it, or reject it.
4.  **The Unleash:** When the user clicks "Approve," the GUI thread updates the shared state and calls `.notify_all()`. The background thread "wakes up," executes the (potentially modified) script, and reports the result back to the AI.

---

## 5. Security: The MCP Allowlist

To prevent "hallucinated" file access, every filesystem tool (read, list, search) is gated by the **MCP (Model Context Protocol) Bridge**:

*   **Resolution:** Every path requested by the AI is resolved to an absolute path.
*   **Checking:** It is verified against the project's `base_dir`. If the AI tries to `read_file("C:/Windows/System32/...")`, the bridge intercepts the call and returns an `ACCESS DENIED` error to the model before the OS is ever touched.

---

## 6. Telemetry & Auditing

Every interaction in Manual Slop is designed to be auditable:
*   **JSON-L Comms Logs:** Raw API traffic is logged for debugging and token cost analysis.
*   **Generated Scripts:** Every script that passes through the "Clutch" is saved to `scripts/generated/`.
*   **Performance Monitor:** Real-time metrics (FPS, Frame Time, Input Lag) are tracked and can be queried via the Hook API to ensure the UI remains "fluid" under load.