A cycle is an access to memory, not an instruction

cycleCount used to tick once per instruction, so RSTA cost what SETD cost and a
CALL moving ten bytes of Stack cost what a branch cost. No machine anybody could
build works that way, and the emulator's job is to be the thing the hardware is
designed against.

Every touch of memory now goes through one of four accessors that charge for it:
fetching an opcode, fetching the bytes after it, reading or writing Data Memory,
and reaching a device port. One access, one cycle, nothing overlapped. The
accessors exist so the cost is counted where the access happens rather than in a
table of per instruction costs kept somewhere else - a table like that is a
second copy of what the code does, and the two drift.

The run loop spends a budget of cycles instead of running a count of
instructions, so the emulated rate means something: an instruction costs what it
touches, and a batch ends when the cycles are gone.

What the numbers say now: RSTA 1 and SETD 4, being one byte and four. LDA 3,
DPUA 2. CALL and RET together 24, RCAL and RRET together 8, because the first
pair moves twenty bytes of Stack and the second moves four. The average SplitBit
instruction costs 3.72 of these, measured over the native assembler assembling a
program.

And the measurement that prompted all of this: converting the filesystem's
hottest leaf routine to RCAL is 3.1 per cent cheaper on a directory heavy
workload. The old model said 0.0, which is what a model that cannot see memory
traffic must say about a change that is nothing else.

Three tests moved. settle() strips the cycle count from recorded output, so
nothing should have churned - but it was anchored to the start of a line and
replCalculator's last output has no newline on it, which leaves the halt message
mid line where the pattern never reached. Not anchored any more.

The two Life programs are bounded by a cycle count because they never end, and
that number was rescaled from 3,000,000 to 11,200,000 - the same amount of work
at 3.72 cycles to the instruction. Nothing about either program changed. No limit
reproduces the old output exactly, because the cut now lands elsewhere in a
frame, so they are recorded again rather than tuned to match.

Whether hardware overlaps a fetch with the end of the previous instruction is
left open on purpose. This is the conservative model; pipelining is a decision to
make while drawing the hardware, not one to inherit from an emulator.

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

README.md

@@ -87,6 +87,25 @@ Then `dir` to see what is there, `load Snake.sbx` and `run` to play something, o
 | --- | --- |
 | `-d`, `--debug` | Single step through cycles. Each key press advances one instruction. |
 | `-c`, `--cycles N` | Stop after N cycles rather than running until the program halts. Useful for programs that never halt, and for getting the same output from a run every time. |
+
+**A cycle is one access to memory**, not one instruction. Fetching an opcode is a cycle,
+fetching each byte after it is another, reading or writing Data Memory is one, every byte a
+CALL pushes or a RET pops is one, and reaching a device port is one. Nothing overlaps -
+there is no fetching the next instruction while this one finishes - so the count is simply
+how many times the machine used the bus.
+
+That makes the numbers describe something buildable. `RSTA` costs 1 and `SETD` costs 4,
+because one is a byte and the other is four. `CALL` and `RET` together cost 24 and `RCAL`
+and `RRET` cost 8, because the first pair moves twenty bytes of Stack and the second moves
+four. Counting instructions said those were the same, which is not true of any machine
+anybody could build - and it is the emulator's job to be the thing the hardware is designed
+against.
+
+The average SplitBit instruction costs 3.72 cycles, measured over the native assembler
+assembling a program. Whether real hardware would overlap a fetch with the end of the
+previous instruction is left open, and deliberately: this is the conservative model, and
+pipelining is a decision to make while drawing the hardware rather than one to inherit from
+an emulator.
 | `-f`, `--fast` | Run as fast as the host allows, ignoring the emulated cycle rate. |
 | `-D`, `--disk <file>` | Attach a disk image, creating a 128K one if the file is not there. |
 | `-W`, `--write-protect` | Attach the disk read only. A disk whose image the host will not let you write is read only whether you ask for this or not. |