kestrel.markets/docs/adr/0055-the-execution-unit-is-an-episode-session-is-the-seat.md

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

# OSS-ADR-0055 — The execution unit is an **Episode**; "session" is reserved for the seat

Status: accepted (2026-07-18, owner-ratified in the same-day design session that
named the product). Code/spec rename tracked as `kestrel-10he`; the rename ships
inside a MINOR bump **before the 0.8.0 cutover freezes the public name**.

## Context

The word "session" was carrying two unrelated referents, and the collision was
discovered the expensive way — a design conversation in which two parties used
the same word for different objects and reached different conclusions:

1. **The runtime execution unit.** This repo's `Session` object
   (`{ driver, clock, gate, bus, mode }`): one continuous span of an Instance's
   execution over one market session, owning one Bus, yielding one Blotter,
   bounded and byte-replayable. Everything the determinism, certification, and
   grading doctrine binds to.
2. **The seat.** The interactive workstation state a caller sits at — screens,
   subscriptions, pending operations — which faces (CLI, API, MCP, SDK, web)
   attach to and detach from. What the product's own vocabulary, and every
   adjacent protocol (MCP sessions, HTTP sessions), naturally calls a
   "session."

The same conversation ratified the product framing that makes sense of the
split: **Kestrel Terminal is the product — the market workstation for agents —
and every face is a Rendering of the one Terminal.** Once the Terminal is the
product, sense (2) irrevocably owns the word: an agent connecting over MCP is
*in a session* in that protocol's own vocabulary, and no amount of glossary
discipline makes it mean "a deterministic replay unit" instead. Keeping the
runtime's name meant fighting every neighboring spec forever.

## Decision

**The deterministic execution unit is an *Episode*.** One strategy program
bound to one tape window: bounded, byte-replayable, owning exactly one Bus and
yielding exactly one Blotter. What certification certifies is an Episode. Two
ways the tape arrives — never a difference of execution authority: a
**backtest Episode** replays a bounded recorded window, compute-paced; a
**forward Episode** rides the advancing tape, wall-clock-paced from *outside*
the runtime, bounded only in retrospect, certifiable at close.

**"Session" is reserved for the seat.** A **Terminal session** is standing
screen state that faces attach to (the tmux model): it *launches* Episodes and
**references** them, never contains their records; it holds what is on the
screens — never strategy, prompts, or reasoning — and may never inject wall
time or nondeterminism into an Episode. Locally it is ephemeral and
single-face; durability and multi-face attachment are managed-service
concerns, out of scope here.

Surviving senses of the bare word: the market-hours span ("the morning
session" — the thing that bounds an Episode) and transport-layer "sessions"
owned by other protocols (MCP, HTTP, auth). Neither is ever the execution
unit.

**Naming collision note:** the fill channel's "resting episode" (OSS-ADR-0016)
predates this decision and keeps its qualified two-word name; a bare
**Episode** always means the execution unit.

## Consequences

- `CONTEXT.md` is renamed now (canon leads); the code and binding specs move
  together under `kestrel-10he`: `src/session/`, the `Session` /
  `SessionReport` types (→ `Episode` / `EpisodeReport`), `RUNTIME.md`,
  `SURFACES.md`, `AGENTS.md` prose. Until that lands, the code name `Session`
  is a known stale spelling of Episode, exactly as `BookState` is a stale
  spelling of the inventory ledger (kestrel-32tl).
- The rename is a MINOR version bump of the package and must land **before
  0.8.0**; after the cutover the public name is frozen.
- Docs and fixtures written before 2026-07-18 may still say "Kestrel Session"
  for this referent; new writing must not.
- The runtime invariants are untouched — this is a rename, not a semantics
  change. Determinism, fail-closed, round-trip, and bounded-risk clauses bind
  the Episode exactly as they bound the Session.