# Phase 3 Hypothetical Promotion: `ProviderHistory` Migration Analysis

**Date:** 2026-06-21
**Author:** Tier 1 Orchestrator
**Status:** Hypothetical — this is the analysis the deferred Phase 3 work would look like, NOT a track spec
**Input:** `docs/handoffs/HANDOFF_CODE_PATH_AUDIT_FROM_any_type_componentization.md` (Tier 2's runtime cost framing) + `src/provider_state.py` (the dataclass already on the tier2 branch)

---

## 1. Purpose

Phase 3 (`provider_state.ProviderHistory` call-site migration in `src/ai_client.py`) was deferred from `any_type_componentization_20260621` because:
1. It's the highest-risk phase (112 call sites across 6 senders)
2. The cost depends on whether each site is in a hot path, cold path, or init path
3. `code_path_audit_20260607` is the right tool to quantify that cost before refactoring

This document presents **what the migration would look like** — the approximate dataclasses, the call-site catalog, and a **qualitative cost estimation** of each codepath. The actual numbers will come from the audit. This document is the **what**; the audit produces the **cost**.

## 2. The Dataclass (already exists on `tier2/any_type_componentization_20260621` branch)

```python
# src/provider_state.py:25-44 (verbatim from branch)
@dataclass
class ProviderHistory:
 messages: list[HistoryMessage] = field(default_factory=list)
 lock: threading.Lock = field(default_factory=threading.Lock)

 def append(self, message: HistoryMessage) -> None:
 with self.lock:
 self.messages.append(message)

 def get_all(self) -> list[HistoryMessage]:
 with self.lock:
 return list(self.messages)

 def replace_all(self, messages: list[HistoryMessage]) -> None:
 with self.lock:
 self.messages = list(messages)

 def clear(self) -> None:
 with self.lock:
 self.messages = []
```

```python
# src/provider_state.py:47-69 (verbatim from branch)
_PROVIDER_HISTORIES: dict[str, ProviderHistory] = {
 "anthropic": ProviderHistory(),
 "deepseek": ProviderHistory(),
 "minimax": ProviderHistory(),
 "qwen": ProviderHistory(),
 "grok": ProviderHistory(),
 "llama": ProviderHistory(),
}

def get_history(provider: str) -> ProviderHistory:
 if provider not in _PROVIDER_HISTORIES:
 raise KeyError(f"Unknown provider: {provider!r}")
 return _PROVIDER_HISTORIES[provider]

def clear_all() -> None:
 for h in _PROVIDER_HISTORIES.values():
 h.clear()

def providers() -> tuple[str, ...]:
 return tuple(_PROVIDER_HISTORIES.keys())
```

**Properties that hold:**
- `@dataclass` (NOT `frozen=True`) — the message list and lock are mutable; this is correct.
- `default_factory=list` for `messages` — each `ProviderHistory` gets its own list.
- `default_factory=threading.Lock` for `lock` — each `ProviderHistory` gets its own lock instance.
- The 4-method interface encapsulates the lock; consumers never see it.

**This is already on the tier2 branch.** What Phase 3 does is migrate the consumers.

## 3. The Hypothetical Migration

The migration replaces direct module-global access (`_anthropic_history`, `_anthropic_history_lock`) with the typed accessor (`get_history("anthropic")`).

### 3.1 Mechanical Translation Rules

| Current | Hypothetical (typed) | Lock needed? |
|---|---|---|
| `_anthropic_history` (read) | `get_history("anthropic").get_all()` | Yes (returns copy under lock) |
| `_anthropic_history` (write ref) | `get_history("anthropic").messages` | Only inside `with h.lock:` |
| `_anthropic_history.append(m)` | `get_history("anthropic").append(m)` | Encapsulated |
| `len(_anthropic_history)` | `len(get_history("anthropic").messages)` | No (length is atomic in CPython) |
| `for m in _anthropic_history:` | `for m in get_history("anthropic").get_all():` | Yes |
| `with _anthropic_history_lock:` | `with get_history("anthropic").lock:` | Same |
| `_anthropic_history = []` | `get_history("anthropic").clear()` | Encapsulated |

### 3.2 Pattern Categories (per `HANDOFF_CODE_PATH_AUDIT_FROM_any_type_componentization.md` §1)

| Category | Sites | Path role |
|---|---:|---|
| `_<provider>_history.append(message)` | 6 | Hot — called per LLM turn |
| `len(_<provider>_history)` / `_<provider>_history[-1]` / iteration | ~40 | Hot — called per LLM turn for trimming, tool-history cache breakpoint, strip_cache_controls |
| `with _<provider>_history_lock:` | ~30 | Mixed — per-turn append is Hot; `reset_session` is Cold |
| `global _<provider>_history` declarations | 4 | N/A — module-level, no runtime cost |
| `_strip_cache_controls(_<provider>_history)` + `_repair_<provider>_history()` + `_add_history_cache_breakpoint()` + `_trim_<provider>_history()` | ~30 | Hot for Anthropic (cache controls); Mixed for others |

### 3.3 Per-Provider Site Count (measured from current `src/ai_client.py`)

| Provider | history refs | lock refs | global decls | Total sites |
|---|---:|---:|---:|---:|
| anthropic | 22 | 2 | 1 | 25 |
| deepseek | 13 | 6 | 1 | 20 |
| minimax | 15 | 5 | 1 | 21 |
| qwen | 7 | 4 | 1 | 12 |
| grok | 7 | 6 | 0 | 13 |
| llama | 12 | 9 | 0 | 21 |
| **Total** | **76** | **32** | **4** | **112** |

(Note: this 112 count is **higher** than the HANDOFF's "41" estimate, because the grep counts every reference including duplicates in helper functions. The migration work is the same either way — every reference gets touched — but the codepath catalog is richer.)

## 4. The Codepath Catalog (with Qualitative Cost Estimation)

This is the **what the audit will quantify**. Each codepath is tagged with `path_role`, `call_frequency`, and **estimated qualitative cost delta** (positive = slower, negative = faster, zero = no change).

### 4.1 `_send_anthropic` (L1407) — **HOT per-LLM-turn**

**Codepaths inside `_send_anthropic` (per the grep):**

| Codepath | Path role | Per-call freq | Qualitative cost delta |
|---|---|---|---|
| `_strip_cache_controls(_anthropic_history)` | Hot (called once per send) | 1× per LLM turn | **+0.5-1μs** (one extra dict lookup `get_history("anthropic")` per call) |
| `_repair_anthropic_history(_anthropic_history)` | Hot | 1× per LLM turn | **+0.5μs** (same) |
| `_anthropic_history.append(...)` (user message) | Hot | 1× per LLM turn | **+0.5μs** (method call vs. bare `.append()`) |
| `_add_history_cache_breakpoint(_anthropic_history)` | Hot | 1× per LLM turn | **+0.5μs** (same) |
| `_trim_anthropic_history(system_blocks, _anthropic_history)` | Hot | 1× per LLM turn | **+0.5μs** (one extra dict lookup) |
| `len(_anthropic_history)` | Hot | 2-3× per LLM turn (used in token estimation) | **+0.3μs** per call (`.messages` attribute access vs. global var lookup) |
| `_estimate_prompt_tokens(system_blocks, _anthropic_history)` | Hot | 1× per LLM turn | **+1μs** (the function takes a list; we pass `h.messages` under lock or `h.get_all()`; if the latter, that's a list copy — ~5μs for a 50-message history) |
| `for m in _anthropic_history:` (inside `_strip_cache_controls`) | Hot | 1× per LLM turn (iteration over ~10-50 messages) | **+5-10μs** (list copy via `get_all()`; the bare global just iterates directly) |

**Per-turn overhead estimate:** +8-15μs per `_send_anthropic` call. At ~50 turns per session, that's **+400-750μs per session**. Negligible vs LLM latency (typically 1-30 seconds).

**Recommendation (subject to audit):** Migrate, but use `with h.lock:` blocks for the hot paths inside `_strip_cache_controls` and `_estimate_prompt_tokens` to avoid the list-copy overhead of `get_all()`.

### 4.2 `_send_deepseek` (L2167) — **HOT per-LLM-turn**

**Similar pattern to `_send_anthropic` but simpler** (no cache controls). Estimated per-turn overhead: **+3-7μs**. At 50 turns/session, **+150-350μs/session**.

### 4.3 `_send_minimax` (L2616) — **HOT per-LLM-turn**

**Has `_trim_minimax_history` helper (L2484).** Estimated per-turn overhead: **+3-7μs**. **+150-350μs/session**.

### 4.4 `_send_grok` (L2532) — **HOT per-LLM-turn**

**No `_trim` or `_repair` helpers; simpler.** Estimated per-turn overhead: **+2-5μs**. **+100-250μs/session**.

### 4.5 `_send_qwen` (L2771) — **HOT per-LLM-turn**

**No helpers.** Estimated per-turn overhead: **+2-5μs**. **+100-250μs/session**.

### 4.6 `_send_llama` (L2856) — **HOT per-LLM-turn**

**Highest lock count (9 lock refs).** Estimated per-turn overhead: **+4-8μs**. **+200-400μs/session**.

### 4.7 `cleanup()` (L454) — **COLD per project-switch**

**Iterates over all 6 providers, calls `clear()` on each.** Current code does `with _<provider>_history_lock: _<provider>_history = []` 6 times. Hypothetical: `clear_all()` (already defined on branch) iterates and calls `clear()` once per provider.

**Per-call cost:** **-2 to -5μs** (negative — slight speedup because `clear_all()` is one function call vs. 6 inline blocks). Called once per project switch; **negligible** in absolute terms.

### 4.8 `reset_session()` (L461) — **COLD per project-switch**

**Calls `cleanup()` (the cold path above).** Total per-call cost: **-2 to -5μs**.

### 4.9 Init Path — **`_PROVIDER_HISTORIES` dict construction at module load**

**One-time cost at module import.** 6 `ProviderHistory()` instances each with `default_factory=list` + `default_factory=threading.Lock`. Total: ~10-15μs. **Negligible.**

## 5. Total Qualitative Cost Summary

| Codepath | Path role | Est. overhead per call | Frequency | Total per session |
|---|---|---|---|---|
| `_send_anthropic` | Hot per turn | +8-15μs | ~50 turns | +400-750μs |
| `_send_deepseek` | Hot per turn | +3-7μs | ~50 turns | +150-350μs |
| `_send_minimax` | Hot per turn | +3-7μs | ~50 turns | +150-350μs |
| `_send_grok` | Hot per turn | +2-5μs | ~50 turns | +100-250μs |
| `_send_qwen` | Hot per turn | +2-5μs | ~50 turns | +100-250μs |
| `_send_llama` | Hot per turn | +4-8μs | ~50 turns | +200-400μs |
| `cleanup()` / `reset_session()` | Cold per project switch | -2-5μs | ~1× | -2-5μs |
| Init (module load) | Once | +10-15μs | 1× | +10-15μs |
| **Total per session** | | | | **~+1.1-2.4ms** |

**Interpretation:** Even at the upper bound (+2.4ms per session), this is **3+ orders of magnitude smaller** than the LLM latency it lives alongside. The migration is **type-safety for free** in absolute runtime terms.

**The actual audit will quantify these estimates.** If the audit finds a >50μs delta per turn (e.g., from lock contention or `get_all()` list copies), the migration strategy changes (use `with h.lock:` blocks instead of `get_all()` to avoid copies).

## 6. The Risks (per `HANDOFF_CODE_PATH_AUDIT_FROM_any_type_componentization.md` §1)

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| `get_history("anthropic").get_all()` copies the list per access; `_estimate_prompt_tokens` is called per turn and iterates the copy | Medium | **+5-15μs per turn** | Use `with h.lock: msg_list = h.messages` pattern in hot iteration sites |
| Lock contention: multiple `_send_<provider>` calls in parallel (rare but possible during batch sends) | Low | **+1-10μs per turn under contention** | The lock is per-provider; no cross-provider contention; benchmark will reveal |
| `getattr` lookup overhead for `get_history(...)` vs. global var | Low | **+0.5μs per access** | Could inline as a module-level constant if needed; unlikely worth the readability cost |
| The `_send_anthropic` cache-control helpers iterate the list; a copy doubles memory bandwidth | Medium | **+10-30μs per turn** if hot | Refactor to operate on `h.messages` under lock without copying |
| Forgotten call site (one of the 76 history refs missed) | Medium | **Runtime AttributeError or NameError** | Run tier-1-unit-core + tier-2-mock-app-core FULLY per the regression protocol |

## 7. The Codepath Audit Additions (per `PROMPT_FOR_TIER_1.md` Decision 4)

Per Tier 1's sequencing decision, the `code_path_audit_20260607` will instrument:

| Action | Codepath | Measures |
|---|---|---|
| `provider_history_append` | `get_history(p).append(msg)` (or current `_anthropic_history.append(msg)`) | Per-turn append latency + lock acquire time |
| `websocket_broadcast` | `broadcast(WebSocketMessage(...))` (post-Phase 6a) | Per-broadcast overhead |
| `ai_message_lifecycle` (existing) | `_send_<provider>` end-to-end | Total per-turn latency delta pre/post Phase 3 |
| `discussion_save_load` (existing) | `reset_session()` + project switch | Cold-path cost |
| `gui_startup` (existing) | `_PROVIDER_HISTORIES` init | One-time cost |

## 8. Recommendation (subject to audit results)

**If the audit confirms the qualitative estimates** (+1-2ms per session; <50μs per turn):
- Proceed with Phase 3 migration as planned (~10-15 commits).
- Use `with h.lock:` blocks for hot iteration sites (`_strip_cache_controls`, `_estimate_prompt_tokens`) to avoid `get_all()` copies.
- Run the 11-tier regression protocol per the follow-up track.

**If the audit reveals a >50μs per-turn delta** (e.g., lock contention >10μs):
- Reconsider: do we even need to migrate the history aspect? It's `list[Metadata]` already typed.
- Alternative: keep the module globals but rename them with a `_HISTORY` suffix and document the pattern; defer full ProviderHistory migration.

**The audit decides.** This analysis is the input to the audit, not the conclusion.

## 9. Open Questions

1. **Should the `ProviderHistory.messages` be `list[HistoryMessage]` or `list[dict[str, Any]]`?** Currently it's `list[HistoryMessage]` (= `list[Metadata]`). The legacy code uses `list[Metadata]` everywhere. The dataclass stays consistent with the type alias.
2. **Should we add a `__len__` method to `ProviderHistory` to avoid `len(h.messages)`?**
   - Pros: cleaner consumer code
   - Cons: minor; only saves attribute access
3. **Should `_PROVIDER_HISTORIES` be a `MappingProxyType` (read-only) for external code?** Currently it's a regular dict; external code could mutate `_PROVIDER_HISTORIES["anthropic"] = ProviderHistory()`. Probably not worth the indirection.
4. **Should `get_history(p)` validate `p` (raise on unknown)?** Currently it raises `KeyError`. Could be `Literal["anthropic", "deepseek", ...]` for static type checking.

## 10. See Also

- `docs/handoffs/HANDOFF_CODE_PATH_AUDIT_FROM_any_type_componentization.md` — the original runtime cost framing
- `docs/handoffs/PROMPT_FOR_TIER_1.md` — Tier 1's decision points
- `src/provider_state.py` — the actual dataclass (already on `tier2/any_type_componentization_20260621` branch)
- `conductor/tracks/any_type_componentization_20260621/spec.md` — parent track spec
- `conductor/tracks/code_path_audit_20260607/spec.md` — the audit that will quantify these estimates
- `conductor/tracks/phase2_4_5_call_site_completion_20260621/spec.md` — the follow-up track that unblocks the audit