kestrel.markets/docs/public/capability-truth.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.

# Capability truth — how to read what Kestrel claims

A public claim a reader cannot verify is a lie the repo tells. Kestrel refuses to make one.
Every capability is graded on **four independent axes**, each claim cites a source and a test
receipt, and the [status page](./status.md) is generated from that catalog — it cannot flatter
because a machine, not a marketer, writes it. This page teaches you to read it.

## Why one flag would lie

It is tempting to mark a feature "supported" and move on. But "supported" hides four
different facts that are genuinely independent:

| Axis | The question | Values |
| --- | --- | --- |
| **Syntax** | Does the grammar (`src/lang`) accept it? | `supported` · `proposed` · `rejected` |
| **Runtime** | Is the executable behavior implemented? | `implemented` · `partial` · `none` |
| **Evidence** | Is there accumulated *graded trading* evidence? | `none` · `mechanical` · `certified` |
| **Access** | Which entry surfaces reach it? | text · SDK · CLI · MCP · adapters |

A feature can **parse** (syntax `supported`) yet have no executable behavior (runtime
`none`), no graded evidence (`none`), and be reachable on only some surfaces. Collapsing
those into one word would be the flattering lie the catalog exists to forbid. The `VIEW` and
`WAKE` statements on the earlier pages are exactly this shape: their syntax is supported and
CI proves it, while their runtime axis is honestly `partial`.

## Syntax: supported, proposed, or rejected

The syntax axis has three values, and two of them are not "yes":

- **supported** — the parser accepts it, and an accepted example fence proves it in CI.
- **proposed** — reference notation not yet executable (grammar skeletons with
  `<placeholders>`). It is asserted to **fail closed** — the docs can never quietly imply the
  parser accepts sugar it does not.
- **rejected** — the parser *refuses* it on purpose, as a fail-closed doctrine. A rejected
  capability is backed by a diagnostic fence that must raise the specific error it pins (a
  budget that is not a positive risk fraction; an EXIT conditioned on a mark; the reserved
  `atomic` keyword). A refusal is a feature, and it is receipted like any other.

See [grammar-fences](./grammar-fences.md) for the accepted / proposed / rejected fence
taxonomy and the CI that holds each to its role.

## Evidence: mechanical is not certified

This is the axis most likely to be misread, so it is the one held most strictly.

- **none** — no accumulated graded-trading evidence. (Unit tests are *receipts*, not
  evidence — they prove the code does what it says, not that a strategy has edge.)
- **mechanical** — exercised end-to-end in a mechanically-graded **practice** session. It
  shows the machinery ran; it is **not** a blessed result.
- **certified** — a faithful, reproducible, contamination-fenced result at the honest tier.

> **The certified honest-tier cohort is 0.** Per kestrel-pqv.1, the agent-day evidence is
> **practice tier** — its author boundary leaked calendar identity and the contamination fence
> is conjunctive, so no result is certified. The catalog *forbids* any capability from labeling
> its evidence `certified` while the cohort is 0: a mechanical agent-day may never be dressed as a
> certified one. Every row you see marked `mechanical (practice)` is machinery that ran, never
> proven edge.

So when a page says a Plan "ran end-to-end," read it as *mechanical* — the runtime executed
it — and nothing more. Certified is a bar nothing has cleared yet, by design.

## Reading a row

On the [status page](./status.md), each capability is one row across the four axes plus a
detail block with its receipts and its example fences. To read it honestly:

1. **Start at Syntax.** `proposed` or `rejected` means the concrete grammar is not an
   accepted, running feature — it is reference notation or a deliberate refusal.
2. **Then Runtime.** `partial` or `none` means the syntax may parse while the executable
   behavior is incomplete. Do not let a supported syntax imply a working runtime.
3. **Then Evidence.** Assume `none` unless told otherwise, and treat `mechanical` as "the
   machinery ran," never as a graded win. `certified` does not appear — the cohort is 0.
4. **Then Access.** Availability differs by surface (text DSL, TS SDK, CLI, MCP, adapters);
   a capability can be `available` on one and `planned` on another.
5. **Check the receipts.** Every public claim cites a `src/` source and a `tests/` test file.
   If a claim has no receipt, CI fails — an unbacked public claim is a structural error.

## The through-line

Perception ([First Frame](./first-frame.md)), decision ([First Plan](./first-plan.md)), and
the [shared lexical core](./lexical-core.md) tell you what Kestrel *is*. This page tells you
how much of it is *real* right now — separately on syntax, runtime, evidence, and access —
so you never mistake a grammar that parses for a strategy that works. The
[status page](./status.md) is the living answer; this page is how to read it.