tracer-cloud--opensre/docs/NAMING.md

# Naming conventions for `core/`

A small, enforceable vocabulary so file and type names say what they are. The
goal is that a reader can tell a data type from a process, a mutable state from
a frozen view, and a package's purpose from its name alone.

## Glossary (one meaning per term)

| Term | Means | Example |
| --- | --- | --- |
| **State** | Mutable investigation/session facts that evolve during a run | `AgentState`, `InvestigationState` |
| **Snapshot** | A frozen view captured at a boundary (turn start, run start) | `TurnSnapshot` |
| **RunInput** / **RunResult** | The input to and output from one `Agent.run()` boundary | `AgentRunInput`, `AgentRunResult` |
| **Slice** | A typed segment of a state dict | `DiagnosisSlice`, `AlertInputSlice` |
| **Resources** | Handles passed into tool executors for one call | `ToolCallResources` |
| **Budget** | An LLM token/window policy — not application state | `enforce_token_budget` |
| **Host** | The callback contract an algorithm drives (a `Protocol`) | `LoopHost` |

## Module naming: `{domain}_{role}.py`

Name a file for the concept it holds, not with a generic bucket word.

```
core/agent/
  agent.py          # the Agent facade
  react_loop.py     # ReactLoop + run_react_loop  (the algorithm)
  loop_host.py      # LoopHost                    (the callback contract)
  run_io.py         # AgentRunInput, AgentRunResult (the run boundary's I/O)
  mixins.py         # the reusable *Mixin behaviors
  provider_hooks.py # ProviderHookDelegate
```

## Type naming

- **Mixins** carry a `Mixin` suffix — they cannot stand alone (they assume
  fields/methods the host provides). `EventEmitterMixin`, `ToolFilterMixin`,
  `SteeringMixin`.
- **Protocols** are named by their role, not with a `Protocol` suffix — matches
  the stdlib (`Iterable`, `SupportsRead`) and `agent_harness/ports.py`
  (`OutputSink`, `SessionStore`). `LoopHost`, not `LoopHostProtocol`.
- **Do not prefix a type with its own package name.** Inside `core/agent/`, a
  class is `EventEmitterMixin`, not `AgentEventEmitter` — the namespace already
  says "agent."

## Anti-patterns (do not add in new code)

- `context.py` at `core/` or `core/agent/` root — "context" is overloaded across
  the repo. Name the concept (`run_io.py`, `turn_snapshot.py`).
- `models.py` when the file holds only run I/O — too vague. Say what the models
  are (`run_io.py`).
- `*Context` without a domain prefix when another `*Context` already exists.
- A package whose only child is a single sub-package — collapse the wrapper.

## Imports

Use fully qualified paths in code; keep short mental labels for docs.

| Mental label | Import |
| --- | --- |
| ReAct run I/O | `from core.agent.run_io import AgentRunInput, AgentRunResult` |
| ReAct loop | `from core.agent.react_loop import run_react_loop` |
| Loop callback contract | `from core.agent.loop_host import LoopHost` |
| The agent primitive | `from core.agent import Agent` |
| Harness turn snapshot | `from core.agent_harness.turns.turn_snapshot import TurnSnapshot` |

Re-export from a package `__init__.py` only for its single canonical symbol
(`Agent`), not everything — avoid `from core.agent import *`-style ambiguity.