Implementations

What an implementation has to get right — the arena lifetime rule, grammar-derived completions, and what the design permits.

The reference implementation is a Go parser with no third-party dependencies. It parses both forms, converts between them, validates, and produces editor completions.

What follows is what an implementation has to get right, told through the choices that one made.

The arena lifetime rule

This is the one thing that will bite you.

The parser allocates every AST node, interned string and vector from a pre-allocated arena, which is what makes parsing allocation-free. Releasing a query returns that arena to a pool, and every pointer and every byte slice derived from the query becomes invalid at that moment — including strings that still look perfectly valid.

So: finish reading before you release. Copy anything you intend to keep. A string you extracted and stored will be overwritten by whichever query gets that arena next, and the resulting bug is intermittent, data-dependent, and looks like memory corruption because it is.

It is also why the limits are fixed rather than configurable. The arena is sized once, and every limit on that page is one of its dimensions.

If you are wrapping an arena-backed parser for another language, or holding one inside a long-lived service, copy at the boundary — once, deliberately — rather than trusting every caller to respect the rule.

Completions and diagnostics

The lint entry point takes a source string and a cursor offset and returns diagnostics with line and column spans, plus completions carrying labels, kinds and descriptions.

Derive those completions from the grammar rather than from a keyword list, and they stay correct as the language changes. That is what makes them a foundation for editor support, an MCP tool, or an in-browser editor, without reimplementing the language somewhere it will drift.

Performance

The JSON parser sustains over a million parses per second on a single core with zero heap allocations per parse. Text parsing targets two allocations or fewer.

Those numbers are a consequence of the arena, which is why the lifetime rule above exists. They are worth having only on a data-plane hot path; if you are parsing a query per user request, use the simple thing and copy freely.