14 Commits
Author SHA1 Message Date
dsh 5c414292d2 calc: a terminal front end -- echo, backspace editing and a prompt
The calculator now behaves like the terminal tape from the previous commit:
every character is echoed, backspace edits the digit window, Enter commits the
line and prints the next prompt, and '.' puts its result on its own line:

    > 12 34 + .
    0046
    > 12<BS>3 .
    0013
    > ^D

It is not the terminal's line buffer moved over: the calculator consumes one
character at a time, and replaying a buffered line would mean unrolling the
engine once per buffer cell, which does not fit.  Line editing here is the
digit window: backspace shifts it right by one, pads a '0' in front, echoes
"space, backspace" and keeps accumulating.

Three things had to be learned the hard way, all recorded in docs/calc.md ?8:

* a borrowed constant cell gets eaten.  KBS (the 8 that backspace subtracts)
  lived in SC+5, and the operator step erases SC..SC+6 wholesale, so the first
  byte after an operator was treated as a backspace -- every character of
  "12 34 + ." came out as an erase.  It is now loaded right before each use.
  It also must not borrow R: the EOF test writes R every round.
* set_1 only forces the low bit; cells lent to the classifier have to be
  re-initialised each round rather than assumed clean.
* the prompt after Enter has to be printed before the command dispatch and the
  operators run, because EH (the "this was Enter" flag) borrows SC+3, which
  mul uses as scratch -- the first version printed a prompt after every
  multiplication.

The tape went 64983 -> 73624 characters (+8.6k: three copies for the window
shift alone are ~4.4k, the two subtracts ~3k).  That is past the old
ROT-8-viz INS_SIZE of 65536; the current VM sizes its buffer from the tape and
runs 112802 characters at 16 bits and 336304 at 32 bits, so only the
historical budget is gone, not the ability to run it.  Ducking under 65536
again would mean dropping line editing: echo plus the Enter prompt alone is
about +2.5k, still over.

Verified: ctest 8/8 (examples_test checks the new header stream), the width
matrix at 11, 16 and 32 bits (calc stream, terminal tape and the viz's serial
output all agree; 73624 / 112802 / 336304 characters), and docs/calc.md records
step counts for the whole session list -- "12 34 + ." is 287589 steps, about
17% more than before the front end.
2026-11-19 14:27:30 +08:00
dsh c417304140 term: a line-editing terminal -- buffer, backspace and command dispatch
examples/term.r8asm was a per-character echo (prompt, echo, backspace erase,
newline, EOF).  It is now a small shell: a 4 character line buffer, a backspace
that really removes a character, and Enter -- or EOF, for a half typed line --
commits the line and dispatches on its first character.  'l' prints the length,
'r' prints the buffer backwards, 'q' quits, anything else is ignored.

The header session "lhi" exercises the whole chain: EOF commits the pending
line, so examples_test sees the '3'.  Three more sessions are documented in the
header: "rab" gives NUL+'b'+'a'+'r', "lab<BS>" gives '2' (the backspace really
dropped the 'b'), and "lhi<NL>rxy<NL>" prints '3' then the reversed second
line.

Three things ate most of the debugging time; all three are written up in the
file:

* "else" needs a flag cell.  biz enters when the low bit is set, so "if not A
  then B" cannot be inferred from "the last test missed": set FLAG=1 before the
  test, clear it in the matched branch, look at FLAG afterwards.  And biz tests
  the CURRENT dp cell, so the order has to be "set FLAG, then .tp to the
  condition cell, then biz" -- the wrong order made every character look like
  a commit key.
* clb_sub_nc eats its operands, so the echo and the append both work from the
  copy CE.  The first version appended C (already zeroed by the comparison),
  which left the line buffer empty: 'l' printed 0 and 'r' printed four NULs.
