loki/docs/implementation/PHASE-1-STEP-4-NOTES.md

# Phase 1 Step 4 — Implementation Notes

## Status

Done.

## Plan reference

- Plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Section: "Step 4: Migrate global-write methods"

## Summary

Added 4 of 8 planned global-write methods to `AppConfig` as
inherent methods, duplicating the bodies that still exist on
`Config`. The other 4 methods were deferred: 2 to Step 7 (mixed
methods that call into `set_*` methods slated for Step 7), and
2 kept on `Config` because they populate runtime-only fields
(`functions`, `mcp_registry`) that don't belong on `AppConfig`.

Same duplication-no-caller-migration pattern as Step 3 — during
the bridge window both `Config` and `AppConfig` have these
methods; caller migration happens organically in Steps 8-9 when
frontends switch from `GlobalConfig` to `AppState` + `RequestContext`.

## What was changed

### Modified files

- **`src/config/app_config.rs`** — added 4 new imports (`NO_COLOR`,
  `get_env_name` via `crate::utils`, `terminal_colorsaurus`
  types) and a new `impl AppConfig` block with 4 methods under
  `#[allow(dead_code)]`:
  - `set_wrap(&mut self, value: &str) -> Result<()>` — parses and
    sets `self.wrap` for the `.set wrap` REPL command
  - `setup_document_loaders(&mut self)` — seeds default PDF/DOCX
    loaders into `self.document_loaders` if not already present
  - `setup_user_agent(&mut self)` — expands `"auto"` into
    `loki/<version>` in `self.user_agent`
  - `load_envs(&mut self)` — ~140 lines of env-var overrides that
    populate all 30+ serialized fields from `LOKI_*` environment
    variables

  All bodies are copy-pasted verbatim from the originals on
  `Config`, with references updated for the new module location:
  - `read_env_value::<T>` → `super::read_env_value::<T>`
  - `read_env_bool` → `super::read_env_bool`
  - `NO_COLOR`, `IS_STDOUT_TERMINAL`, `get_env_name`, `decode_bin`
    → imported from `crate::utils`
  - `terminal_colorsaurus` → direct import

### Unchanged files

- **`src/config/mod.rs`** — the original `Config::set_wrap`,
  `load_envs`, `setup_document_loaders`, `setup_user_agent`
  definitions are deliberately left intact. They continue to
  work for every existing caller. They get deleted in Step 10
  when `Config` is removed entirely.
- **`src/config/mod.rs`** — the `read_env_value` and
  `read_env_bool` private helpers are unchanged and accessed via
  `super::read_env_value` from `app_config.rs`.

## Key decisions

### 1. Only 4 of 8 methods migrated

The plan's Step 4 table listed 8 methods. After reading each one
carefully, I classified them:

| Method | Classification | Action |
|---|---|---|
| `set_wrap` | Pure global-write | **Migrated** |
| `load_envs` | Pure global-write | **Migrated** |
| `setup_document_loaders` | Pure global-write | **Migrated** |
| `setup_user_agent` | Pure global-write | **Migrated** |
| `setup_model` | Calls `self.set_model()` (Step 7 mixed) | **Deferred to Step 7** |
| `load_functions` | Writes runtime `self.functions` field | **Not migrated** (stays on `Config`) |
| `load_mcp_servers` | Writes runtime `self.mcp_registry` field (going away in Step 6.5) | **Not migrated** (stays on `Config`) |
| `update` | Dispatches to 10+ `set_*` methods, all Step 7 mixed | **Deferred to Step 7** |

See "Deviations from plan" for detail on each deferral.

### 2. Same duplication-no-forwarder pattern as Step 3

Step 4's target callers are all `.write()` on a `GlobalConfig` /
`Config` instance. Like Step 3, giving these callers an
`AppConfig` instance would require either (a) a sync'd
`Arc<AppConfig>` field on `Config` (breaks because Step 4
itself mutates `Config`), (b) cloning on every call (expensive
for `load_envs` which touches 30+ fields), or (c) duplicating
the method bodies.

Option (c) is the same choice Step 3 made and for the same
reasons. The duplication is 4 methods (~180 lines total dominated
by `load_envs`) that auto-delete in Step 10.

### 3. `load_envs` body copied verbatim despite being long

`load_envs` is ~140 lines of repetitive `if let Some(v) =
read_env_value(...) { self.X = v; }` blocks — one per serialized
field. I considered refactoring it to reduce repetition (e.g., a
macro or a data-driven table) but resisted that urge because:

- The refactor would be a behavior change (even if subtle) during
  a mechanical code-move step
- The verbatim copy is easy to audit for correctness (line-by-line
  diff against the original)
- It gets deleted in Step 10 anyway, so the repetition is
  temporary
- Any cleanup belongs in a dedicated tidying pass after Phase 1,
  not in the middle of a split

### 4. Methods stay in a separate `impl AppConfig` block

