# mypy Triage — Gate 1 Stabilization (CyberBrain26)

## Goal
Reach `mypy src/cyberbrain26 → "Success: no issues found"` with no newly introduced type errors, while keeping runtime/security behavior fail-closed.

## Baseline (2026-11-05, host ~/CyberBrain26-unified)
`mypy src/cyberbrain26`: **Found 33 errors in 10 files** (checked 131 source files).

Errors by area:
- P0 runtime/security:
  - `execution_plane/execution_backends.py:244` — `"bool" not callable` [operator]. **Genuine bug**: helper is a method (`_check_runtime`), used as an attribute flag. Fixed to property-style access.
  - `memory/core.py` — client/collection double-definition + assigning `None` to non-Optional attrs; Chroma `where` typed `dict[str, str] | None` vs expected `Where | None`; `results["documents"]/["ids"]/["metadatas"]` index into Optional lists; string-index into dict results. P0/P1 (memory retrieval data path).
  - `knowledge_plane/batch_processor.py:305` — `list[float] | None` assigned into `list[float]`. No empty-vector fallback allowed.
- P1 public contract / optional boundary:
  - `model_layer/{ollama,llama_cpp,litellm}_client.py` — override signature incompatibilities + LiteLLM `list_models` return type. ProviderABC contract unresolved.
  - `execution_plane/execution_backends.py:49,82,431`; `orchestration/langgraph_orchestrator.py:14,15` — missing imports for `playwright`, `playwright.async_api`, `interpreter`, `langgraph.graph`, `langgraph.graph.state`.
- P2 hygiene:
  - `memory/auto.py:99`, `knowledge_plane/markdown_store.py:38`, `services/safe_oi/app.py:933,937,1107,1108` — unused `type: ignore` comments.

## Decisions (recommended, not yet implemented)
1. **ProviderABC canonical contract** (P1): adopt
   - `ChatResult = str | Iterator[dict[str, Any]]`
   - `def chat(self, model: str, messages: list[dict[str, str]], **kwargs: Any) -> ChatResult`
   - `def embed(self, model: str, texts: list[str], **kwargs: Any) -> list[list[float]]`
   - `def list_models(self) -> list[dict[str, Any]]`
   Implementations keep provider-specific options inside `**kwargs: Any` (provider options DTO), not narrowed overrides. Streaming must be verified against actual behavior before accepting any annotation.
2. **Optional dependency boundary** (P1): Treat Playwright, Open Interpreter, LangGraph as optional capabilities. No global `ignore_missing_imports`; no install without required-vs-optional decision. LangGraph imports → lazy/`TYPE_CHECKING`; Playwright/Interpreter availability → lazy resolution behind existing capability gates with explicit `capability_unavailable` outcomes.

## Task list (ordered)
1. Remove unused ignores: `memory/auto.py:99`, `knowledge_plane/markdown_store.py:38`, `services/safe_oi/app.py:933,937,1107,1108`.
2. `execution_plane/execution_backends.py` — keep lazy optional-import boundaries; verify no regression from the `bool`-not-callable fix.
3. `orchestration/langgraph_orchestrator.py` — make LangGraph imports optional/lazy; preserve state typing.
4. `memory/core.py` — Optional state model (`client: ClientAPI | None`, `collection: Collection | None`), guards/raises explicit `MemoryUnavailable`/config error, typed `Where`, non-None checks after `get()`, internal DTO normalization before indexing. Add tests: empty collection, missing metadata, multiple results, inactive backend.
5. `knowledge_plane/batch_processor.py` — explicit None-branch on embedding; **no empty-vector fallback**.
6. `model_layer` — implement unified ProviderABC contract + provider overrides; add contract tests for Ollama, llama.cpp, LiteLLM.
7. `services/safe_oi/app.py` — mechanical `Any` import fix + verify Safe OI tests green.
8. Full validation: `pytest -q`, `ruff check`, `mypy src/cyberbrain26`.

## Constraints (must hold)
- No `global ignore_missing_imports = True`.
- No blanket `# type: ignore`.
- No changing `Any` into arbitrary types without a contract.
- Never fall back to empty embedding vectors (false retrieval results).
- Do not weaken `ProviderABC` merely to silence override errors without verifying streaming behavior.
- Do not install missing packages without deciding required vs optional.

## Validation plan
- `pytest -q`
- `ruff check .`
- `mypy src/cyberbrain26` → Success, no issues found
- Re-run Safe OI tests after `Any` fix.
- Regression tests for: execution_backends bool bug, memory paths, batch processor missing embedding.
- Security review of all changes in `execution_plane`, `memory`, `services/safe_oi`, `model_layer`.
- Gate 1 acceptance: mypy success + green tests + ruff + security review + evidence ledger + no unguarded Funnel directory listing.

## Open items
- None blocking once decisions above are accepted by the implementation agent.