* the cell layout dominates the tape.  copy / clb_sub_nc / clb_nonzero all emit
  .tp internally, some of them inside %rep _CELL_SIZE, so a 20 cell gap costs
  a couple of thousand characters: putting the constants at 22..28 gave 33067
  characters, packing the hot cells into 0..27 gives 21721.

The buffer is left aligned with a length counter -- appending needs a dispatch
on LEN, but backspace is just LEN-- -- and 'r' prints all four cells instead of
dispatching on the length, which costs a NUL for the unused cells and is
documented.

tests/widths.ps1 now also checks term.r8asm at every width (its expected
stream is width independent, which is what makes it a good second program for
the matrix), and TODO/AGENTS/README record the item as done.
2026-11-18 21:58:29 +08:00
dsh 0c218abf32 calc: a 3 cell RPN stack -- nesting now works
The two register machine (A accumulator + P pending operand) could not nest:
"1 2 + 3 4 * + ." printed 0007 because the second operator overwrote the
first.  The calculator now keeps a 3 cell stack (S0 is the top), operators run
immediately (pop two, push one), '.' is a real peek (repeated '.' shows the
same value, and it no longer flushes anything), and ',' clears both the stack
and the depth.

Depth is counted in DEPTH because the unary minus rule needs it: '-' is unary
iff the stack is empty.  The previous "the previous character was an operator"
rule is wrong for a stack machine -- in "1 2 + -" the minus has to be a binary
subtraction (popping an empty cell yields 0, and 0 - top is exactly a
negation); treating it as unary would silently swallow the sign.  The
"have == 0" rule from the original plan was already wrong for the old machine
("2 * -5" would lose its minus).

Sizing was driven by the tape: every push/pop is one copy per stack cell
(~500 characters), and the file has to stay under 65536.  So 3 cells instead
of the 16 the TODO dreamed of: push is two copies (S2<-S1, S1<-S0), an
operator is two more (S1<-S2, then the result), and the new number is written
straight into clb_undigits' target cell (it erases N itself) so the extra
"result -> top" copy disappears -- that one was worth 540 characters.  S2 sits
in cell 33, the freed OP cell: putting it at 51 cost 3.7k in walking alone.

64983 characters (was 62624) and 246142 steps for "12 34 + ." (was 280645 --
the old settle-the-pending-OP block is gone).  The file header carries the
measured session list, the nesting cases, the stack move order (high to low,
or the source gets overwritten) and the older "2047 3 / ." caveat; docs/calc.md
gets the stack section, and SPEC 5.4/7.10 now point at DEPTH instead of NEED.
2026-11-18 21:45:00 +08:00
dsh 10f164b480 docs: the signed wrappers in SPEC, AGENTS, README and TODO
SPEC gains 7.10 with both contracts, the five design points and the measured
tape lengths; 5.4 stops saying "implementation pending" and spells out why the
range is asymmetric -- |N| can be outside the signed range while still fitting
unsigned, so 1024 has to print -1024 and the absolute value cannot be done by
clearing the sign bit.

Numbers re-measured on this machine, because some had drifted: the flagship is
62351 characters / 202159 steps (documented as 62513 / 206491), --opt takes it
to 56338, the calculator is 62624, the byte level test is 23 items over 22
macros, and asm/ has 55 macros in 23 files.

tests/widths.ps1 no longer compares the viz's serial output below 8 bit cells:
the viz prints one number per OUT there, so the 7 bit "viz FAILED" was the
script's expectation, not the tape -- the calculator itself passes at 7 bits
through r8forge_derive, and the same failure reproduces with the previous
calculator (checked against HEAD in a temp worktree).  The TODO gains the open
question of whether the flagship should keep the 65536 limit at all, plus the
evidence that a 16 bit tape of 96052 characters runs fine in the viz.
2026-11-18 21:14:07 +08:00
dsh 723b8285dd docs: record the signed number plan in AGENTS, SPEC and TODO
The four decisions are settled and the work is not done, so each fact goes where it
belongs:

  SPEC 5.4   two complement, the sign bit is _CELL_SIZE-1 (-1024..1023 at 11 bits,
             -128..127 at 8 bits, symmetric, so no |MIN| trap), display -0042,
             truncating division (the remainder takes the sign of the dividend),
             silent wraparound.  Addition, subtraction and multiplication need no
             change: the arithmetic is already modulo 2^W.
  TODO       three independently verifiable steps -- clb_digits_signed (sign test
             via clb_sub_nc against HALF = 2^(_CELL_SIZE-1), negate a copy, then the
             existing digits), clb_divmod_signed (magnitudes, unsigned divide, signs
             reapplied), and the calculator unary minus when HAVE is clear.  Each
             step lists its acceptance sweep.
  AGENTS     a short pointer so the next session sees the big queued thing.

