docs: add Maelstrom echo learning unit

docs/learning/index.md

@@ -22,6 +22,7 @@ A curated set of roadmaps and references for learning systems software in 2026.
 | "I want the design rounds — LLD + HLD" | [System design](./system-design.md) |
 | "I want to learn how databases *actually work* (internals)" | [Disk-First DB roadmap](./db-roadmap.md) |
 | "I want one mental model that covers V8, JVM, Go runtime, vLLM, Workers" | [Runtime roadmap](./runtime-roadmap.md) |
+| "I want a first hands-on distributed-systems exercise" | [Maelstrom Echo lab](./maelstrom-echo.md) |
 | "I want to see how real ML systems work in production" | [ML system design case studies](./ml-case-studies.md) |
 | "I want retrieval / search / vector / RAG depth" | 9-Day Reset → 30-Day Retrieval → 90-Day AI Search & Infra → 12-Month Advanced AI Infra (in-app `/learn`) |
 | "I want OS, cloud, containers, distributed systems, and reliability" | Systems Foundations → Infrastructure & Platforms → Distributed Systems (in-app `/learn`) |
@@ -41,6 +42,7 @@ The four AI roadmaps are one progressive curriculum at four horizons — not fou
 | [System design](./system-design.md) | catalogue | LLD patterns + HLD components + the canonical "design X" practice problems |
 | [Disk-First Databases & RAM](./db-roadmap.md) | 12-month roadmap | DB internals: storage engines, execution, distributed |
 | [Runtime — what every runtime has to do](./runtime-roadmap.md) | 12-month roadmap | Cross-cutting: V8, JVM, Go, BEAM, vLLM, Workers as one shape |
+| [Maelstrom Echo lab](./maelstrom-echo.md) | one-session lab | Request/reply envelopes, correlation IDs, and protocol-level testing |
 | [ML system design case studies](./ml-case-studies.md) | catalogue | 450 production ML write-ups, grouped by category |
 | 9-Day Reset → 12-Month AI Infra | in-app `/learn` | Retrieval, ANN, RAG, storage progression |
 | Systems Foundations → Distributed Systems | in-app `/learn` | OS, hardware, networks, cloud, containers, orchestration, reliability, workflows |

docs/learning/maelstrom-echo.md

