30
Backend
06
Security
12
iOS
21
Infra

Constrain effect generation with a JSON Schema derived from the Rust types

Amended by ADR-0097
ADR-0096 AMENDED · 2026-10-25
Constrain effect generation with a JSON Schema derived from the Rust types

Decision

Have the model return effects as JSON through one strict function call, and generate the schema that constrains it from the Rust type holding the effects the model may produce. Nothing in the schema is written by hand.

The response is an object holding an array of effects. Each effect names its type first, then its fields by name, so start and end cannot be swapped. Strict mode forbids extra properties and requires every property, so an optional value is written as null; null and omitted parse to the same effect. serde remains the only parser and still rejects unknown fields. Effects only the system produces, such as enrichment, are absent because the model-facing type does not contain them.

The schema stays inside the subset OpenAI strict mode and Anthropic structured outputs both accept: anyOf for the union, enums for tags, regular expressions for ids, handles and datetimes, and date as the only format. Bounds neither provider shares, such as integer ranges and string lengths, are enforced by the parsing types. Every create writes a handle, so a later effect in the same response refers to the destination by it. S-expressions remain only as the encoding of stored effects between the app and the server.

Why

OpenAI's Responses API began rejecting our Lark grammar with "regex construction fuel exhausted". The budget is undocumented, it moved once without notice, our grammar was several times over it, and live probing found no grammar shape that fit. A schema has no such budget. It is also the one constraint both OpenAI and Claude offer, which matters because the in-app agent offers effects as tool calls on both.

We had rejected JSON at roughly twice the tokens. On recorded calls input fell about 10% per call, from 5,961 to 5,369 tokens, because the schema is smaller than the grammar. Output on calls without reasoning rose from 44 to 56 tokens, and output is about 1% of a call.

Rejected alternatives

  • Shrink the grammar until the budget accepts it. The budget is not documented, so we would be fitting to a number we cannot read, and it has already moved once.
  • Keep the grammar for OpenAI and use a schema for Claude. Two shapes of one contract drift apart.
  • Ask for JSON without a schema and validate afterwards. A malformed response costs a retry, which strict decoding cannot produce.

Consequences

A provider can change what schema it accepts without notice, and recorded tests cannot see that, so a live call with the shipped schema is the early warning. Changing the schema means re-recording the model tests, and a test fails until that is done. Claude caps optional and union-typed parameters per request, so reusing this schema there means splitting effects across tools. Strings are free text now; the grammar's alphabet excluded accented letters.