Encode effects as JSON between the app and the server
Amends ADR-0096: s-expressions no longer remain as the encoding of stored effects between the app and the server.
Decision
Encode effects as JSON wherever they travel as text: in the string the app sends to apply a modification, in the string sync returns, and in the app's on-device store. The JSON is the serde encoding of the effect enum, the same one the server already writes to its jsonb log, so one encoding covers the wire, the device and the database. The model keeps its own schema-constrained shape from ADR-0096, which resolves into this enum before anything is stored.
Why
ADR-0096 moved the model to JSON and left s-expressions only on the app-to-server path, so one hop kept a second text format and a second parser library. serde-lexpr encodes a required field and an optional one differently, a dotted pair against a one-element list, so making a field optional silently changed how every effect carrying it was written on the wire and on devices. In JSON an optional field is either the value or null. Code that read effects without going through serde also had to know the s-expression syntax, and nothing the compiler checks tied that knowledge to the effect types.
Rejected alternatives
- Keep s-expressions on the app-to-server path. It saves a few bytes per effect and keeps a second parser, with its own encoding rules, for a format no other part of the system uses.
- Send effects as a structured type across the boundary instead of a string. The effect enum embeds a generic three-state patch type, which UniFFI cannot derive, so both boundaries would need parallel hand-written types that drift from the enum.
Consequences
The GraphQL schema still types effects as an opaque string, so the schema compatibility floor cannot see an encoding change. An installed build that predates this change cannot read what sync returns or write what the server accepts, and devices discard their local store of effects rather than migrate it, since there is no installed base to migrate. JSON can carry a NUL as an escape and Postgres cannot store one in jsonb, so the write rejects it as a permanent error instead of a transient parse failure.