loki/docs/implementation/PHASE-1-STEP-8b-NOTES.md

# Phase 1 Step 8b — Implementation Notes

## Status

Done.

## Plan reference

- Plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Section: "Step 8b: Finish Step 7's deferred mixed-method migrations"

## Summary

Migrated 7 of the 9 Step 7 deferrals to `RequestContext` / `AppConfig`
methods that take `&AppConfig` instead of `&Config`. Two methods
(`edit_role` and `update`) remain deferred because they depend on
`use_role` (Step 8d) and MCP registry manipulation (Step 8d)
respectively. Four private helper functions in `mod.rs` were bumped
to `pub(super)` to support the new `repl_complete` implementation.

## What was changed

### Files modified (3 files)

- **`src/config/request_context.rs`** — added a fifth `impl RequestContext`
  block with 7 methods:

  - `retrieve_role(&self, app: &AppConfig, name: &str) -> Result<Role>` —
    loads a role by name, resolves its model via
    `Model::retrieve_model(app, ...)`. Reads `app.temperature` and
    `app.top_p` for the no-model-id fallback branch.

  - `set_model_on_role_like(&mut self, app: &AppConfig, model_id: &str)
    -> Result<bool>` — resolves the model via `Model::retrieve_model`,
    sets it on the active role-like if present (returns `true`), or on
    `ctx.model` directly (returns `false`). The `false` case means the
    caller should also call `AppConfig::set_model_id_default` if they
    want the global default updated.

  - `reload_current_model(&mut self, app: &AppConfig, model_id: &str)
    -> Result<()>` — resolves a model by ID and assigns it to
    `ctx.model`. Used in tandem with `AppConfig::ensure_default_model_id`.

  - `use_prompt(&mut self, _app: &AppConfig, prompt: &str) -> Result<()>` —
    creates a `TEMP_ROLE_NAME` role with the prompt text, sets its model
    to `current_model()`, calls `use_role_obj`. The `_app` parameter is
    included for signature consistency; it's unused because `use_prompt`
    only reads runtime state.

  - `set_rag_reranker_model(&mut self, app: &AppConfig,
    value: Option<String>) -> Result<bool>` — validates the model ID via
    `Model::retrieve_model(app, ...)` if present, then clones-and-replaces
    the `Arc<Rag>` with the updated reranker model. Returns `true` if RAG
    was mutated, `false` if no RAG is active.

  - `set_rag_top_k(&mut self, value: usize) -> Result<bool>` — same
    clone-and-replace pattern on the active RAG. Returns `true`/`false`.

  - `repl_complete(&self, app: &AppConfig, cmd: &str, args: &[&str],
    _line: &str) -> Vec<(String, Option<String>)>` — full tab-completion
    handler. Reads `app.*` for serialized fields, `self.*` for runtime
    state, `self.app.vault` for vault completions. MCP configured-server
    completions are limited to `app.mapping_mcp_servers` keys during the
    bridge (no live `McpRegistry` on `RequestContext`; Step 8d's
    `ToolScope` will restore full MCP completions).

  Updated imports: added `TEMP_ROLE_NAME`, `list_agents`, `ModelType`,
  `list_models`, `read_to_string`, `fuzzy_filter`. Removed duplicate
  `crate::utils` import that had accumulated.

- **`src/config/app_config.rs`** — added 4 methods to the existing
  `set_*_default` impl block:

  - `set_rag_reranker_model_default(&mut self, value: Option<String>)`
  - `set_rag_top_k_default(&mut self, value: usize)`
  - `set_model_id_default(&mut self, model_id: String)`
  - `ensure_default_model_id(&mut self) -> Result<String>` — picks the
    first available chat model if `model_id` is empty, updates
    `self.model_id`, returns the resolved ID.

- **`src/config/mod.rs`** — bumped 4 private helper functions to
  `pub(super)`:

  - `parse_value` — used by `update` when it migrates (Step 8f/8g)
  - `complete_bool` — used by `repl_complete`
  - `complete_option_bool` — used by `repl_complete`
  - `map_completion_values` — used by `repl_complete`

### Files NOT changed

- **`src/client/macros.rs`**, **`src/client/model.rs`** — untouched;
  Step 8a already migrated these.
