ADR-0025: JSON encoding is shape-aware, never value-sniffed

• Status: Accepted
• Date: 2026-06-25
• Deciders: jka
• Decision: D25

Context

Inside the core, values are Tcl dicts and strings (ADR-0011). Tcl cannot tell the string "hi there" from the two-element list {hi there}, or the string "10" from a number. A generic dict-to-JSON encoder must therefore guess types from values, which mis-types strings that happen to look like lists or numbers.

Decision

The boundary encoder never infers types from values.

• The envelope is fixed: id is a JSON string, ok is a JSON boolean, and a reply carries either result or error ({code, message}).
• result and event params default to flat objects whose values are JSON strings.
• An operation that needs another shape (numbers, arrays, nested objects) declares it: rio::wire keeps a result-encoder registry keyed by operation name, and dispatch passes the operation name with the reply. Unregistered operations use the flat encoder.
• Inbound JSON is parsed with tcllib's json::json2dict.
• rio::wire::str escapes every C0 control character, as RFC 8259 requires.

Consequences

• Encoding is total and predictable, and each non-flat result is explicit in rio-core/wire.tcl.
• A registered encoder lists its keys by name, so a key added to an operation's result is dropped on the wire unless the encoder is updated. Core tests that call the operation directly do not notice. Since ADR-0110, each encoder has a guard test that encodes the real operation's result and compares the key set.
• Events are flat objects. An event that would need nested data carries an identifier instead, and the client fetches the data (ADR-0106).