Step 3 added its 7 read methods in one `impl AppConfig` block.
Step 4 adds its 4 write methods in a second `impl AppConfig`
block directly below it. Rust allows multiple `impl` blocks on
the same type, and the visual separation makes it obvious which
methods are reads vs writes during the bridge window. When Step
10 deletes `Config`, both blocks can be merged or left separate
based on the cleanup maintainer's preference.

## Deviations from plan

### `setup_model` deferred to Step 7

The plan lists `setup_model` as a Step 4 target. Reading its
body:

```rust
fn setup_model(&mut self) -> Result<()> {
    let mut model_id = self.model_id.clone();
    if model_id.is_empty() {
        let models = list_models(self, ModelType::Chat);
        // ...
    }
    self.set_model(&model_id)?;  // ← this is Step 7 "mixed"
    self.model_id = model_id;
    Ok(())
}
```

It calls `self.set_model(&model_id)`, which the plan explicitly
lists in **Step 7** ("mixed methods") because `set_model`
conditionally writes to `role_like` (runtime) or `model_id`
(serialized) depending on whether a role/session/agent is
active. Since `setup_model` can't be migrated until `set_model`
exists on `AppConfig` / `RequestContext`, it has to wait for
Step 7.

**Action:** left `Config::setup_model` intact. Step 7 picks it up.

### `update` deferred to Step 7

The plan lists `update` as a Step 4 target. Its body is a ~140
line dispatch over keys like `"temperature"`, `"top_p"`,
`"enabled_tools"`, `"enabled_mcp_servers"`, `"max_output_tokens"`,
`"save_session"`, `"compression_threshold"`,
`"rag_reranker_model"`, `"rag_top_k"`, etc. — every branch
calls into a `set_*` method on `Config` that the plan explicitly
lists in **Step 7**:

- `set_temperature` (Step 7)
- `set_top_p` (Step 7)
- `set_enabled_tools` (Step 7)
- `set_enabled_mcp_servers` (Step 7)
- `set_max_output_tokens` (Step 7)
- `set_save_session` (Step 7)
- `set_compression_threshold` (Step 7)
- `set_rag_reranker_model` (Step 7)
- `set_rag_top_k` (Step 7)

Migrating `update` before those would mean `update` calls
`Config::set_X` (old) from inside `AppConfig::update` (new) —
which crosses the type boundary awkwardly and leaves `update`'s
behavior split between the two types during the migration
window. Not worth it.

**Action:** left `Config::update` intact. Step 7 picks it up
along with the `set_*` methods it dispatches to. At that point
all 10 dependencies will be on `AppConfig`/`RequestContext` and
`update` can be moved cleanly.

### `load_functions` not migrated (stays on Config)

The plan lists `load_functions` as a Step 4 target. Its body:

```rust
fn load_functions(&mut self) -> Result<()> {
    self.functions = Functions::init(
        self.visible_tools.as_ref().unwrap_or(&Vec::new())
    )?;
    if self.working_mode.is_repl() {
        self.functions.append_user_interaction_functions();
    }
    Ok(())
}
```

It writes to `self.functions` — a `#[serde(skip)]` runtime field
that lives on `RequestContext` after Step 6 and inside `ToolScope`
after Step 6.5. It also reads `self.working_mode`, another
runtime field. This isn't a "global-write" method in the sense
Step 4 targets — it's a runtime initialization method that will
move to `RequestContext` when `functions` does.

**Action:** left `Config::load_functions` intact. It gets
handled in Step 5 or Step 6 when runtime fields start moving.
Not Step 4, not Step 7.

### `load_mcp_servers` not migrated (stays on Config)

Same story as `load_functions`. Its body writes
`self.mcp_registry` (a field slated for deletion in Step 6.5 per
the architecture plan) and `self.functions` (runtime, moving in
Step 5/6). Nothing about this method belongs on `AppConfig`.

**Action:** left `Config::load_mcp_servers` intact. It gets
handled or deleted in Step 6.5 when `McpFactory` replaces the
singleton registry entirely.

## Verification

### Compilation

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

### Tests

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

