kestrel.markets/docs/public/lexical-core.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.

# The shared lexical core

Kestrel is **one language with one lexical core**. The four statement kinds — View, Wake,
Plan, Grade — are not four dialects; they share the same series references, the same trigger
algebra, the same price expressions, and the same lexical conventions. Learn the core once
and you can read all four.

That is the whole reason the language fits in a context window: an author holds the entire
grammar in a few hundred tokens, and every kind reuses the same pieces.

## The core, in four parts

- **Series** — anything with a name whose value changes over time: the universal operand.
  Two kinds only. **Market facts** (`spot`, `vwap`, `hod`, `velocity(1m)`) are ambient per
  signal instrument and visible even to spectators. **Org facts** (`pnl`, `fills.avg_px`) are
  path-scoped in the org tree and exist only in acting sessions.
- **The trigger algebra** — the shared `WHEN` language: series × predicates (compare, cross,
  break-and-hold, distance, velocity, state, window) × `AND / OR / NOT`, plus `held` and
  `within`. Used by Wake, Plan, and Grade filters alike.
- **Windows** — the timescale every rate/magnitude series carries: `velocity(1m)`,
  `move(1d)`. There is no absolute shock; magnitude is judged at a window against that
  window's own trailing baseline (`p99`, `3sigma`), so a threshold is portable across
  instruments.
- **Price expressions** — three anchor families crossed with combinators. **VALUE**
  (`fair · intrinsic · basis`) is what something is worth; **BOOK** (`bid ask mid last`) is
  only where the queue is; **ABSOLUTE** (`1.85`) is a fixed number. Combinators layer on any
  anchor: `lean(bid, fair, 0.5)`, `min`/`max`, offsets (`fair-3c`), `peg`, and bounds
  (`cap` on buys, `floor ≥ intrinsic` on sells). A quote is never a value.

## One algebra, three kinds

Watch the same operands appear across three different statement kinds.

A **Wake** spends attention, never risk. It subscribes over the trigger algebra and delivers
a View — here it fires when spot pushes above the high of day and delivers the `open` View
from [First Frame](./first-frame.md), up to eight times a day:

```kestrel id=core-wake check=roundtrip
WAKE watch-hod
  WHEN spot > hod
  DELIVER open
  BUDGET 8 wakes/day
```

A **Plan** spends risk. This fade uses the *same* series (`spot`, `vwap`, `hod`) but the
opposite thesis to the drive Plan on the [First Plan](./first-plan.md) page: a flush below
VWAP is a gift, so buy into it; and if the level truly breaks and holds, **INVALIDATE** —
stop adding, ride the bounded remainder — rather than EXIT:

```kestrel id=core-plan-fade check=roundtrip
PLAN fade-level budget 0.4R ttl 15:30
  WHEN spot crosses below vwap
  DO buy 1 -1 P @ lean(bid, fair, 0.5)
  INVALIDATE spot > hod held 120s
```

Notice `lean(bid, fair, 0.5)` — a **combinator** resting halfway between the book (`bid`) and
value (`fair`). The same price grammar the drive Plan used for `min(fair, mid) cap fair`.

A **Grade** reads recorded history. It replays authored statements over recorded sessions
under a named fill model, with counterfactuals as syntax — never a parameter search:

```kestrel id=core-grade check=roundtrip
GRADE plan open-drive OVER 2024-01..2026-06 FILL maker-v1
  VS ungated null
  BY regime.intraday, lineage
```

`VS ungated` is the counterfactual that strips a Plan's `regime` gate — it asks whether gating
earned its keep on the tapes that carry that regime (the Plans above are ungated so they fire on
every cell; a `regime {…}` clause is a hard arming gate, absent from free tapes); `VS null` asks
whether there is any edge at all with the same fills and no judgment; `BY regime.intraday, lineage`
stratifies the answer into honest cells instead of one flattering average.

## Why it holds together

Because the operands are shared, a series registered once is visible to every surface — a
trigger, a pane, a grade column — by construction. And because the same adverse observation
means opposite things to opposite theses, the grammar makes the **thesis** choose: the drive
Plan EXITs on giveback; the fade Plan INVALIDATEs. Same words, opposite intent, one core.

## Next

- **[Capability truth](./capability-truth.md)** — the Wake and Grade statements above parse
  and round-trip, but their *runtime* and *evidence* axes are graded separately. Learn to
  read what Kestrel actually claims.