- **All other source files** — no changes. All existing `Config` methods
  stay intact.

## Key decisions

### 1. Same bridge pattern as Steps 3-8a

New methods sit alongside originals. No caller migration. `Config`'s
`retrieve_role`, `set_model`, `setup_model`, `use_prompt`,
`set_rag_reranker_model`, `set_rag_top_k`, `repl_complete` all stay
on `Config` and continue working for every current caller.

### 2. `set_model_on_role_like` returns `Result<bool>` (not just `bool`)

Unlike the Step 7 `set_temperature_on_role_like` pattern that returns
a plain `bool`, `set_model_on_role_like` returns `Result<bool>` because
`Model::retrieve_model` can fail. The `bool` still signals whether a
role-like was mutated. When `false`, the model was assigned to
`ctx.model` directly (so the caller doesn't need to fall through to
`AppConfig` — the "no role-like" case is handled in-method by assigning
to `ctx.model`). This differs from the Step 7 pattern where `false`
means "caller must call the `_default`."

### 3. `setup_model` split into two independent methods

`Config::setup_model` does three things:
1. Picks a default model ID if empty (`ensure_default_model_id`)
2. Calls `set_model` to resolve and assign the model
3. Writes back `model_id` to config

The split:
- `AppConfig::ensure_default_model_id()` handles #1 and #3
- `RequestContext::reload_current_model()` handles #2

Step 8f will compose them: first call `ensure_default_model_id` on
the app config, then call `reload_current_model` on the context
with the returned ID.

### 4. `repl_complete` MCP completions are reduced during bridge

`Config::repl_complete` reads `self.mcp_registry.list_configured_servers()`
for the `enabled_mcp_servers` completion values. `RequestContext` has no
`mcp_registry` field. During the bridge window, the new `repl_complete`
offers only `mapping_mcp_servers` keys (from `AppConfig`) as MCP
completions. Step 8d's `ToolScope` will provide full MCP server
completions.

This is acceptable because:
- The new method isn't called by anyone yet (bridge pattern)
- When Step 8d wires it up, `ToolScope` will be available

### 5. `edit_role` deferred to Step 8d

`Config::edit_role` calls `self.use_role()` as its last line.
`use_role` is a scope-transition method that Step 8d will rewrite
to use `McpFactory::acquire()`. Migrating `edit_role` without
`use_role` would require either a stub or leaving it half-broken.
Deferring it keeps the bridge clean.

### 6. `update` dispatcher deferred to Step 8f/8g

`Config::update` takes `&GlobalConfig` and has two branches that
do heavy MCP registry manipulation (`enabled_mcp_servers` and
`mcp_server_support`). These branches require Step 8d's
`McpFactory`/`ToolScope` infrastructure. The remaining branches
could be migrated individually, but splitting the dispatcher
partially creates a confusing dual-path situation. Deferring the
entire dispatcher keeps things clean.

### 7. RAG mutation uses clone-and-replace on `Arc<Rag>`

`Config::set_rag_reranker_model` uses the `update_rag` helper which
takes `&GlobalConfig`, clones the `Arc<Rag>`, mutates the clone,
and writes it back via `config.write().rag = Some(Arc::new(rag))`.

The new `RequestContext` methods do the same thing but without the
`GlobalConfig` indirection: clone `Arc<Rag>` contents, mutate,
wrap in a new `Arc`, assign to `self.rag`. Semantically identical.

## Deviations from plan

### 2 methods deferred (not in plan's "done" scope for 8b)

| Method | Why deferred |
|---|---|
| `edit_role` | Calls `use_role` which is Step 8d |
| `update` | MCP registry branches require Step 8d's `McpFactory`/`ToolScope` |

The plan's 8b description listed both as potential deferrals:
- `edit_role`: "calls editor + upsert_role + use_role — use_role is
  still Step 8d, so edit_role may stay deferred"
- `update`: "Once all the individual set_* methods exist on both types"
  — the MCP-touching set_* methods don't exist yet

### `set_model_on_role_like` handles the no-role-like case internally

The plan said the split should be:
- `RequestContext::set_model_on_role_like` → returns `bool`
- `AppConfig::set_model_default` → sets global

