Write down what the machine costs, before it has to be worked out again

Three measurements that would otherwise be re-derived from scratch in three months, put
where a reader will meet them rather than where somebody has to know to look.

The README's cost model section says what a nominal 1 MHz actually means: about 270,000
instructions a second, since the average instruction costs 3.72 cycles. The same program
therefore takes 3.72 times the wall clock it did when a cycle was an instruction - nothing
got slower, the number got honest, and the number it replaced described no machine anybody
could build. Beside it, the two figures that put that in proportion: the emulator runs 195
million cycles a second in --fast, and CosmOS assembling CosmOS is 654 million of them,
which is eleven minutes at a megahertz, 3.3 seconds at --fast, and six and a half seconds at
a hypothetical 100 MHz. That last is pessimistic rather than hopeful: it assumes hardware
overlaps nothing, which is the same conservative reading the controller's cost model takes.

The CosmOS README gets what that means for its assembler, which is superlinear in what it
reads: 1,383 cycles a byte for a four kilobyte source, 6,290 for a hundred kilobyte one.
IT IS NOT THE DISK, and the number that says so is worth keeping - 654 million on a disk
carrying the whole source tree against 653 million on a flat one with a sixth as many files.
The suspected cause is walking a table of some nine hundred labels once per reference,
suspected rather than measured.

Nothing is being done about it, and the reason is written down too: development happens with
the host assembler. But faster hardware buys a constant factor and does not change the shape
of the curve, so the program that forces this is not CosmOS - it is the first one twice its
size.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

Programs/CosmOS/README.md

@@ -200,6 +200,29 @@ Each *name* along a path is still the 22 characters a directory entry holds, and
 one is refused rather than cut short, because a name cut to 22 characters is a different
 name that might well be some other file's.
 
+### What It Costs:
+
+**The assembler is superlinear in what it reads**, and that is worth knowing before reaching
+for it on something large. Cycles per byte of source climb with the size of the source:
+
+| Source | Bytes | Cycles a byte |
+| --- | --- | --- |
+| `colours.asm` | 4,299 | 1,383 |
+| `Edit.asm` | 16,778 | about 3,000 |
+| `cosmos.asm` | about 104,000 | 6,290 |
+
+So assembling the operating system is 654 million cycles, which is eleven minutes at a
+megahertz. **It is not the disk**: the same build costs 654 million on a disk carrying the
+whole source tree and 653 million on a flat one with a sixth as many files. The suspected
+cause is looking a label up by walking the whole table, of which there are about nine
+hundred, once for every reference - suspected rather than measured.
+
+Nothing is being done about it, deliberately. Development happens with the host assembler,
+which is where the tooling is, and the machine assembling itself is a demonstration that it
+can rather than the way anybody works. But faster hardware buys a constant factor and does
+not change the shape of the curve, so the program that eventually forces this is not CosmOS
+- it is the first one twice its size.
+
 ### The Working Directory:
 
 `cd` moves the machine. A path beginning with `/` is measured from the root and anything

README.md

@@ -166,7 +166,23 @@ anybody could build - and it is the emulator's job to be the thing the hardware
 against.
 
 The average SplitBit instruction costs 3.72 cycles, measured over the native assembler
-assembling a program.
+assembling a program. **Which is what a nominal 1 MHz means here**: about 270,000
+instructions a second, not a million. The same program takes 3.72 times the wall clock it
+did when a cycle was an instruction - nothing got slower, the number got honest, and the
+number it replaced described no machine anybody could build.
+
+Two measurements that put that in proportion, taken on the machine assembling its own
+operating system:
+
+| | |
+| --- | --- |
+| The emulator, in `--fast` | 195 million cycles a second |
+| CosmOS assembling CosmOS | 654 million cycles: 11 minutes at 1 MHz, 3.3 seconds at `--fast` |
+
+At a hypothetical 100 MHz that build is six and a half seconds, and that is a pessimistic
+figure rather than a hopeful one: it assumes hardware overlaps nothing, which is the same
+conservative reading the memory controller's cost model takes and the same one that wants
+measuring before it is designed.
 
 **The memory controller is charged for what it moves**, on the same terms. Banks are
 separate memories, and that is what sets the rate: a move between two of them can overlap