The width trap is called out in all three: HALF must be %rep _CELL_SIZE; a literal
11 would misread the sign bit on an 8 bit machine.
2026-11-18 20:20:55 +08:00
dsh 3543003a78 digits: reorder the scratch block -- 22% fewer steps, 15% less tape
The profile said 77% of clb_digits' steps are pointer moves, so the layout of its
13 cell scratch block (S..S+12) is the cost.  The block is one rigid 7 cell unit
(clb_divmod owns its internal order: Rhi,Sd,Bo,Cm=Bc,Ci,buf,NR) plus six free
units, so the legal space is 5040 permutations.  All 5040 were assembled and run
(minimal driver, value 2047):

  old: TEN Q R [block] counter T F
  new: T1 R [block] TEN Q F counter

   tape 13,717 -> 11,717 chars (-14.6%)
   steps 145,114 -> 113,264 (-21.9%)
   pointer moves 111,958 -> 80,108 (-28.4%)   non-move steps identical (33,156)

Full 2048 value sweep: worst 164,843 -> 123,731 (-24.9%), mean 144,904 -> 112,552
(-22.3%), better on all 2048 values.  The old layout ranked 3459/5040.

Two things worth remembering.  First, ordering the units by the wrapper's first
visit order is *worse* than the old layout (150,748 steps): first visit ignores
revisit frequency -- the counter is touched once per round, TEN is copied into Bc
every round, T1 is hammered by clb_add_ip's carry chain.  Second, the n-1 lower
bound is not reachable here: 74% of the steps still execute inside clb_divmod's
block, whose order is not clb_digits' to choose, so this lever is now exhausted
(that is what the exhaustive search proves).

Min tape is not min steps either: block-first BQTRT1F1C gives the shortest tape
(10,713) but 123,890 steps.  Tape counts a .tp once, steps count its execution.

Ripple: asm/test.r8asm 64,513 -> 62,513 chars, 236,439 -> 206,491 steps, INS_SIZE
headroom ~1k -> ~3k; --opt 58,060 -> 56,350; calc --opt 52,857; calc_op 77,356 ->
69,324 chars / 599,090 -> 476,170 steps.

Verified: ctest 8/8, byte_op_test 21 items (digits 2048/2048), examples_test 18,
--opt assembles, SPEC 7.7/10.2 + AGENTS + README + docs/calc.md + docs/divmod.md
numbers updated.  New driver drv/digits_layout.r8asm keeps the measurement honest
(one clb_digits call, no output, value fed as 0=2047).
2026-11-18 17:27:05 +08:00
dsh 01aa13d0f0 tape_run --profile: the walking share is measured, not estimated
A tape run now reports, on stderr (stdout keeps the out line):

    profile: 314779 steps, 250112 of them pointer moves (79.5%)
      > 125073 39.7%   < 125039 39.7%   + 22178 7.0%   - 12395 3.9%
      [ 25121 8.0%     ] 4954 1.6%      . 7  , 10
      hottest cells (steps spent there): 11:30471 10:26446 9:25733 12:24879 ...

The flagship tape: 236441 steps, 180665 pointer moves (76.4%), hottest cells
91, 90, 92, 89, 87, 93, 88, 86, 85 -- which is exactly clb_digits' scratch block.