But `set_model` doesn't just set `model_id` when no role-like is
active — it also assigns the resolved `Model` struct to `self.model`
(runtime). Since the `Model` struct lives on `RequestContext`, the
no-role-like branch must also live on `RequestContext`. So
`set_model_on_role_like` handles both cases (role-like mutation and
`ctx.model` assignment) and returns `false` to signal that `model_id`
on `AppConfig` may also need updating. `AppConfig::set_model_id_default`
is the simpler companion.

## Verification

### Compilation

- `cargo check` — clean, zero warnings, zero errors
- `cargo clippy` — clean

### Tests

- `cargo test` — **63 passed, 0 failed** (unchanged from Steps 1–8a)

No new tests added — this is a bridge-pattern step that adds methods
alongside existing ones. The existing test suite confirms no regressions.

## Handoff to next step

### What Step 8c can rely on

Step 8c (extract `McpFactory::acquire()` from `McpRegistry::init_server`)
can rely on:

- **All Step 8a guarantees still hold** — `Model::retrieve_model`,
  `list_models`, `list_all_models`, `list_client_names` all take
  `&AppConfig`
- **`RequestContext` now has 46 inherent methods** across 5 impl blocks:
  1 constructor + 13 reads + 12 writes + 14 mixed (Step 7) + 7 mixed
  (Step 8b) = 47 total (46 public + 1 private `open_message_file`)
- **`AppConfig` now has 21 methods**: 7 reads + 4 writes + 10
  setter-defaults (6 from Step 7 + 4 from Step 8b)

### What Step 8c should watch for

Step 8c is **independent of Step 8b**. It extracts the MCP subprocess
spawn logic from `McpRegistry::init_server` into a standalone function
and implements `McpFactory::acquire()`. Step 8b provides no input to
8c.

### What Step 8d should know about Step 8b's output

Step 8d (scope transitions) depends on both 8b and 8c. From 8b it
gets:

- `RequestContext::retrieve_role(app, name)` — needed by `use_role`
- `RequestContext::set_model_on_role_like(app, model_id)` — may be
  useful inside scope transitions

### What Step 8f/8g should know about Step 8b deferrals

- **`edit_role`** — needs `use_role` from Step 8d. Once 8d ships,
  `edit_role` on `RequestContext` becomes: call `app.editor()`, call
  `upsert_role(name)`, call `self.use_role(app, name, abort_signal)`.
  The `upsert_role` method is still on `Config` and needs migrating
  (it calls `self.editor()` which is on `AppConfig`, and
  `ensure_parent_exists` which is a free function — straightforward).

- **`update` dispatcher** — needs all `set_*` branches migrated. The
  non-MCP branches are ready now. The MCP branches need Step 8d's
  `McpFactory`/`ToolScope`.

- **`use_role_safely` / `use_session_safely`** — still on `Config`.
  These wrappers exist only because `Config::use_role` is `&mut self`
  and the REPL holds `Arc<RwLock<Config>>`. Step 8g eliminates them
  when the REPL switches to holding `RequestContext` directly.

### Bridge-window duplication count at end of Step 8b

Running tally:

- `AppConfig` (Steps 3+4+7+8b): 21 methods
- `RequestContext` (Steps 5+6+7+8b): 46 methods
- `paths` module (Step 2): 33 free functions
- Step 6.5 types: 4 new types on scaffolding
- `mod.rs` visibility bumps: 4 helpers → `pub(super)`

**Total: 67 methods + 33 paths + 4 types / ~1500 lines of parallel logic**

All auto-delete in Step 10.

### Files to re-read at the start of Step 8c

- `docs/PHASE-1-IMPLEMENTATION-PLAN.md` — Step 8c section
- `src/mcp/mod.rs` — `McpRegistry::init_server` method body (the
  spawn logic to extract)
- `src/config/mcp_factory.rs` — current scaffolding from Step 6.5

## References

- Phase 1 plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Step 8a notes: `docs/implementation/PHASE-1-STEP-8a-NOTES.md`
- Step 7 notes: `docs/implementation/PHASE-1-STEP-7-NOTES.md`
- Modified files:
  - `src/config/request_context.rs` (7 new methods, import updates)
  - `src/config/app_config.rs` (4 new `set_*_default` / `ensure_*`
    methods)
  - `src/config/mod.rs` (4 helper functions bumped to `pub(super)`)