Private
Public Access
0
0

docs: fix 3 more unverified claims (4-thread->8, 12 locks->11, _search_mcp real)

Re-audit after reading the actual full file contents:

1. guide_app_controller.md (the __init__ walkthrough):
   - '4-thread ThreadPoolExecutor' -> '8-thread' per IO_POOL_MAX_WORKERS = 8
     in src/io_pool.py:20 (bumped from 4 in commit 4a338486; the io_pool.py
     module docstring is also stale and says '4 worker threads' - flagged
     for a separate fix).
   - '12 locks' -> '11 locks + 5 non-lock state fields' (re-counted the
     threading.Lock() and the _rag_sync_*/_project_switch_* fields).

2. guide_app_controller.md (the closing line):
   - '12 locks' -> removed; explained the 434-line __init__ body
     composition (locks + state fields + settable_fields + gui_task_handlers).

3. guide_rag.md (Future Work section):
   - 'The _search_mcp method is a placeholder for this' -> WRONG.
     _search_mcp (src/rag_engine.py:322) IS a real implementation that
     calls mcp_client.async_dispatch when vector_store.provider == 'mcp'.
     Rewrote the future-work item to describe the actual mechanism.

4. docs/reports/docs_sync_test_era_20260610.md (the closing report):
   - Same 4-thread->8 and 12-locks->11 corrections propagated.

The structural facts (WorkspaceProfile/RAGConfig/VectorStoreConfig field
lists, method existence, _init_actions/_load_active_project line
numbers, _LiveGuiHandle existence, etc.) were all correct. The
counting/threading-pool claims I cited from memory were the ones
that needed re-verification.
This commit is contained in:
2026-06-10 20:49:20 -04:00
parent 994ded3598
commit bb1aa3e03c
3 changed files with 7 additions and 7 deletions
+5 -5
View File
@@ -60,13 +60,13 @@ When `--enable-test-hooks` is passed, the controller also spins up the HookServe
Initializes the controller. Real state created here:
The actual `__init__` (`src/app_controller.py:778-836`) does the following:
The actual `__init__` (`src/app_controller.py:778-1212`) does the following:
1. **Startup timeline anchors** — Captures `_init_start_ts` for the `startup_timeline()` diagnostics. Other timeline anchors are filled in lazily as events occur.
2. **Locks** — Creates 12 thread-safety locks (`_send_thread_lock`, `_disc_entries_lock`, `_pending_*_lock` for comms/tool_calls/history/gui_tasks/dialog/api_event_queue, `_rag_engine_lock`, `_rag_sync_lock`/`_rag_sync_token`/`_rag_sync_dirty` for FR3 coalescing, `_project_switch_lock`/`_project_switch_in_progress`/`_project_switch_pending_path`/`_project_switch_error`).
2. **Locks** — Creates **11** thread-safety locks (`_send_thread_lock`, `_disc_entries_lock`, `_pending_*_lock` for comms/tool_calls/history/gui_tasks/dialog/api_event_queue, `_rag_engine_lock`, `_rag_sync_lock`, `_project_switch_lock`) plus 5 non-lock state fields for the RAG-sync coalescing and project-switch state machine (`_rag_sync_token`/`_rag_sync_dirty`, `_project_switch_in_progress`/`_pending_path`/`_error`).
3. **GUI health state**`_gui_degraded_reason` and `_last_imgui_assert` (set when `immapp.run` raises `RuntimeError`; see [guide_gui_2.md](guide_gui_2.md#startup-architecture-lazy-imports-profiler-refresh-rate)).
4. **Shared io_pool**`make_io_pool()` creates a 4-thread `ThreadPoolExecutor` named `controller-io-N`. This is the SOLE background pool for all async work (no `threading.Thread()` calls anywhere else in `src/`).
5. **Warmup manager**`WarmupManager(self._io_pool, log_to_stderr=log_to_stderr)` with an on-complete callback to stamp `warmup_done_ts`. `defer_warmup=True` defers the actual `start_warmup()` call until the first frame is painted (the desktop GUI pattern; headless mode starts immediately).
4. **Shared io_pool**`make_io_pool()` creates an **8-thread** `ThreadPoolExecutor` named `controller-io-N` (per `IO_POOL_MAX_WORKERS = 8` in `src/io_pool.py:20`; the io_pool.py module docstring still says "4 worker threads" — that string is stale from a 2026-06-06 4→8 bump and should be fixed separately). This is the SOLE background pool for all async work (no `threading.Thread()` calls anywhere else in `src/`).
5. **Warmup manager**`WarmupManager(self._io_pool, log_to_stderr=log_to_stderr)` with an on-complete callback to stamp `warmup_done_ts`. `defer_warmup=True` defers the actual `start_warmup()` call until the first frame is painted (the desktop GUI pattern; headless mode starts immediately). The `log_to_stderr` parameter honors `SLOP_WARMUP_DEBUG` env var.
6. **Various flags**`_warmup_started`, `_pending_fetch_provider`, `_defer_warmup`.
**Manager objects** (`preset_manager`, `persona_manager`, `context_preset_manager`, `tool_preset_manager`, `tool_bias_engine`, `history_manager`, `workspace_manager`, `rag_engine`) are **NOT created in `__init__`**. They are lazy attributes accessed via `__getattr__` and created on first reference (typically from `_load_active_project` at `src/app_controller.py:2150` or from `App._post_init` at `src/gui_2.py:492`).
@@ -76,7 +76,7 @@ The actual `__init__` (`src/app_controller.py:778-836`) does the following:
2. `src/api_hooks.py:HookHandler.do_GET` / `do_POST` reads from these registries to expose App methods as `/api/gui` `custom_callback` actions.
3. The `sloppy.py` CLI parses `--enable-test-hooks` and passes it to `HookServer` (a separate class, not the controller).
For the actual init flow, read `src/app_controller.py:778-1212` (`__init__`; the long range is mostly `_post_init`-style wiring for the 12 locks, GUI health state, io_pool, warmup manager, and lazy manager defs), `:1606` (`_init_actions`), `:1740` (`init_state`), and `:2150` (`_load_active_project`).
For the actual init flow, read `src/app_controller.py:778-1212` (`__init__`; the 434-line body is locks + io_pool + warmup manager + ~150 lines of internal/Core/UI/Service state initialization, then the `_settable_fields` map (~75 entries) and `_gui_task_handlers` map (~25 hook actions) at the tail), `:1606` (`_init_actions`), `:1740` (`init_state`), and `:2150` (`_load_active_project`).
This is the **only** bridge between the GUI's app methods and the external Hook API. If a method is not in `_predefined_callbacks`, external callers cannot invoke it.