Migration

v1 is the current major. There is nothing to migrate from yet.

This page exists so that the answer to “what changes, and when?” has a stable home. The next major is not released, but its intended breaking changes are known, and they are listed here so nobody builds against behaviour that is already scheduled to change.

What the next major intends to change

Scalars stop being strings

Today every scalar from the database is emitted as a JSON string — the single largest wart on the surface. The next major returns real JSON numbers. If you currently parse these fields, that keeps working; if you compare them as strings, or rely on "0" being truthy, it will not.

This is a breaking change on nearly every response, which is exactly why it waits for a major rather than arriving as a fix.

Rate limiting starts working

A per-key hourly call limit exists in the schema and in the configuration, but the counter behind it is never incremented, so the limit does not currently trip. When that is repaired, clients that have been quietly exceeding their nominal limit will begin receiving -32002.

A method for reading your remaining quota is intended to ship at the same time, so that the first thing you learn about your limit is not that you exceeded it.

Errors get real codes

Several failures currently surface as code 0 with only a message to distinguish them. Those get assigned codes. Code 0 narrows to genuinely unclassified failures, so anything switching on it today should switch on the message until then.

What is not changing

Method names, parameter names and the envelope shape are stable within a major. Parameter names are part of the public surface — calls pass parameters by name — so they are treated as breaking to rename, not as an implementation detail.