R0.2.1 · Valkey under the Exchange Platform — dive 1

The facade seam.

One seam holds the whole system together: every surface calls the same boundary — the echo data layer — and Valkey lives below it, never on a surface’s path. The one owned client is EchoWire; EchoCache and the EchoMQ bus ride it, both over Valkey.

Grounding: echo/apps/echo_wire (the connector + the version fence) · content/bcs3.1.md (the fence live) · bcs4.1.md (the EchoCache read path) — every figure verbatim from a committed record.

Trace a call. Pick a surface; the lit path runs to the facade and stops. Hover any node to read its part.

readout · Pick a surface. Every trace reads the same way: surface → the echo data layer → EchoWire → Valkey; no surface appears below the seam.

Static verdicts — the order API, a consumer, a worker each → the echo data layer → EchoWire → Valkey · owned clients to Valkey: 1 (EchoWire) · a surface reaching Valkey directly: never.

§1

One boundary, one return set

echo/apps/echo_wire · the master invariant

The Exchange Platform reaches Valkey through one boundary, the echo data layer. The master invariant is a rule about every surface above it: a surface calls only that boundary and reads only a typed result from a closed set. A surface never opens a socket, never holds a key, never branches on a raw store error. EchoWire — the one owned Valkey client — is below it.

The closed return set is the other half of the seam. Every call returns either a success or one of a fixed, small set of typed errors — :disconnected when the socket is gone, :overloaded when in-flight is full, {:version_fence, got} when the boot fence fails — never a raw exception. Because the set of outcomes is closed, the surface’s handling is finite. How the connector resolves a call, pipelines, and reconnects is the subject of the EchoMQ course, not repeated here.

§2

Every outcome is one of a closed set

content/bcs4.1.md

A condition below the boundary — an EchoCache L1 hit, a cold read that runs the loader once, a dropped socket, a full in-flight queue — never escapes as a raw store condition. The data layer folds each one into the closed return set, and the surface reads the typed result. The committed EchoCache walk shows the read path the seam hides:

content/bcs4.1.md · three sources of one answer · verbatimfrozen

a cold read fills (loader ran once), a warm read hits L1 without touching
the owner, and an L1 drop falls back to L2 -- the loader still ran once

Classify an outcome. Pick a condition below the seam — by button or by hovering its box; the readout names what the surface receives.

readout · Pick a condition. Every one resolves to a success or a typed {:error, reason} — no raw store condition escapes the seam.

Static verdicts — L1 hit → {:ok, …} · cold fill → {:ok, …} (the loader ran once) · socket dropped → {:error, :disconnected} · in-flight full → {:error, :overloaded}.

A failure below the boundary never reaches a surface as a raw store error. The data layer returns a success or one of a closed set of typed errors — and the surface handles exactly that.

§3

The seam at the edge — and at the wire

echo/apps/exchange · content/bcs3.1.md F3

Take one call: the order API admits an order. It calls the gateway to parse it; the gateway mints a branded id, returns a typed command or one of a closed set of errors, and the API handles the result — never a raw exception:

# A surface (the order API) calls ONLY the gateway and matches ONLY the closed error set.
case Exchange.Gateway.parse_place(raw_order) do
  {:ok, command}   -> submit(command)
  # one of six closed errors: :unknown_instrument | :bad_direction | :bad_order_type
  # | :nonpositive_quantity | :bad_price | :malformed
  {:error, reason} -> reject(reason)
end

Nowhere in the order API is there a socket, a key, or a parse branch on a raw field. And the discipline reaches all the way down: even the wire’s boot is typed at its own seam. At every connect EchoWire’s connector reads {emq}:version and refuses any other value with a typed error — the same shape as the gateway’s closed set, applied at the wire.

the application · the typed seam, twice

The edge above, the version fence below

The command’s outcomes are typed by the gateway; the connector’s boot is typed by the fence. The committed line reads the fence back through the fenced connection itself — on the emq:{q}: keyspace the bus owns.

content/bcs3.1.md · F3, the fence live · verbatimfrozen

GET {emq}:version answers echomq:2.0.0 through the fenced connector itself

Notes on ValkeyThe EchoCache L2 row is written with SET … PX, so the second layer expires itself on the server’s own clock even when no node sweeps it — PTTL 300 ms of 300 in the committed record — valkey.io/commands/set.

the invariant

A caller depends on one stable interface and a closed set of outcomes; the store behind it is an implementation detail that can change without the caller noticing.

its BCS application

Every surface calls only the echo data layer and reads a typed result; EchoWire is the one owned Valkey client below it — and its connector applies the same law to the wire with the version fence.

The seam is the master invariant the whole course respects: the surface above the boundary, EchoWire and Valkey below it, and a closed set of outcomes between them.

§4

The doors

live routes

The depth behind the boundary is taught elsewhere — the doors are live routes.

/echomq

References

sources · related

Sources

Valkey — SET — the PX option: the L2 row written with its expiry in one command.
Valkey — Programmability — atomic script execution below the seam; a transition either happened or did not.
Redis — Documentation — the command and data-type reference behind the catalog.
llmstxt.org — The llms.txt convention — the machine-readable map format the course follows.

Related in this course

R0.2 · Valkey under the Exchange Platformthe module hub
R0.2.2 · The two rolesthe next dive
R0.2.3 · The reserved tierthe tier, shipped
/echomqthe connector and the protocol in depth
/bcsthe architecture below the seam
/elixirthe functional-Elixir craft behind the umbrella