kestrel.markets
Version:
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.
218 lines (175 loc) • 13.6 kB
Markdown
<!-- GENERATED FILE — do not edit by hand.
Regenerate from the typed capability catalog with: bun scripts/gen-card.ts
Source of truth: tests/support/catalog.ts · renderer: tests/support/card.ts
A CI test (tests/docs.card.test.ts) asserts this file equals a fresh regeneration,
that it fits the declared token budget, and that every object⇄text pair round-trips. -->
# Kestrel agent language card
A compact, receipt-backed reference for **authoring Kestrel** — one typed, token-efficient language for agentic trading with four statement kinds over one lexical core. This card is a **compiled projection of the capability catalog** (`tests/support/catalog.ts`), the same four-axis source of truth the [status page](./status.md) derives from. It claims nothing the catalog does not: every capability below is graded on syntax · runtime · evidence · access and backed by a source (`src/`) and test (`tests/`) receipt.
- **Language version:** `0.4.20`
- **Catalog hash:** `sha256:a3bb213498d60219` (full hash in `card.json`) — a drifted catalog invalidates this card.
- **Token budget:** ≤ 6000 tokens under `kestrel-card/word-punct-v1` (enforced in CI).
- **Certified honest-tier cohort:** 0 — every `mechanical (practice)` row below is a mechanically-graded practice run, never certified.
## Non-negotiables
Compactness never drops these — they are the doctrine the runtime enforces, not style.
- **Fail closed.** a parse escape stands down; an unknown series de-arms with a logged reason — never a silent default.
- **Never naked / bounded risk.** a budget is a positive risk fraction (a type); a SELL is floored at intrinsic.
- **Marks lie.** a quote is a health signal, never a value: no active EXIT conditions on the mark — mid/bid/ask/last or the human words mark/premium — and mid is never a price anchor.
- **Evidence honesty.** the certified honest-tier cohort is 0; a mechanical (practice) run is never labeled certified.
- **Text is a projection.** the typed object model is canonical; `print(parse(text))` is a byte-stable fixed point (ADR-0004).
## Statement kinds (surfaces)
| Kind | What it answers |
| --- | --- |
| `VIEW` | what should I see? — panes at a token budget, materialized as a Frame |
| `WAKE` | when should I look? — a standing subscription that spends attention, not risk |
| `PLAN` | what may execute? — a bounded-risk contingent program the runtime fires |
| `GRADE` | did it actually work? — an imperative replay reporting honest EV |
## Capabilities — four axes
A feature can *parse* (syntax) yet have no *runtime*, no graded *evidence*, and only partial *access*. These four facts are independent; a single "supported" flag would collapse them into one flattering lie.
| Capability | id | Syntax | Runtime | Evidence | Access |
| --- | --- | --- | --- | --- | --- |
| Comments (# reasoning) | `comments` | supported | implemented | none | text: available, sdk: available |
| Fail closed: atomic is reserved and refused | `fail-closed-atomic` | rejected (fail-closed) | implemented | none | text: available, sdk: available, mcp: available |
| Fail closed: budget is a positive risk fraction | `fail-closed-budget` | rejected (fail-closed) | implemented | none | text: available, sdk: available, mcp: available |
| Fail closed: no EXIT on a mark | `fail-closed-exit-on-mark` | rejected (fail-closed) | implemented | none | text: available, sdk: available, mcp: available |
| Grade statement | `grade` | supported | partial | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| Grade counterfactuals | `grade-counterfactuals` | supported | partial | mechanical (practice) | text: available, sdk: available |
| Modules & IMPORT | `module-imports` | supported | none | none | text: available, sdk: available |
| Plan statement | `plan` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| ARM (inventory adoption — the exit escape hatch) | `plan-arm` | supported | implemented | none | text: available, sdk: available, cli: available, mcp: available |
| EXIT (active out) | `plan-exit` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| INVALIDATE (thesis dead) | `plan-invalidate` | supported | implemented | none | text: available, sdk: available, cli: available, mcp: available |
| RELOAD ladder | `plan-reload` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| TP (take-profit tiers) | `plan-tp` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| Pod / Book / Risk org | `pod-book` | supported | implemented | none | text: available, sdk: available, cli: available |
| BOOK price anchors | `price-book-anchors` | supported | implemented | none | text: available, sdk: available, cli: available, mcp: available |
| Price combinators | `price-combinators` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| VALUE price anchors | `price-value-anchors` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| Byte-stable round-trip | `roundtrip` | supported | implemented | none | text: available, sdk: available |
| Trigger algebra (WHEN) | `trigger-algebra` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| USING scoped defaults | `using-defaults` | supported | implemented | mechanical (practice) | text: available, sdk: available, cli: available, mcp: available |
| View statement | `view` | supported | partial | none | text: available, sdk: available, mcp: available |
| Wake statement | `wake` | supported | partial | none | text: available, sdk: available, mcp: available |
**Access surfaces exposed:** `text` · `sdk` · `cli` · `mcp`.
## What each capability is
- **Comments (# reasoning)** (`comments`) — `#` to end of line carries the author's thinking so the WHY travels with the strategy. Comments are PRESERVED byte-stably (ADR-0004 / ADR-0033): the lexer captures them as trivia, the printer re-emits them verbatim in canonical position. No runtime semantics by design — reasoning, not behavior.
- **Fail closed: atomic is reserved and refused** (`fail-closed-atomic`) — The atomic keyword is reserved and refused in v1 — a multi-leg ticket may not claim all-or-none fills the runtime cannot guarantee.
- **Fail closed: budget is a positive risk fraction** (`fail-closed-budget`) — Bounded risk is a type: a budget must be a positive risk fraction so the position is always defined-risk. A non-positive budget is refused.
- **Fail closed: no EXIT on a mark** (`fail-closed-exit-on-mark`) — A quote is a health signal, never a value: an active EXIT may not condition on the mark (ADR-0005) — spelled as jargon (mid/bid/ask/last) or as the words a written playbook uses (mark/premium). The parser refuses all of them.
- **Grade statement** (`grade`) — An imperative replay of authored statements over recorded sessions under a named, versioned fill model, reporting honest EV.
- **Grade counterfactuals** (`grade-counterfactuals`) — Counterfactuals as syntax — VS ungated (did the gate earn its keep?), VS null (any edge at all?) — and stratified BY dimensions.
- **Modules & IMPORT** (`module-imports`) — Every document is a module; its named statements are importable by other documents (import what you reuse).
- **Plan statement** (`plan`) — A standing, bounded-risk contingent program: trigger → actions → bracket → invalidation → TTL, fired by the runtime at machine speed while the author is informed in parallel.
- **ARM (inventory adoption — the exit escape hatch)** (`plan-arm`) — A replacement plan adopts a superseded plan's held leg with `ARM [basis <px>] foreach held leg`, so it can manage and covered-exit inventory it did not open itself — never naked, never inferred from a matching strike.
- **EXIT (active out)** (`plan-exit`) — An active out on an underlying trigger (never on option marks) — giveback means the thesis is dead, get out.
- **INVALIDATE (thesis dead)** (`plan-invalidate`) — Thesis broken: stop adding, ride the bounded remainder — distinct from EXIT, which flattens.
- **RELOAD ladder** (`plan-reload`) — Add rungs into the thesis on further confirmation — worse price = better entry for a fade; the ladder IS the thesis.
- **TP (take-profit tiers)** (`plan-tp`) — Take-profit tiers on the position — bank a fraction at a multiple, resting at a value anchor.
- **Pod / Book / Risk org** (`pod-book`) — The recursive org tree — an allocating Pod (PM + envelope) over Books (the only place positions live); budgets nest, authority only narrows.
- **BOOK price anchors** (`price-book-anchors`) — bid · ask · mid · last · join · improve — queue position, not value; a dark side fails the line closed.
- **Price combinators** (`price-combinators`) — Combinators on any anchor: interpolation lean(a,b,x), guards min/max, offsets (fair-3c), tracking peg, bounds cap (buys) / floor (sells ≥ intrinsic), and time escalation esc.
- **VALUE price anchors** (`price-value-anchors`) — fair · intrinsic · basis — model worth, settle floor, and your own cost; a quote is never a value.
- **Byte-stable round-trip** (`roundtrip`) — print(parse(text)) is a byte-stable fixed point; the typed object model is canonical and text is a projection of it (ADR-0004).
- **Trigger algebra (WHEN)** (`trigger-algebra`) — The shared WHEN expression language — named series × predicates (compare, cross, held, within, velocity) × AND/OR/NOT — used by Wake, Plan, and Grade alike.
- **USING scoped defaults** (`using-defaults`) — Scoped signal/exec defaults for a document; any leg may override — composition over repetition.
- **View statement** (`view`) — The standing definition of what should be seen — which panes, at what token budget — materialized as a Frame.
- **Wake statement** (`wake`) — A standing subscription over the trigger algebra that spends attention (tokens, wakes), never risk; it delivers a View.
## Fail-closed rejects
These are refused at parse time — the illegal statement never reaches the engine.
| id | Doctrine |
| --- | --- |
| `fail-closed-atomic` | The parser raises KestrelParseError ("reserved and refused") on the atomic keyword. |
| `fail-closed-budget` | The parser raises KestrelParseError ("positive risk fraction") on a non-positive budget. |
| `fail-closed-exit-on-mark` | The parser raises KestrelParseError ("marks lie") on an EXIT conditioned on a mark — mid/bid/ask/last and their plain-English synonyms mark/premium alike. |
## Object ⇄ text (ADR-0004 round-trip)
The typed AST object **is** the language; text is a byte-stable projection of it. For every pair below `print(parse(text)) === text` (the card's test proves it). Objects are shown as JSON; the full objects for all pairs are in `card.json`.
### Wake — a standing subscription over the trigger algebra
A Wake spends attention, never risk. Its `when` is the shared trigger algebra as a typed node.
Canonical text:
```text
WAKE momentum
WHEN spot crosses above hod
```
Object (parsed AST):
```json
{
"kind": "wake",
"name": "momentum",
"when": {
"kind": "cross",
"dir": "above",
"left": {
"kind": "series",
"segments": [
{
"name": "spot"
}
]
},
"right": {
"kind": "series",
"segments": [
{
"name": "hod"
}
]
}
}
}
```
### Grade — an imperative replay with counterfactuals
`VS` counterfactuals and `BY` dimensions are syntax, not config; the object mirrors the text one-for-one.
Canonical text:
```text
GRADE plan fade OVER 2024-01-01..2024-03-31 FILL maker-fair-v1
VS ungated null
BY vehicle
```
Object (parsed AST):
```json
{
"kind": "grade",
"by": [
{
"kind": "dim-vehicle"
}
],
"fill": "maker-fair-v1",
"over": {
"kind": "corpus-range",
"from": "2024-01-01",
"to": "2024-03-31"
},
"subject": {
"kind": "grade-subject",
"name": "fade",
"what": "plan"
},
"versus": [
{
"kind": "cf-ungated"
},
{
"kind": "cf-null"
}
]
}
```
### Plan — bounded-risk contingent program (trigger → action → take-profit)
The printer elides USING-covered qualifiers and normalizes spacing; the object carries the full structure (see card.json).
Canonical text:
```text
PLAN fade budget 0.3R ttl +30m
WHEN spot crosses below vwap
DO buy 1 -1 P @ lean(bid, fair, 0.5) peg
TP 2x frac 0.5 @ fair
```
### Plan — an equity ticket (shares, not option strikes)
An equity/spot leg is `buy N shares` — the `shares` marker replaces the strike+right an option leg carries (ADR-0017); the ambient `exec` symbol is the instrument. Omit `shares` and the parser refuses `buy N @ …`, naming both continuations.
Canonical text:
```text
PLAN accumulate budget 0.5R ttl +30m
WHEN spot crosses above vwap
DO buy 100 shares @ spot
```
## Provenance
Generated from `tests/support/catalog.ts` by `tests/support/card.ts`. Regenerate with `bun scripts/gen-card.ts`. The committed card is asserted byte-identical to a fresh regeneration in `tests/docs.card.test.ts`; if you change the catalog, regenerate or CI fails.