@@ -0,0 +1,77 @@
+# Maelstrom Echo — a first distributed-systems lab
+
+← [Learning OS index](./index.md) · [Runtime roadmap](./runtime-roadmap.md)
+
+This one-session lab practices reading a wire protocol, correlating a reply to
+its request, and using a workload checker. It covers one node and one
+request/reply operation. It does not cover consensus, persistence, membership,
+or the rest of the Fly.io challenge sequence.
+
+## Before you start
+
+You should be comfortable writing a small program that reads and writes lines
+of JSON. Choose a language you already know; this repository adds no language
+runtime or Maelstrom dependency. The external exercise uses the
+[Fly.io distributed-systems challenge 1](https://fly.io/dist-sys/1/) and the
+[Maelstrom protocol](https://github.com/jepsen-io/maelstrom/blob/main/doc/protocol.md).
+Follow their current setup and safety guidance if you choose to run it.
+
+## Trace the contract
+
+Read the Echo challenge and protocol reference, then write the request and
+reply as two separate JSON envelopes. In your own words, identify:
+
+1. Which envelope fields identify the sender, recipient, and message body?
+2. Which value must the reply use to point back to this particular request?
+3. Which body field carries the exact text that must be echoed?
+4. Why should diagnostics go somewhere other than the protocol output stream?
+
+Do not copy a reference implementation. Use the contract to make your own
+small table with columns `input`, `required output`, and `invariant`.
+
+## Build and test
+
+Implement only the Echo operation in a scratch project using the language you
+chose. Read one JSON message per input line and emit one JSON response per
+line. For a request of type `echo`, preserve its payload in an `echo_ok`
+response and set the response's `in_reply_to` to the request's `msg_id`.
+Keep logs off standard output so they cannot be mistaken for protocol
+messages. Treat the protocol's initialization message as setup, not as an Echo
+request.
+
+If Maelstrom is already available in your environment, the upstream workload
+is bounded to one node and ten seconds:
+
+```sh
+./maelstrom test -w echo --bin ./your-program \
+  --node-count 1 --time-limit 10
+```
+
+Use the current command documented by the challenge if its interface changes.
+Do not run this against a service or production system; the harness launches a
+local process. If you do not have Maelstrom installed, the protocol trace and
+your own table are still useful preparation, but they are not a passing test.
+
+## Explain the result
+
+Save a short artifact beside your scratch project containing:
+
+- the input/output envelope table;
+- the exact test command and result, or “not run” with the reason;
+- one bug you deliberately considered (for example, replying with the node's
+  latest message ID instead of the request ID) and how the invariant catches
+  it;
+- a three-sentence explanation of why a correct reply needs correlation, not
+  just the original payload.
+
+The successful workload is evidence that the tested Echo contract held for
+that run. It does not demonstrate fault tolerance or correctness under
+concurrent, partitioned, or persistent workloads.
+
+## Primary sources
+
+- [Fly.io Distributed Systems Challenge 1: Echo](https://fly.io/dist-sys/1/)
+- [Maelstrom protocol specification](https://github.com/jepsen-io/maelstrom/blob/main/doc/protocol.md)
+- [Maelstrom getting-ready guide](https://github.com/jepsen-io/maelstrom/blob/main/doc/01-getting-ready/index.md)
+
+Last audited: 2026-10-02.

docs/learning/runtime-roadmap.md

@@ -205,6 +205,10 @@ Pick one. Don't pick all four.
   capability API, measure per-tenant memory limit + CPU quota
   enforcement. Output: a multi-tenant evaluator runnable in one binary.
 
+For a smaller first distributed-systems exercise, use the [Maelstrom Echo
+lab](./maelstrom-echo.md). It focuses on message envelopes and request/reply
+correlation; it does not replace the larger synthesis projects above.
+
 ---
 
 ## Cross-runtime cheat sheet

package.json

@@ -119,19 +119,20 @@
   },
   "pnpm": {
     "overrides": {
-      "brace-expansion@<1.1.18": "1.1.18",
+      "brace-expansion@<1.1.21": "1.1.21",
       "brace-expansion@>=2.0.0 <2.1.4": "2.1.4",
-      "brace-expansion@>=4.0.0 <5.0.9": "5.0.9",
+      "brace-expansion@>=4.0.0 <5.0.12": "5.0.12",
       "fast-uri@<3.1.5": "3.1.5",
       "immutable@<4.3.9": "4.3.9",
       "js-yaml@>=3.0.0 <3.15.1": "3.15.1",
       "js-yaml@>=4.0.0 <4.3.1": "4.3.1",
       "lodash-es@>=4.0.0 <=4.17.23": "4.18.1",
       "minimatch@>=10.0.0 <10.2.3": "10.2.5",
-      "nanoid@<3.3.17": "3.3.17",
-      "nanoid@>=4.0.0 <5.1.11": "5.1.11",
+      "nanoid@<3.3.18": "3.3.18",
+      "nanoid@>=4.0.0 <5.1.16": "5.1.16",
       "postcss@<=8.5.22": "8.5.23",
-      "undici@>=7.0.0 <7.29.0": "7.29.0",
+      "undici@>=5.0.0 <6.27.0": "6.29.0",
+      "undici@>=7.0.0 <7.29.1": "7.29.1",
       "sharp@<0.35.4": "0.35.4",
       "js-yaml@>=4.0.0 <4.3.2": "4.3.2",
       "smol-toml@<1.7.1": "1.7.1"

src/pages/LearningDoc.tsx

@@ -46,6 +46,10 @@ const DOC_META: Record<string, DocMeta> = {
     blurb: 'Cross-cutting view of V8, JVM, Go, BEAM, vLLM, Workers — all do the same five jobs.',
     companionRoadmapId: 'runtime',
   },
+  'maelstrom-echo': {
+    title: 'Maelstrom Echo — a first distributed-systems lab',
+    blurb: 'A one-session exercise in message envelopes, reply correlation, and protocol testing.',
+  },
   'swe-landscape': {
     title: 'The Software Engineering Landscape (2026)',
     blurb: 'One page per major systems-software domain. Vocabulary first, depth on demand.',