The orchestrator, the connection loop and the book thread's shell move to src/core/, generic over an Exchange and its loss rule (ADR 0004). Polymarket runs through it unchanged. Kalshi joins: a signed handshake (KALSHI_KEY_ID_FILE, KALSHI_PRIVATE_KEY_FILE), a reconnect on a skipped sequence number, first one wins by clock and rank, and its market listing with markets tracked from three hours before they open. Breaking: the exchange is now the first argument, `engineering-challenge <polymarket|kalshi|kalshi-demo> [OUTPUT]`.
2.7 KiB
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). 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.