So the "walking is about seventy percent" line in AGENTS turns out to be right, and
now it is measured: this machine has no random access, every access costs
|delta address|, so layout is the performance knob -- which is also why the
peephole pass (that only cancels round trips) buys 17% of the steps.

TODO drops the --profile item; AGENTS gets the number and the conclusion, with the
two commands next to the other baseline entries.
2026-11-18 15:19:57 +08:00
dsh a56a12f132 r8forge --opt: the peephole pass is part of the assembler now
The pass moved out of tests/tape_opt.cc into src/tape_opt.cc with a header
(rot8_optimize(tape, cell_size)), so both entry points share one implementation:

  r8forge --opt file.r8asm > t.rot8     assemble, then optimise in memory
  r8forge_tape_opt t.rot8 t2.rot8       optimise a tape assembled earlier

--opt is peeled off argv before the rest of the parsing, so it can appear
anywhere and the existing flags are untouched; without it the output is byte for
byte what it was (flagship 64513).

Measured: flagship 64513 -> 58060 (-10.0%), calculator 62585 -> 54863 (-12.3%),
and "12 34 + ." still prints the same out stream from the optimised calculator.
ctest 8/8 still green.
2026-11-18 10:34:30 +08:00
dsh ca72e19b0b tape_opt: the peephole pass -- 10% off the flagship tape with identical output
r8forge_tape_opt rewrites a tape with three run-local rules:

  > <   a maximal run of pointer moves becomes its net displacement
  +     a run becomes (length % _CELL_SIZE), a whole turn is a no-op
  -     a run becomes (length % 2), two flips cancel

The nice part is what it does NOT do: it never looks at brackets.  '[' and ']' are
not in any of the three character classes, so they always end a run, and within a
run only the net matters (the pointer moves are pure additions and nothing in
between is observable).  Keeping every run's net keeps the pointer identical at
every surviving character, brackets included, so the pairing that the machine
finds by scanning cannot change; and since bracket characters are never added or
removed, a run can never be merged across one.  No stack, no offset table, one
linear pass.

Measured, with tape_run's out stream compared before and after (and the reference
machine on the flagship's -n stream, same 93 values):

  asm/test.r8asm      64513 -> 58060   (-6453, 10.0%)
  examples/calc.r8asm 62585 -> 54863   (-7722, 12.3%)   "12 34 + ." identical
  examples/term.r8asm  3467 ->  3402   (  -65,  1.9%)   "hi" identical

Step counts unchanged (the removed instructions did nothing).  Not yet wired into
`r8forge` itself: the pipeline is `r8forge f.r8asm > t.rot8 && r8forge_tape_opt
t.rot8 t2.rot8`, and a --opt flag can wrap that later.
2026-11-18 10:29:53 +08:00
dsh f7ac81b06f asm: clb_puts and load -- printing a sentence, and the constant helper
clb_puts REG LEN prints LEN consecutive cells as characters (the low 7 bits, which
is what serial OUT sends).  LEN has to be an assembly time constant: .tp takes a
literal address here, so "print until the cell is zero" is not expressible -- the
walk would leave the data pointer somewhere else.  Each character costs two .tp
plus one out (three or four tape characters), uses no extra cell and leaves the
source cells alone.

load N V is the helper every driver was writing by hand (erase then .xor): .xor is
an exclusive or, so a second load without the erase would mix with the old value.

  drv/puts.r8asm      198 chars, in-family check: out 72 73 33 72 (HI! plus the
                      untouched source cell)
  examples/hello.r8asm 727 chars, out 72 69 76 76 79 44 32 82 56 33, and the
                      reference machine prints "HELLO, R8!"

