ADR-0002: The core API is a transport-independent message protocol

• Status: Accepted; amended by ADR-0030
• Date: 2026-06-24
• Deciders: jka
• Decision: D2

Context

ADR-0001 separates the core from its frontends and allows a server mode. If the core were exposed as a set of Tcl procedures called directly by the GUI, server mode would later need a second API and a second code path. The terminal frontend also carries a risk: if the Ck toolkit proves unsuitable, the TUI may have to be written in another language.

Decision

The core exposes a request/response and event-stream API designed as a protocol from the first day, independent of the transport that carries it. The same requests are served whether the caller is in the same process or at the far end of a socket.

The original plan shipped the in-process transport first. ADR-0030 removed the in-process path for frontends: a frontend always speaks the protocol over a channel. Inside the core, operations still call each other through the same dispatch without serialisation.

Consequences

• Server mode is the same core with a different transport, not a second codebase. This is what made ADR-0029 and ADR-0030 cheap.
• A frontend can be written in any language that can read and write the wire format (ADR-0011). If the Ck TUI fails, a TUI in another language can be built against the unchanged core, so the Ck spike gates Ck, not the project (ADR-0112).
• Every new operation has to be designed as structured data a terminal client could use, never as Tk-shaped payloads.