Regenerating examples/programs/kv/
Every function body in the five modules of program 3 was stripped; the intents, types,
processes, signatures with their contracts, and the tests were left as written. This is the
report of writing the bodies back from mo-wiki/spec/programs/03-kv-store.md, the signatures,
and the tests.
Done-when
mo checkandmo testare green onprotocol.mo,log.mo,store.mo,server.mo, andmain.mo: 8, 14, 8, 5, and 5 tests, 40 in all, 0 failed, 0 skipped.- Every
# run:line ofmain.moprints its.expectedfile byte for byte and exits as its# exit:line says:check0,compact0,serve2,serve data/nowhere1,client 127.0.0.1 1 GET greeting1. mo test --write --sim 100has rewritten theverified:line of every module. All five also hold under--sim 100with faults: 10 process tests, 10 held under faults, 0 passed only without faults, and the threeinvariants were kept under every seed.data/compact/kv.logis rewritten by the second run and comes back byte-identical, so the worktree holds no change outside the five modules andexamples/programs/.mo.ids.
Wall clock
15 minutes 16 seconds, from reading examples/README.md to the last green run
(2026-09-16 00:13:39 UTC to 00:28:55 UTC), the commit apart.
Loops, by cause
A loop is a failing mo check, mo test, or # run: line. There were two, both on
store.mo, both at mo check, and the first edit fixed each.
| # | module | stage | code | cause | next edit | fixed |
|---|---|---|---|---|---|---|
| 1 | store.mo | mo check | MO0102 | Error(_): break — break is a statement, so it cannot be a case arm’s expression | moved break onto its own line below the arm | yes |
| 2 | store.mo | mo check | MO0304 | if nested 4 deep in faithful? (for → case → if → if); the limit is 3 | pulled the inner block into two private helpers, agreed? and next_table | yes |
Nothing else failed: protocol.mo, log.mo, server.mo, and main.mo were green at mo check and mo test on their first run, every # run: line matched its .expected file on its
first run, and no test ever failed.
Two failures outside the program, which cost no kv loop and are recorded so the count is honest:
- A scratch probe (
MO0310) settled four shapes beforeserver.mowas written: aBooldropped from a pure call is refused, but one from a call that takes a capability or a handle is not, soturn_awaymay dropsent(conn, ...); a blockif/elsemay be an arm’s value;Ok(Quit)may sit aboveOk(request)in the samecase; and a module function may share its name with a process’s state field (admitted). - The first sweep of the last four
# run:lines passed each line’s arguments as one word: zsh does not split an unquoted variable. The harness was wrong, not kv; rerun with the words given literally, all four matched.
Decisions the spec did not cover
- The signature the strip cut in half.
main.moended a line atfn check(...) : Result(String,with the continuation gone. Restored asProblem), the only return type the body and its callers admit. - The journal’s own deadline.
Journal’sFs.appendwaits 60 s, a fixed duration, not the asker’sreply_by. The store’slog_withingoverns only the ask, so a line the journal appends after the store’s deadline is still in the log — which is whatcommitted’s comment requires, and whichreply_bywould have made impossible. - Every other deadline. 10 s for an
Fsread, list, or size and fornet.connect; 30 s for a client’s silence (conn.lines(idle:)), the worker’s ask of the store, and aconn.write; 60 s for the listener’sidle:and the journal’s append. Only the 30 s client silence is in the spec. - What
STATScounts.sets=countsSETcommands that were not refused,gets=countsGETcommands;DELandINCRcount as neither.log_bytes=is the journal’s running byte count, starting at the size of the log it opened, anduptime_ms=isclock.nowless the time the store opened. The spec names the fields, not their meaning. - Keys are read in bytes. A key byte must be above 32 — which excludes the space and every
C0 control — and not 127. Bytes from 0x80 up pass, so
éis two legal key bytes and the 1-to-256 limit is a limit on bytes, as the tests read it. - A
KEYSprefix is not a key.KEYSalone andKEYSboth mean the empty prefix, which no key rule admits, sokeyed?— whichparse’sensuresreads — is true forKeys,Stats, andQuitand asks the key rules only ofSet,Get,Del, andIncr. - The table’s hash.
bucket_offolds(hash * 31 + byte) % 256over the key’s bytes: the 256-bucket spreadTOOLCHAIN-BUGS.mdrecords as the workaround for bug 2, with the parenthesised expression kept in the namedmixedfor bug 5. - An empty line in a log is
BadLine. The spec says only that a truncated last line is ignored.replaystops at any line that is not aSETor aDEL, andparse("")is malformed, so a blank line stops replay at its number — which is what the tests read. - How compaction is made safe.
compactwriteskv.compacted.logbeside the log and renames it overkv.log, so a compaction cut short leaves the old log whole. The scratch file’s name is mine; the spec says only “rewrites the log”. - Where
kv checkwrites. The folder’skv.logis only read; the changes go tokv.check.logbeside it, removed before the script and again after. A removal that fails is not an error, since the transcript does not depend on it. - A line over 64 KiB. The runtime’s
LineTooLongis answeredERR malformedand the connection goes on, matching the spec’s rule for a malformed line, which does not itself say what an over-long line gets. - A connection already closed. A worker that has closed its client ignores the lines the
runtime had already read, so the request after
QUITon the same connection is not answered — which is whatkv.expectedshows, since its lastGET hitsis a connection of its own. ERR busybefore the close. The 65th client is writtenERR busyand then closed. The count of clients inside is a process of its own,Gate, so the limit of 64 is that process’sinvariantrather than a number the listener keeps.- A full store answers
ERR full. ASETor anINCRthat would add a key to a table of 1,000,000 is refused with a newRefusal,Full, so the store’sinvariantholds without a crash. The spec names the invariant but not the answer;Refusalalready carriedFull. - What ends the program.
servealone keeps running, since the runtime owns the listener; every other command ends withplatform.exit, and stdout is flushed before it, so aserved_online is not lost. faithful?goes on after anERR io. AnERR iochanged nothing, so the model beside the store still matches and the check keeps asking; it stops only at an ask that got no answer, since the store may yet take it.mo test --write --sim 100, not plain--write.examples/README.mdsays the corpus’sverified:lines are written with--sim 100, and the corpus test runs every file that way. Plain--writewould have writtensim (not run)onlog.mo,store.mo, andserver.mo, which do have process tests; with--sim 100they recordsim (100 runs, invariants (kept 1, tripped 0)), andprotocol.moandmain.morecordsim (not run)either way.- The words on stderr.
usage()and eachProblem’s sentence are mine; no.expectedfile pins stderr, only stdout.
Private helpers written beyond the signatures left in place
store.mo: agreed?, next_table (loop 2’s fix). server.mo: told — one answer written to a
client whose connection goes on unless the write failed. main.mo: rewritten, why_unopened,
cleared.