Step 4 added no new tests because it's duplication. The existing
test suite confirms:
- The original `Config` methods still work (they weren't touched)
- `AppConfig` still compiles, its `Default` impl is intact
- The bridge's round-trip test still passes:
  - `config::bridge::tests::round_trip_default_config`
  - `config::bridge::tests::round_trip_preserves_all_non_lossy_fields`
  - `config::bridge::tests::to_app_config_copies_every_serialized_field`
  - `config::bridge::tests::to_request_context_copies_every_runtime_field`

### Manual smoke test

Not applicable — no runtime behavior changed. CLI and REPL still
call `Config::set_wrap()`, `Config::update()`, `Config::load_envs()`,
etc. unchanged.

## Handoff to next step

### What Step 5 can rely on

Step 5 (migrate request-read methods to `RequestContext`) can
rely on:

- `AppConfig` now has **11 methods total**: 7 reads from Step 3,
  4 writes from Step 4
- `#[allow(dead_code)]` on both `impl AppConfig` blocks — safe
  to leave as-is, goes away when callers migrate in Steps 8+
- `Config` is unchanged for all 11 methods — originals still
  work for all current callers
- The bridge from Step 1, the paths module from Step 2, the
  read methods from Step 3 are all unchanged and still working
- **`setup_model`, `update`, `load_functions`, `load_mcp_servers`
  are still on `Config`** and must stay there:
  - `setup_model` → migrates in Step 7 with the `set_*` methods
  - `update` → migrates in Step 7 with the `set_*` methods
  - `load_functions` → migrates to `RequestContext` in Step 5 or
    Step 6 (whichever handles `Functions`)
  - `load_mcp_servers` → deleted/transformed in Step 6.5

### What Step 5 should watch for

- **Step 5 targets are `&self` request-read methods** that read
  runtime fields like `self.session`, `self.role`, `self.agent`,
  `self.rag`, etc. The plan's Step 5 table lists:
  `state`, `messages_file`, `sessions_dir`, `session_file`,
  `rag_file`, `info`, `role_info`, `session_info`, `agent_info`,
  `agent_banner`, `rag_info`, `list_sessions`,
  `list_autoname_sessions`, `is_compressing_session`,
  `role_like_mut`.
- **These migrate to `RequestContext`**, not `AppConfig`, because
  they read per-request state.
- **Same duplication pattern applies.** Add methods to
  `RequestContext`, leave originals on `Config`, no caller
  migration.
- **`sessions_dir` and `messages_file` already use `paths::`
  functions internally** (from Step 2's migration). They read
  `self.agent` to decide between the global and agent-scoped
  path. Those paths come from the `paths` module.
- **`role_like_mut`** is interesting — it's the helper that
  returns a mutable reference to whichever of role/session/agent
  is on top. It's the foundation for every `set_*` method in
  Step 7. Migrate it to `RequestContext` in Step 5 so Step 7
  has it ready.
- **`list_sessions` and `list_autoname_sessions`** wrap
  `paths::list_file_names` with some filtering. They take
  `&self` to know the current agent context for path resolution.

### What Step 5 should NOT do

- Don't touch the Step 3/4 methods on `AppConfig` — they stay
  until Steps 8+ caller migration.
- Don't try to migrate `update`, `setup_model`, `load_functions`,
  or `load_mcp_servers` — each has a specific later-step home.
- Don't touch the `bridge.rs` conversions — still needed.
- Don't touch `paths.rs` — still complete.
- Don't migrate any caller of any method yet — callers stay on
  `Config` through the bridge window.

### Files to re-read at the start of Step 5

- `docs/PHASE-1-IMPLEMENTATION-PLAN.md` — Step 5 section has
  the full request-read method table
- This notes file — specifically "Deviations from plan" and
  "What Step 5 should watch for"
- `src/config/request_context.rs` — to see the current shape
  that Step 5 will extend
- Current `Config` method bodies in `src/config/mod.rs` for
  each Step 5 target (search for `pub fn state`, `pub fn
  messages_file`, etc.)

## Follow-up (not blocking Step 5)

### 1. `load_envs` is the biggest duplication so far

At ~140 lines, `load_envs` is the largest single duplication in
the bridge. It's acceptable because it's self-contained and
auto-deletes in Step 10, but it's worth flagging that if Phase 1
stalls anywhere between now and Step 10, this method's duplication
becomes a maintenance burden. Env var changes would need to be
made twice.

**Mitigation during the bridge window:** if someone adds a new
env var during Steps 5-9, they MUST add it to both
`Config::load_envs` and `AppConfig::load_envs`. Document this in
the Step 5 notes if any env var changes ship during that
interval.

### 2. `AppConfig` now has 11 methods across 2 `impl` blocks

Fine during Phase 1. Post-Phase 1 cleanup can consider whether to
merge them or keep the read/write split. Not a blocker.

### 3. The `read_env_value` / `read_env_bool` helpers are accessed via `super::`

These are private module helpers in `src/config/mod.rs`. Step 4's
migration means `app_config.rs` now calls them via `super::`,
which works because `app_config.rs` is a sibling module. If
Phase 2+ work moves these helpers anywhere else, the `super::`
references in `app_config.rs` will need updating.

## References

- Phase 1 plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Step 3 notes: `docs/implementation/PHASE-1-STEP-3-NOTES.md`
  (for the duplication rationale)
- Modified file: `src/config/app_config.rs` (new imports + new
  `impl AppConfig` block with 4 write methods)
- Unchanged but referenced: `src/config/mod.rs` (original
  `Config` methods still exist, private helpers
  `read_env_value` / `read_env_bool` accessed via `super::`)