The finale of the campaign: replication and partitioning on top of the
database you already have.

serve: started as:
sql: started as:

Same two commands as every part before this one. AGENTS.md (or
README.md) carries serve:, sql: and test:, and the platform
captures all three into session memory. AGENTS.md wins when both files
declare one.

Part five adds a third argument to serve: — <command> <port> <datadir> <primary_port> starts the server as a replica of the primary
on <primary_port> — plus WAIT <n>; on the primary and
PARTITION BY RANGE on CREATE TABLE. The project description has the
full contract.

This rung also re-checks parts one through four in one pass: the server
binds and answers, the engine takes a table and rows, the storage
survives a restart on the same data directory, and an index serves a
lookup. Carry your repository forward and this rung pays on the first
probe.

A fourth word on the command line is the whole switch:

started that way, your server comes up as a replica of the primary on
127.0.0.1:<primary_port>. It binds its own port, keeps its own data
directory, and — this is what is graded here — accepts client
connections and answers a read.

The check starts a primary, creates a table on it, then starts a
replica pointed at it and asks the replica for that table. The table
came from the primary, so the replica has to have followed the primary
far enough to know it exists; it is empty, so the answer is the empty
result SELECT 0.

A replica that never finishes connecting, or that refuses connections
until some far-off moment, fails here. Come up, follow, serve.

A replica almost never joins an empty primary. It joins one that has
been taking writes for a while, and the first thing it has to do is get
a copy of what is already committed — the base backup, the initial
copy, whatever you want to call the moment before the stream starts.

The check writes several rows to the primary, and only then starts the
replica. Every one of those rows must be readable on the replica, in
insertion order, with the same SELECT <n> count the primary would
give.

The check polls the replica for a few seconds rather than demanding the
copy be instant, so a replica that accepts connections while it is
still copying is fine — as long as it finishes.

The initial copy is the easy half. The stream is the other one: rows
committed on the primary after the replica is already connected have
to arrive on it, without anybody asking for a fresh copy.

This is where WAIT earns its place in the contract:

WAIT 1; -> WAIT 1

Sent to the primary, it blocks until at least that many replicas have
acknowledged everything committed so far, then answers with how many
did. The check writes to the primary, sends WAIT 1;, and reads the
replica immediately afterwards — no sleeping, no polling. If your
WAIT returns before the rows are really on the replica, the read that
follows will say so.

A copy that accepts writes is not a copy — it is a second database that
looks like the first one until the moment it quietly stops being it.

Every statement that would change data, sent to a replica, replies with
an ERROR: line and changes nothing. As always in this campaign the
session survives: three rejected writes in a row get three ERROR:
lines, not a dropped connection.

The check sends an INSERT, an UPDATE and a DELETE to the replica,
then reads both servers. Both must still show exactly the rows the
primary wrote — the replica because it refused, the primary because
nothing reached it.

Replicas die. The machine reboots, the process is killed, the network
stalls for a minute. What matters is what happens when it comes back:
it should ask the primary for the part it missed and carry on — not
throw away its data directory and copy the whole database again.

The check writes a first batch, lets the replica take it, kills the
replica, writes a second batch while nothing is following, and then
restarts the replica on the same data directory. Both batches must
be there afterwards, in order, and WAIT 1; on the primary must
succeed again — the follower is back in the count.

Only the outcome is graded, but the data directory is handed back to
you on purpose. A replica that re-copies gigabytes because it missed
three rows is a replica nobody will run.

WAIT <n>; is the only window a client has into replication:

WAIT 1; -> WAIT 1

Sent to the primary it blocks until at least <n> replicas have
acknowledged everything committed so far, and answers with the number
that did. With a replica connected and caught up, WAIT 1; answers
WAIT 1.

The second half is the part people forget. With no replica
connected, WAIT 1; can never be satisfied — and a statement that
waits forever takes the client with it. So it gives up: after a few
seconds it answers with the count it actually got, WAIT 0, or with an
ERROR: line explaining that nobody is following. Either is accepted;
hanging is not.

Pick your own timeout, keep it under ten seconds, and make it the same
number in your code and in your documentation.

A partitioned table is one table to whoever queries it and several
tables to whoever stores it:

CREATE TABLE () PARTITION BY RANGE () PARTITIONS ; -> CREATE TABLE

The key column is INT. Partition i is named <t>_p<i> and owns the
keys from i × 1000 up to but not including (i + 1) × 1000 — fixed
slices, no bounds syntax to invent. Every INSERT goes to the
partition its key falls in.

Two things are graded. SELECT * FROM <t>; still returns every row in
insertion order, exactly as an unpartitioned table would — partitioning
is not allowed to be visible to a reader who did not ask. And each
partition is readable on its own, SELECT * FROM <t>_p2;, holding
precisely the rows whose key belongs to it and no others. Some
partitions get several rows, some get one, some get none and answer
SELECT 0.

Routing rows into partitions buys nothing until the planner uses it. A
query filtered on the partition key only has to look in one place, and
it has to be able to say so.

EXPLAIN SELECT * FROM WHERE v = 2317;

For a partitioned table, EXPLAIN prints one PARTITION <name> line
for every partition the plan will scan, in partition order, before its
EXPLAIN acknowledgement. Filtered by the key, that is exactly one
line, naming the partition that owns the value — <t>_p2 for a key of
2317, since partition i owns i × 1000 up to (i + 1) × 1000.
Unfiltered, it is all of them.

Whatever else your EXPLAIN prints from part four — index choice, scan
kind, costs — stays exactly as it was; only the PARTITION lines are
read here. The plan has to be honest: a filtered EXPLAIN that still
lists every partition, or names the wrong one, is a planner that has
not learned anything from the layout underneath it.

The rungs above proved the copy follows and the partitions prune. This
one asks how it is built, and a panel of judges reads the repository to
answer: architecture, performance, code craft, tests, and the way the
project is run.

Nothing new to implement. This is the last rung of the campaign, so
spend the time you have left where the panel looks:

• Architecture. What is the replication protocol you invented?
  Write it down as a protocol: what a replica says when it connects,
  what the primary sends, what an acknowledgement is, how a replica
  tells the primary where it stopped. Is that protocol a layer of its
  own, or is it woven through the storage and the accept loop? And is
  partitioning a routing layer with a seam — a table that dispatches to
  child tables — or a special case bolted into INSERT and SELECT?
• Performance. What does the stream cost the primary: a commit that
  blocks on a socket, a background sender, a queue that can grow
  without bound? What happens when the network stalls and a replica
  stops acknowledging — does the primary slow down, buffer forever, or
  drop the follower? What does WAIT do to a busy primary, and what
  does pruning actually save on a table with many partitions?
• Code quality. Duplication, dead branches, functions that do four
  things. Primary and replica are one binary here; if that produced two
  parallel copies of the same logic, the judge will find both. The
  measurement probes report duplication; the judge reads the rest.
• Tests. Do they start a primary and a replica and assert on
  convergence, or do they only test the pieces? Do they cover the
  failure modes — a replica that dies mid-stream, a WAIT with nobody
  listening, a write refused by a follower, a key on a partition
  boundary? A test suite that has never had two servers running has not
  tested this part.
• Technical governance. A successor has to operate this. Write
  down how to promote a replica, what to do when one falls too far
  behind, what your WAIT timeout is and why, what the durability and
  staleness guarantees really are, and how to add or resize partitions.
  Declare your conventions in tooling — a formatter, a linter, the
  test: command that really runs.

When you are done, write .ololo/distribution-done.md with a short
description of what you built and the decisions you made (at least 10
words).