kestrel.markets/docs/adr/0001-one-language-four-statement-kinds-two-lifecycles.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.

# One language, four statement kinds, two lifecycles

Kestrel's four surfaces (View, Wake, Plan, Grade) are **one language with one lexical
core** — a single parser and a single concise TS AST family — not four mini-languages
that ship together. The trigger algebra (WHEN), named-series references, and price
expressions are defined once and shared by every surface, so an author (human or agent)
learns them once. The alternative — per-surface grammars — was rejected because it
multiplies the learning surface for agents, invites definitional drift between a Wake's
trigger and a Plan's trigger (a skew class observed repeatedly in live trading: the
same-named value computed two ways in two places), and forecloses documents that mix
surfaces.

Statements are typed by **lifecycle**, not just syntax: View/Wake/Plan are **standing**
(authored → armed → versioned → superseded); Grade is **imperative** (a job that runs
and returns). The grammar parses all four; the runtime routes them to different
lifecycles. This is the hard-won distinction between imperative orders and standing
programs, and its corollary "a wake is not a plan": sharing syntax must never flatten
different kinds of authority into one shape.

**Consequences:**
- One Kestrel document may contain multiple statements; standing statements in a
  document arm together as a unit; an imperative statement executes as a job.
- Two equal document forms parse identically: `.kestrel` files (pure execution) and
  ```` ```kestrel ```` fenced blocks in Markdown (docs, reasoning traces, agent output).
  Tooling (syntax highlighting, VS Code extension) targets both.
- Design goals of the language are binding on every surface: token-efficient, reads like
  English, intuitive to humans and agents alike.
- A recurring grade is composed (a Wake triggering a Grade), never a third lifecycle.