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.
98 lines (82 loc) • 6.39 kB
Markdown
# Plan v1 scope: proven core + inventory binding; atomicity reserved, never faked; gates are open-vocabulary
Kestrel's Plan surface inherits a battle-tested predecessor grammar core (WHEN / DO /
RELOAD / TP / EXIT / INVALIDATE / CANCEL-IF / ARM / ALSO; price expressions with
peg/fix, caps/floors, esc; plan chaining; EXIT's "marks lie" doctrine as a
registry-class check), validated against a privately-maintained golden-parse corpus as
the acceptance suite. That predecessor was red-teamed against sixteen lived trading
scenarios, yielding seven missing primitive families; their dispositions here:
**inventory binding is IN v1** (`basis` price anchor, held-leg quantifiers, a real
on-arm trigger) because managing pre-existing positions is a documented daily pattern
the old grammar couldn't say; **fill telemetry and instrument axes are already
solved** by path-scoped org series and `USING signal/exec`; **size modulation and
time-parameterized schedules are deferred** (conviction stays deliberately out of plan
text — a visible conviction slot invites inflation); **line continuation is solved by
an indentation-aware lexer from day one**.
**Atomic multi-leg is reserved, never faked:** the `atomic` keyword parses to a loud
rejection until a whole-structure preflight + atomic execution adapter exist. The
red-team's sharpest lesson was text that parses but lies (an iron fly accepted as four
sequential legs); Kestrel forbids that corner by refusing it, not by pretending.
**Regime gates generalize to open-vocabulary tag series.** The old `regime {…}` gate
assumed a predictor feeding a vector; Kestrel has no predictor dependency. Regime
becomes an ordinary state series written by any authorized writer at that scope
(trader-agent with logged reason, PM, app detector — a future ML model would be just
another writer). The platform defines no taxonomy — tags are opaque, agents mint them
freely (emergence through authorship: named, legible clusters instead of a model's
illegible latent ones) — and Grade culls them: a gate that doesn't beat its ungated
counterfactual in replay is refuted-as-posed.
---
## Amendment (2026-07-15): bounded risk is the platform invariant; "no naked" is an application default
The doctrine above states gates and refusals in the language: reserve rather than
fake, refuse rather than pretend. This amendment records a related ruling on the RISK
boundary — made by the owner on 2026-07-15 after live paper testing — and reconciles
ARCHITECTURE §6 invariant 1 with the platform-vs-application membership test that
ARCHITECTURE §6 itself states.
**Ruling.** "NO NAKED SHORT EVER" is an *application* policy, not a *platform*
invariant. ARCHITECTURE §6's membership test is: a thing belongs in the platform iff
violating it is *always* wrong; if two reasonable strategies could legitimately differ
on it, it is a free dial. Two reasonable strategies plainly differ on naked shorts — a
cash-secured put is a standard, respectable strategy — so "never naked" fails that test.
A hard never-naked rule is a legitimate *house* rule for a particular book; it is a smart
default, but the platform must not *prevent* an author or agent from making a
valid-but-risky trade.
**What survives — and is HARDENED — as the platform invariant: BOUNDED RISK.** Every
action must have a `max_loss` that is **computable** (never unknown, never unbounded)
**and** satisfy `size × max_loss ≤ budget`, enforced at the output boundary,
fail-closed. This single invariant already forbids exactly the always-wrong cases and
permits the merely-risky ones:
- naked short **put** — `max_loss = (strike × multiplier) − premium`, finite ⇒ *allowed*
when the budget covers it;
- naked short **call** — `max_loss` unbounded ⇒ *forbidden by bounded risk itself*;
- short **equity** — `max_loss` unbounded ⇒ *forbidden*, for the same reason.
"Never naked" is a strictly stronger, strategy-opinionated rule that buys nothing
bounded risk does not already give, while banning legitimate trades. It is therefore
reclassified:
- **Platform invariant (kept, hardened): bounded risk.** An UNKNOWN or UNBOUNDED
`max_loss` is refused. ARCHITECTURE §6 invariant 1 is revised from "Bounded risk / no
naked" accordingly.
- **Application default (new home): `no-uncovered-short`, ON by default,
author-overridable** in the Risk envelope — the same shape as `RISK day-loss 2R →
halt`. One application keeps it hard; another author turns it off and sells puts.
**Bounded by default, fail-closed — unbounded only by explicit willing-human
enablement.** Unbounded/naked risk is never a silent default. A willing human may enable
it for their agent, but ONLY through an explicit human approval act:
- **On the platform:** a human-signed Envelope scope, obtained through the same
term-sheet browser-launch flow as auth and payment. Wallet signers may **never** sign
it — enabling unbounded risk is an identity-bound, deliberately-taken act.
- **Pure-OSS / self-hosted:** an explicit, loud configuration or profile declaration —
visible and intentional, never inferred.
**Engine consequence (shipped, PR #108).** Bounded-risk enforcement reads the
*author-stated* authority rather than inventing one. The engine-minted `default`
envelope carries the SUM of the standing document's own `budget NR` lines, so a
synthesized one-shot order inherits the author's bound and can never widen it. A standing
document that states no budget *anywhere* (no POD, no BOOK, no plan `budget`) leaves
nothing to read, and the placeOrder is refused with the typed reason
`no-bounded-envelope` on the author's channel — fail-closed, with a legible reason (AX
doctrine: no refusal without a reason). The `no-uncovered-short` check continues to judge
every order at the boundary; making that default *author-overridable* in code (turning
the hardcoded sign test into "bounded-risk + policy check", and letting an instrument
with no intrinsic carry an UNKNOWN intrinsic without refusal) is follow-on engine work
tracked on kestrel-buos. This amendment records the doctrine and reconciles the docs; it
does not weaken the bounded-risk invariant, which the engine enforces fail-closed today.
Related: ARCHITECTURE §6 (invariant 1), §7 (platform vs application); kestrel-buos;
platform scope-gated Envelope signers (wallet vs human-signed).