kestrel.markets/docs/public/first-wake.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.

# First Wake — a standing subscription that spends attention

A **Wake** answers *when should I look?* It is a standing subscription over the trigger
algebra that spends **attention** — tokens and wakes — and never risk. A Wake is not a Plan:
it cannot place an order. It watches, and when its condition confirms it delivers a View to
the author. The wake decides *when*; the View decides *what*.

This page reads one Wake clause by clause.

```kestrel id=wake-fast-move check=roundtrip
WAKE fast-move
  WHEN velocity(1m) > p99
  DELIVER open KEYFRAME
  PRIORITY 2
  COALESCE fast-move
  BUDGET 8 wakes/day
```

## The header: attention, never risk

```
WAKE fast-move
```

A Wake is named, standing, and armed like a View or a Plan — but the only thing it can spend
is your attention. The name is not decoration: every free-text name (plan, wake, clause, tag)
is a legible, gradable aggregation key, so `fade-setup` and `fast-move` become columns a Grade
can later cull if they never earn a look. Mint them freely; the accounting is downstream.

## The trigger: WHEN to look

```
WHEN velocity(1m) > p99
```

The `WHEN` clause is the same trigger algebra a Plan uses to decide when it may fire — named
series and predicates composed with `AND / OR / NOT`. `p99` is a **baseline-relative**
threshold: the 99th percentile of that window's own trailing distribution, not an absolute
number, so the same Wake is portable across instruments. A Wake reads this algebra to spend
attention where a Plan reads it to spend risk; the language is identical. See the [shared
lexical core](./lexical-core.md).

## The delivery: what you see when it fires

```
DELIVER open KEYFRAME
```

A Wake names the View it delivers — here, the `open` View from [First Frame](./first-frame.md).
This is the division that keeps the language small: the wake decides *when* to look, the View
decides *what* is shown, and the two compose freely. `KEYFRAME` asks for a full re-orientation
Frame rather than a delta — when a fast move wakes you, you want the whole screen re-stamped,
not just the bars that changed. A wake's delivered View zooms to the wake's window: detection
scale is rendering scale.

## The dispatch discipline: priority, coalesce, budget

```
PRIORITY 2
COALESCE fast-move
BUDGET 8 wakes/day
```

Attention is finite, so a Wake declares how it competes for it. `PRIORITY` ranks this wake
against others when they contend. `COALESCE fast-move` names a squelch group: when the budget
saturates, wakes sharing a key **coalesce and downgrade** — a burst becomes one delivery,
never a silent drop, and the squelch stays visible in the record. `BUDGET 8 wakes/day` caps
the spend outright. Nothing here can move a position; the entire clause set governs only how
often, and how loudly, the author is interrupted.

## Two more clauses

Two clauses this Wake does not use, but every author should know:

- **UNIVERSE** turns a Wake into a **Scan** — a Wake whose scope is a whole universe rather
  than one coverage. `UNIVERSE all-listed` is wide and slow (every listing at `move(1d) > p99`)
  where a coverage Wake is narrow and fast.
- **MANDATORY** (a delivery modifier, `DELIVER open MANDATORY`) marks a delivery that must
  never be squelched. It is how the platform's backstop wake works: if nothing has woken you
  in a while, one fires anyway — not removable while you hold positions, because an agent may
  never go blind to its own book.

## What is real today

The `WAKE` statement above **parses and round-trips** today — its syntax is supported and CI
proves it. How far the runtime that evaluates a Wake's trigger and dispatches its delivery has
been wired is graded on its own *runtime* axis, honestly `partial`; read the state on the
[status page](./status.md) rather than assuming a supported syntax implies a running wake.

## Next

- **[First Plan](./first-plan.md)** — now that you know *when* to look, decide *what may
  fire*: a bounded-risk contingent program.
- **[Adopt](./adopt.md)** — what to reply *with* at a wake when a position must outlive the plan
  that opened it: a superseding revision that carries the held leg over with `ARM … foreach held
  leg`, so its `EXIT` is a covered close and not a naked hole. The whole loop, end to end.
- **[The shared lexical core](./lexical-core.md)** — the trigger algebra and series a Wake
  shares with the other three statement kinds.