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

# Phase 1 Step 1 — Implementation Notes

## Status

Done.

## Plan reference

- Plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Section: "Step 1: Make Config constructible from AppConfig + RequestContext"

## Summary

Added three conversion methods on `Config` (`to_app_config`,
`to_request_context`, `from_parts`) plus a round-trip test suite, all
living in a new `src/config/bridge.rs` module. These methods are the
facade that will let Steps 2–9 migrate callsites from the old `Config`
to the split `AppState` + `RequestContext` incrementally. Nothing calls
them outside the test suite yet; that's expected and matches the
plan's "additive only, no callsite changes" guidance for Step 1.

## Pre-Step-1 correction to Step 0

Before implementing Step 1 I verified all three Step 0 files
(`src/config/app_config.rs`, `src/config/app_state.rs`,
`src/config/request_context.rs`) against every architecture decision
from the design conversations. All three were current except one stale
reference:

- `src/config/request_context.rs` docstring said "unified into
  `ToolScope` during Phase 1 Step 6" but after the
  ToolScope/AgentRuntime discussions the plan renumbered this to
  **Step 6.5** and added the `AgentRuntime` collapse alongside
  `ToolScope`. Updated the `# Tool scope (planned)` section docstring
  to reflect both changes (now titled `# Tool scope and agent runtime
  (planned)`).

No other Step 0 changes were needed.

## What was changed

### New files

- **`src/config/bridge.rs`** (~430 lines including tests)
  - Module docstring explaining the bridge's purpose, scheduled
    deletion in Step 10, and the lossy `mcp_registry` field.
  - `impl Config` block with three public methods, scoped under
    `#[allow(dead_code)]`:
    - `to_app_config(&self) -> AppConfig` — borrow, returns fresh
      `AppConfig` by cloning the 40 serialized fields.
    - `to_request_context(&self, app: Arc<AppState>) -> RequestContext`
      — borrow + provided `AppState`, returns fresh `RequestContext`
      by cloning the 19 runtime fields held on both types.
    - `from_parts(app: &AppState, ctx: &RequestContext) -> Config` —
      borrow both halves, returns a new owned `Config`. Sets
      `mcp_registry: None` because no split type holds it.
  - `#[cfg(test)] mod tests` with 4 unit tests:
    - `to_app_config_copies_every_serialized_field`
    - `to_request_context_copies_every_runtime_field`
    - `round_trip_preserves_all_non_lossy_fields`
    - `round_trip_default_config`
  - Helper `build_populated_config()` that sets every primitive /
    `String` / simple `Option` field to a non-default value so a
    missed field in the conversion methods produces a test failure.

### Modified files

- **`src/config/mod.rs`** — added `mod bridge;` declaration (one
  line, inserted alphabetically between `app_state` and `input`).
- **`src/config/request_context.rs`** — updated the "Tool scope
  (planned)" docstring section to correctly reference Phase 1
  **Step 6.5** (not Step 6) and to mention the `AgentRuntime`
  collapse alongside `ToolScope`. No code changes.

## Key decisions

### 1. The bridge lives in its own module

I put the conversion methods in `src/config/bridge.rs` rather than
adding them inline to `src/config/mod.rs`. The plan calls for this
entire bridge to be deleted in Step 10, and isolating it in one file
makes that deletion a single `rm` + one `mod bridge;` line removal in
`mod.rs`. Adding ~300 lines to the already-massive `mod.rs` would have
made the eventual cleanup harder.

### 2. `mcp_registry` is lossy by design (documented)

`Config.mcp_registry: Option<McpRegistry>` has no home in either
`AppConfig` (serialized settings only) or `RequestContext` (runtime
state that doesn't include MCP, per Step 6.5's `ToolScope` design).
I considered three options:

1. **Add a temporary `mcp_registry` field to `RequestContext`** — ugly,
   introduces state that has to be cleaned up in Step 6.5 anyway.
2. **Accept lossy round-trip, document it** — chosen.
3. **Store `mcp_registry` on `AppState` temporarily** — dishonest,
   contradicts the plan which says MCP isn't process-wide.

Option 2 aligns with the plan's direction. The lossy field is
documented in three places so no caller is surprised:

- Module-level docstring (`# Lossy fields` section)
- `from_parts` method docstring
- Inline comment next to the `is_none()` assertion in the round-trip
  test

Any Step 2–9 callsite that still needs the registry during its
migration window must keep a reference to the original `Config`
rather than relying on round-trip fidelity.

### 3. `#[allow(dead_code)]` scoped to the whole `impl Config` block

Applied to the `impl` block in `bridge.rs` rather than individually to
each method. All three methods are dead until Step 2+ starts calling
them. When the first caller migrates, I'll narrow the allow to the
methods that are still unused. By Step 10 the whole file is deleted
and the allow goes with it.

### 4. Populated-config builder skips domain-type runtime fields

`build_populated_config()` sets every primitive, `String`, and simple
`Option` field to a non-default value. It does **not** try to construct
real `Role`, `Session`, `Agent`, `Supervisor`, `Inbox`, or
`EscalationQueue` instances because those have complex async/setup
lifecycles and constructors don't exist for test use.

