Rebuilding Apprenticeship

Sample exercise · week 1

FND-01AI OFF~6 hours

A key-value store in memory

This is the first exercise, exactly as you'd get it in your repository. Every exercise has the same parts: why it matters, the brief, how the checks run your program, and what a reviewer will look at.

Why no tools here

Everything in this track sits on a store, so you start by building the simplest one. The point is not the hash map. It is the edges: the protocol you choose, what happens with an empty key, a 10 MB value, or a client that disconnects halfway through a command. Without tools you have to decide each of these yourself, and deciding is the skill. An agent would decide silently, and you would never know a decision had been made.

This will feel slow and artificial, like arithmetic by hand for someone who owns a calculator. That's the point: you're building the reference model you'll use for years to judge code that agents write. Nobody checks whether you used AI. If you do, the only person who loses is you.

Brief

Build kvd, a key-value server that listens on TCP and speaks a line protocol you design. It must support GET key, SET key value, DEL key and KEYS prefix. Keys are UTF-8 strings of at most 256 bytes. Values are arbitrary bytes of at most 1 MiB.

Write a one-page PROTOCOL.md that someone else could use to write a client without reading your code. It must say what happens for every malformed input you can think of.

Handle at least 50 concurrent client connections. Data is in memory only for now. Restarting loses everything.

How the checks start your server

Edit run.sh so that this starts your server:

./run.sh kvd --port <n> --data-dir <dir>

Listen on 127.0.0.1:<n>. Accept --data-dir and ignore it for now (you'll use it in FND-03). Use any language. make start EX=FND-01 LANG=python (or typescript) copies a minimal starter into src/ if you want one.

Deliverables

  • kvd source, wired into run.sh
  • PROTOCOL.md, with runnable examples (below)
  • DECISIONS.md: at least five decisions you made, with the alternative you rejected for each (e.g. length-prefixed vs line-delimited values)

Writing examples the checks can run

The checks can't know your protocol, so they run the examples in your PROTOCOL.md, exactly as written. Put each example in a fenced block whose info string is kv-example:

```kv-example
> SET {k1} 5
> hello
< OK
> GET {k1}
< VALUE 5
< hello
```
Line Meaning
> text send text and a newline (\n; tag the block crlf to send \r\n)
>> text send text with no line ending
< text expect exactly this line back
<~ regex expect a line matching this regular expression
!close close the connection; later lines use a new one
# … a comment
  • Escapes work in sent and expected text: \n, \r, \t, \\, \xNN.
  • Use placeholders for keys: {k1} to {k9}. Each run gets different keys, so 50 clients can run your examples at once without colliding. {len:k1} is the length in bytes of whatever {k1} became, for protocols that length-prefix keys.
  • Tag malformed-input examples with malformed: ```kv-example malformed. You need at least three.
  • After each example the checks wait briefly. If your server sends anything the example doesn't show, that's a failure: your document should describe everything the server says.

What the checks verify

Run make check EX=FND-01. The checks:

  1. find runnable examples for GET, SET, DEL and KEYS, and at least three malformed ones;
  2. run every example against a fresh server;
  3. run your examples on 50 connections at once, 20 rounds each;
  4. send garbage, half a command, and abrupt disconnects, then check your server still answers.

What they can't judge: whether your protocol is a good design, whether your malformed-input handling is complete, binary and 1 MiB values, and the quality of your writing. Your reviewer covers those in a 20-minute explain-back.

Submitting

make submit EX=FND-01, then open the pull request it prints and mark FND-01 submitted on the website.

Want to build it, and have it reviewed?

The founding cohort works through 24 weeks of exercises like this, with a senior engineer reviewing each one.