# 0004. The exchange seam: a codec and a loss rule per exchange ## Context Extension 3 asks for a generic service where "the only thing we need to change is the encoding/decoding on the websocket layer". By M5 everything lived in `src/polymarket/`, and M6 adds Kalshi. Most of the code is the same for any exchange (the orchestrator, the connection loop, the book thread's minute Snapshots, quiet watch and moves, the writer) or plainly per exchange (URL, handshake, message formats, market listing). One part is neither: how a loss is detected and how a symbol's two connections are merged ([0003](0003-first-one-wins.md)). Polymarket sends a hash of the whole book with every change, which both verifies our book and says where a change from either connection belongs. Kalshi has no hash: it numbers each connection's messages and gives each market a clock. These are different mechanisms, not two encodings of one. ## Decision The seam has three parts. A **shared core** (`src/core/`) that names no exchange. An **`Exchange` trait** for the websocket layer: the request, the encoding of subscribe commands, the decoding of frames, the keepalive, and the market fetcher. And, inside the book thread, a **rule supplied by the exchange**: what a symbol's book does with an event from one of its connections (a duplicate, the next change, held, a loss, a resync to ask for), with its own per-symbol state. The core understands of an event only the market it belongs to, which routes it to a book thread, and whether it is a full book, which ends a move. The event itself is the exchange's own type, handed to the exchange's rule unread: the rule folds it into the symbol's book, which is the core's and offers both ways a level changes (set to a quantity, moved by one). ## Why Decode-only, as the brief's sentence reads, would put both loss rules in the core, picked by exchange: the "generic" core would know each exchange's quirks and a third exchange would mean editing it. A whole book thread per exchange would keep the rules apart but write the minute Snapshots, the quiet watch and the moves twice. With the rule behind the seam, the core is really exchange-agnostic and the shell is written once. What the two rules still share in shape (asking for a fresh book, and again when its connection leaves or the minute passes) stays in each: their bookkeeping differs, and Polymarket's was moved, not rewritten. Trade-off: an exchange is more to write than a codec, and the seam is wider than the brief asks. The book thread's shell and the rule also meet at more points than a codec would (the minute's per-symbol questions, a connection going down), so the rule's interface is the part most likely to move when a third exchange arrives.