Software Architecture, Design & Engineering by Nicholas J. Kisseberth.
Read the disk MIT's Incompatible Timesharing System ran, on a machine that has never heard of a 36-bit word. One dependency-free C99 binary, a word-packing layer proven byte-for-byte against a real RP06 pack, a geometry layer because an ITS block number is not an offset, a checker that shares no code with the reader, and a documented refusal to write a field offset that has not been checked against a source.
So the bottom layer is word packing, not byte order — a bigger abstraction than a byte-addressed filesystem needs, and the first thing built. No host integer is ever laid over image bytes: every word enters through get() and leaves through put(), masked to 36 bits.
All 39,398,400 words of a 300 MB RP06 decode and re-encode byte-for-byte, and again through a packing with a different stride. Because put() masks, that identity also measures — over the whole image — that nothing sets the 28 bits outside the word.
There is no structure header in this repo, and that is the design. Field offsets get written from sources with a citation each, never from recollection — and every packing carries its own provenance, so a layout nobody has checked against an artifact is labelled unverified by the tool itself.
The documentation
What it is, and every command
The quick reference: what itsfs is and what it does, the full subcommand list, how ITS spells a file name, and worked examples for reading a pack, writing to one, moving files through DUMP save sets, and building a file system from nothing.
The layers and the invariants
The layer cake — including the one neither sibling project needs — the eight rules that each cost somebody a bug once, the single deliberate exception to one of them, and what is deliberately out of scope.
Eight phases done, and the two hardest left
What ended each finished phase — including the one taken out of order, because ITS's own salvager turned out to need no writer — and the open questions, a pack recovered from MIT or a second FSDEFS, that would reorder the rest.
A block number is not an offset
ITS numbers blocks within a cylinder, and the division truncates — so four sectors of every RP06 cylinder are reachable by no block number at all. The layer that has no counterpart in t10fs or s5fs, and the arithmetic that finds the master file directory 3,244 sectors from where linear numbering puts it.
The format itself, and what is still unknown
The MFD whose entry positions are its pointers, one-block directories with two areas growing towards each other, a block list that is a bytecode, links stored as strings in the same field — and a gap register naming every question still open.
Not a byte-order codec
Thirty-six bits do not tile onto eight, so the bottom layer is word packing rather than byte order. The four packings, DEC's bit numbering, why SIXBIT is deliberately somewhere else, and why two packings are `corroborated` here that a sibling project calls `confirmed`.
Confirmed, observed, sourced
Kept scrupulously apart: what has been measured on a real pack, what was observed before any theory existed, what the monitor source states, and — field by field — which of it has actually been exercised.
Off the pack: tar, save sets, a mount
The three ways a file leaves an ITS pack, and the question all of them have to answer: a 36-bit word is not a byte, and there are two honest ways to make bytes out of one. Also the percent-encoding that lets a directory named `.` exist on a host, why an mtime is noon rather than midnight, why links to `>` dangle, and why a mount is read-only.
Where every constant comes from
The citation record: the one ITS file that defines this format, the licensing line and where it sits, the corroborating implementations, and two traps — a base that changes on a full stop, and documentation that gives ASCII codes for bytes stored as SIXBIT, which ITS's own code then contradicts.
How correctness is established
The levels of evidence and the axis the taxonomy was missing, the 39,641,600-word round trip, the three-way accounting that comes out exact, MIT's own salvager naming the same damaged blocks and the same files as ours, 2,000 fuzzed commands under the sanitizers — and a plain statement of everything that is not established.
Written before any code
The planning document this project is being built to: what was measured on a real pack before anything was written, what is still assumption, and the four places where copying t10fs would have been a mistake.
For the next maintainer
What to read in what order, the shape of the tree, the things not to do — one of which is silent when you get it wrong — and the known gaps stated plainly.
Documentation
    
OpenWhat the layers are, which rules are not negotiable, and what is deliberately out of scope.
OpenWhere each phase ends, and what has to be true before it can be called done. PLAN.md has the same table; this is the detail.
OpenThis layer has no counterpart in t10fs or s5fs, and it is the first place ITS turns out not to be TOPS-10 with different field names.
OpenThe format itself: what is known, how it was established, and — at the end — a register of what is still not known.
OpenWhere every constant comes from, what has been checked against a real pack, and two traps worth knowing about before reading the ITS sources yourself.
OpenHow correctness is established here, what has actually been established, and what has been found by trying.
Open