Both are documented in SPEC 5.2; the macro count goes 48 -> 50 and the examples 16
-> 17.  The flagship tape is untouched (64513) because asm/test.r8asm still has its
own local load -- same body, and lib's definition comes first, so nothing changed.
2026-11-17 19:55:32 +08:00
dsh 1200880d4d TODO: drop the finished items, add what the last rounds turned up
Done and removed: the desk calculator (examples/calc.r8asm -- 62585 characters at
11 bits, three implementations agree, width matrix in tests/widths.ps1), the INP
whole-cell semantic fix, and the reference machine's support for tapes above
64k.  In their place, under "interactive computing": the RPN stack (fixed depth,
because .tp is an assembly time constant -- 16 deep is about 12k of tape, 200 deep
would be 100k per push), the terminal tape (prompt, echo, line editing, one
session per `;   in` header), and clb_puts / printf so a program can print a
sentence.

New tail: ROT-8-viz still has zero tests, and its old fixed-buffer read_tape is
now unused; INS_SIZE is a historical constant next to ROT8_MAX_TAPE (16M
instructions).
2026-11-17 16:14:42 +08:00
dsh b873d71082 calc: stage 2 verified -- the digit window and clb_undigits
drv/calc_num.r8asm reads 6 characters, shifts digits into a four cell ASCII
window (D3 D2 D1 D0, most significant first) and converts it with clb_undigits
whenever a non digit arrives, then resets the window to "0000".

    in  12 34      out  12 34        tape 88413, 78908 steps
    in  0 7        out  0 7 0 0      (each EOF read is a terminator too)
    in  2047       out  2047 0
    in  9999       out  1807 0       (9999 wraps mod 2048, as the machine does)
    in  1234/0007  out  1234 0 / 7 0  (leading zeros work)

tape_run and derive agree on every case.

One deliberate departure from docs/calc.md: the digit branch copies the character
itself into the window instead of C - 48.  clb_undigits xors each cell with 48 on
the way in, so the window has to hold ASCII -- storing the numeric value paid the
xor twice (first version: "12 34" -> 540 562, e.g. 49^48=1 but 1^48=49 then * 10 +
... lands at 540).  So cell 2 (the 48 constant) and the sub_nc call are unused;
the file says so.

The window shift goes high to low (D3 <- D2 <- D1 <- D0) which is the order that
does not clobber unshifted digits; each copy is preceded by an erase of the
buffer even though this build's copy turns out to clean it itself.
2026-11-11 10:22:58 +08:00
dsh cc75ed7ea4 drop the CI pipeline, keep the local ctest
The act_runner image has no cmake and installing it per run did not get through
this network (even from a domestic mirror), so the pipeline was cost without a
green run.  Remove .gitea/workflows/ci.yml and the image recipe, keep what was
useful on its own:

  * ctest --test-dir build -j 4   runs the 8 checks in about 9 s
  * README / AGENTS now point at that instead of six commands typed by hand

TODO keeps a note: CI is paused, and ROT-8-viz is still the untested half.
2026-11-11 10:07:44 +08:00
dsh 0d08fdc838 docs: collect every leftover TODO into one file
"Not done yet" was scattered: AGENTS had a five item candidate list, docs/divmod.md
had a "no optimisation we skipped" section, README pointed at neither, and the
tree carried one genuine code marker nobody had noticed -- src/r8asm.cc:154
still says "TODO: FILL THE BLANK" above the ROT8_NODE macro (inherited from
upstream, so it is recorded rather than changed).

TODO.md now holds all of it, each item with why it matters and where to start:

  interaction   the desk calculator (input plumbing is already in place)
  tools         --opt peephole + tape diff, --profile, %synth --verify, CI
  text/picture  clb_puts + mini printf, 259 cells as a frame buffer
  skipped opts  clb_divmod's ~D precompute, clb_digits layout, the 495 char copy
  not TODOs     SPEC 12 "we already proved this cannot work" stays out of it

AGENTS' candidate section shrinks to a pointer, README gains a row in both of its
index tables, and docs/divmod.md 6 is linked from the optimisation entry instead
of being rewritten.
2026-11-09 17:22:25 +08:00