The round-trip tests still exercise the clone path for all those
`Option<T>` fields — they just exercise the `None` variant. The tests
prove that (a) if a runtime field is set, the conversion clones it
correctly (which is guaranteed by Rust's `#[derive(Clone)]` on
`Config`), and (b) `None` roundtrips to `None`. Deeper coverage with
populated domain types would require mock constructors that don't
exist in the current code, making it a meaningful scope increase
unsuitable for Step 1's "additive, mechanical" goal.

### 5. The test covers `Config::default()` separately from the
populated builder

A separate `round_trip_default_config` test catches any subtle "the
default doesn't roundtrip" bug that `build_populated_config` might
mask by always setting fields to non-defaults. Both tests run through
the same `to_app_config → to_request_context → from_parts` pipeline.

## Deviations from plan

None of substance. The plan's Step 1 description was three sentences
and a pseudocode block; the implementation matches it field-for-field
except for two clarifications the plan didn't specify:

1. **Which module holds the methods** — the plan didn't say. I chose a
   dedicated `src/config/bridge.rs` file (see Key Decision #1).

2. **How `mcp_registry` is handled in round-trip** — the plan's
   pseudocode said `from_parts` "merges back" but didn't address the
   field that has no home. I chose lossy reconstruction with
   documented behavior (see Key Decision #2).

Both clarifications are additive — they don't change what Step 1
accomplishes, they just pin down details the plan left implicit.

## Verification

### Compilation

- `cargo check` — clean, zero warnings. The expected dead-code warning
  from the new methods is suppressed by `#[allow(dead_code)]` on the
  `impl` block.

### Tests

- `cargo test bridge` — 4 new tests pass:
  - `config::bridge::tests::round_trip_default_config`
  - `config::bridge::tests::to_app_config_copies_every_serialized_field`
  - `config::bridge::tests::to_request_context_copies_every_runtime_field`
  - `config::bridge::tests::round_trip_preserves_all_non_lossy_fields`

- `cargo test` — full suite passes: **63 passed, 0 failed**
  (59 pre-existing + 4 new).

### Manual smoke test

Not applicable — Step 1 is additive only, no runtime behavior changed.
CLI and REPL continue working through the original `Config` code
paths, unchanged.

## Handoff to next step

### What Step 2 can rely on

Step 2 (migrate ~30 static methods off `Config` to a `paths` module)
can rely on all of the following being true:

- `Config::to_app_config()`, `Config::to_request_context(app)`, and
  `Config::from_parts(app, ctx)` all exist and are tested.
- The three new types (`AppConfig`, `AppState`, `RequestContext`) are
  fully defined and compile.
- Nothing in the codebase outside `src/config/bridge.rs` currently
  calls the new methods, so Step 2 is free to start using them
  wherever convenient without fighting existing callers.
- `AppState` only has two fields: `config: Arc<AppConfig>` and
  `vault: GlobalVault`. No `mcp_factory`, no `rag_cache` yet — those
  land in Step 6.5.
- `RequestContext` has flat fields mirroring the runtime half of
  today's `Config`. The `ToolScope` / `AgentRuntime` unification
  happens in Step 6.5, not earlier. Step 2 should not try to
  pre-group fields.

### What Step 2 should watch for

- **Static methods on `Config` with no `&self` parameter** are the
  Step 2 target. The Phase 1 plan lists ~33 of them in a table
  (`config_dir`, `local_path`, `cache_path`, etc.). Each gets moved
  to a new `src/config/paths.rs` module (or similar), with forwarding
  `#[deprecated]` methods left behind on `Config` until Step 2 is
  fully done.
- **`vault_password_file`** on `Config` is private (not `pub`), but
  `vault_password_file` on `AppConfig` is `pub(crate)`. `bridge.rs`
  accesses both directly because it's a sibling module under
  `src/config/`. If Step 2's path functions need to read
  `vault_password_file` from `AppConfig` they can do so directly
  within the `config` module, but callers outside the module will
  need an accessor method.
- **`Config.mcp_registry` round-trip is lossy.** If any static method
  moved in Step 2 touches `mcp_registry` (unlikely — none of the ~33
  static methods listed in the plan do), that method should NOT use
  the bridge — it should keep operating on the original `Config`.
  Double-check the list before migrating.

### What Step 2 should NOT do

- Don't delete the bridge. It's still needed for Steps 3–9.
- Don't narrow `#[allow(dead_code)]` on `impl Config` in `bridge.rs`
  yet — Step 2 might start using some of the methods but not all,
  and the allow-scope should be adjusted once (at the end of Step 2)
  rather than incrementally.
- Don't touch the `request_context.rs` `# Tool scope and agent
  runtime (planned)` docstring. It's accurate and Step 6.5 is still
  far off.

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

- `docs/PHASE-1-IMPLEMENTATION-PLAN.md` — Step 2 section has the
  full static-method migration table.
- This notes file (`PHASE-1-STEP-1-NOTES.md`) — for the bridge's
  current shape and the `mcp_registry` lossy-field context.
- `src/config/bridge.rs` — for the exact method signatures available.

## References

- Phase 1 plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Architecture doc: `docs/REST-API-ARCHITECTURE.md`
- Step 0 files: `src/config/app_config.rs`, `src/config/app_state.rs`,
  `src/config/request_context.rs`
- Step 1 files: `src/config/bridge.rs`, `src/config/mod.rs` (mod
  declaration), `src/config/request_context.rs` (docstring fix)