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.
24 lines (20 loc) • 1.63 kB
Markdown
# The typed TS interface is the language; text is a projection
Kestrel's canonical representation is an elegant, typed TypeScript object model — not
the text. The text DSL parses INTO it (`parse: text → objects`) and prints FROM it
(`print: objects → canonical text`, byte-stable round-trip). Consequently an ESM module
exporting typed Kestrel objects and a `.kestrel` file are the same kind of module —
mutually importable, one composition system (extends ADR-0003). We chose this over
text-as-canonical (with the AST as a parser detail) because programs, agents, and
humans all author Kestrel: agents/humans write text; programs compose objects; neither
may be second-class, and equivalence must be mechanical (round-trip), not aspirational.
Consequences: every language feature must be designed twice — its text form (English-
like, token-efficient) and its object form (typed, composable) — and the round-trip
test is part of the definition of done; serialization formats (JSON of the object
model) come for free; tooling (VS Code, linters, the runtime) targets the object model,
never re-parses text ad hoc.
The byte-stable projection includes the author's `#` **comments** — they are authored
reasoning, not decoration, so they are **PRESERVED byte-stably**, never discarded. The
comment layer is a cross-cutting sidecar on the object model, canonicalized in position
by the printer but never dropped; blank lines, being non-semantic, are the one thing the
canonical printer owns and normalizes. See ADR-0033 (the byte-stable inline-comments ADR)
for the trivia model and the canonical comment-position rules.