100 Commits
Author SHA1 Message Date
dsh 7170ad4813 mechanics: what the mechanical address register costs, tape by tape
Answering "is it acceptable for shorter tapes": with the mechanical register the
cost is one physical step per pointer move, in either direction -- no direction
penalty like the drum, but every move pays.  Measured move counts at 8 bits
(tape_run --profile), and the times for a 3 ms direct drive stepper (200 steps per
rev, 3.1 steps per cell) and a 20 ms telephone uniselector:

  full_add            95 instructions      11 moves    0.03 s / 0.2 s
  hello              577                 139          0.4 s  / 2.8 s
  term             16414               13077         39 s    / 4.4 min
  asm/test.r8asm   43676               71885          3.6 min / 24 min
  signed_demo      37511              122178          6 min   / 41 min
  calc             51378              130589          6.5 min / 44 min

So short tapes are fine, comfortably: hello finishes inside a second even on the
slowest mechanism, and the practical line is about 20000 moves, which is roughly
20000 instructions, for "under a minute".  term sits right at the edge at 39 s.
The three big tapes need the two speed design: mechanical position authoritative
in single step and demo mode, a clutch that disengages it in run mode so an
electronic counter drives the 6116.  Same clutch idea as the step counter.
2026-11-20 17:20:15 +08:00
dsh 9590cfd35b mechanics: a VCR drum works as a spindle, and the numbers say only the delay
line is fast enough to be a daily machine

Size first, since that is the constraint.  A VHS head drum is 62 mm across and
spins at 1500 rpm with its own direct drive motor and a very good bearing, so it
is usable -- but as a spindle, not as a medium: its own heads are for tape, and
the video tape transport is exactly the complexity we do not want.  Strip the
heads, glue an annulus of floppy media onto the upper drum, and put two fixed
heads (cassette or stripe heads) at the rim: at 62 mm one cell is 3.0 mm of
circumference, so the heads can be crude and the read-modify-write pair sits 3 mm
apart with no machining.  A dead 2.5 inch hard disk spindle is cheaper and spins
five times faster, with a floppy head (100 um track) parked open loop over a disc
of floppy media.

What that costs in practice is now measured rather than guessed.  The 8 bit
calculator session is 166348 steps: 65311 forward pointer moves and 65278
backward ones.  On a 25 rev/s drum a forward move waits one cell (625 us) but a
backward move waits 64-k cells, about 38 ms for the usual k, so a session is 41
minutes and the flagship tape 23 minutes.  hello is 0.3 seconds.  A
magnetostrictive delay line has a full revolution of 0.5 ms instead of 40 ms: the
same session is 32 s and the flagship 18 s, because its backward move waits at
most one revolution.  So the drum is an exhibit machine, and the delay line is the
only mechanical memory that can be used interactively -- both because of the same
property, how long one lap takes.

Also recorded: what the drum needs besides the mechanism -- an index pulse, a 64x
clock resynchronised to it every revolution, a plain FM channel (one clock
transition per cell plus a data transition for a 1) read with a windowed latch,
and the second head for read-modify-write.
2026-11-20 16:54:32 +08:00
dsh a5dfd70499 docs: what a mechanical dp can actually mean when the memory is electronic
The question that exposes the gap in the previous note: if the ring lives in a
6116, what is a mechanical pointer pointing at?  The honest answer is that dp is
an address, so there are three coherent designs and they are different machines.

A. a mechanical address register.  The physical position of a 64 position device
(uniselector, or stepper plus ratchet) feeds A0..A5 of the SRAM through its
contact bank.  The position is genuinely part of the machine state and the panel
pointer does not lie, but it only selects which byte is addressed -- it is not
the byte.  Cheap (50-200 CNY) and two days of work, so it stays N1.

B. a drum.  Eight tracks by 64 cells rotating under fixed read and write heads:
then the memory itself is mechanical, dp becomes the phase of the rotation, >
waits for the next cell pulse, < waits almost a full turn, and + or - does a
read-modify-write between two heads one cell apart.  Expensive and months of
machining, but it is the 1950s machine.

C. a magnetostrictive delay line.  512 bits of sound circulating in a loop of
nickel wire with a transducer at each end: the ring is literally a loop, there
are no bearings and no heads to wear, > is free (wait for the next time slot), <
costs at most one revolution (0.5 ms at 1 Mbit/s).  An order of magnitude cheaper
than the drum and still electrically genuine, but it needs winding, biasing and
scope time.

Recommendation stays: A first because it is cheap and it is honest about being an
address register, then C if the wish is for the memory itself to be mechanical,
with B kept for when there must be a spinning drum.  The section now says all of
this, and the summary table no longer claims dp can simply "be mechanical".
2026-11-20 16:43:57 +08:00
dsh 1e7acc018e hardware: the 74LS machine gets a period bill of materials, and a mechanics plan
Two things: the TTL build is now the main target (Tang Nano looks too modern), and
the packer learned the format that makes the TTL build simple.

Format: r8forge_tape_pack --eprom writes one byte per instruction with the opcode
in the low three bits.  Then ip is the EPROM address and D2..D0 are the opcode --
no shift register, no 16 bit window, no decoder.  It wastes five bits per
instruction, and a 27C512 is exactly 64K, which is the historical instruction
budget: the 8 bit calculator (51378) and the flagship (43676) both fit.  Both
formats live in the same .r8t trailer now (format byte 1 = packed, 2 = one byte
per instruction), decode dispatches on it, and the test runs both and requires
the same output and step count.

Carrier: 74LS DIPs on a green board, 27C512 in a socket with its quartz window,
6116 SRAM, 74LS299 for the rotate, 6850 ACIA for serial, 74LS47 and four seven
segment displays on the panel, 1 MHz can oscillator.  About 31 to 40 chips, 400
to 700 CNY, a few weeks.  The FPGA stays as a bench-only stepping stone.

hardware/mechanics.md: where mechanics actually pays.  The program must stay
electronic (130 metres of paper tape for the calculator), and 512 relays for the
data ring are out, but the pointer is worth it -- > and < are 71 to 73 percent of
all steps, so a 64 position ratchet or uniselector makes the machine physically
walk the ring.  Also listed: an electromagnetic step counter (10 to 20 Hz, so
only in single step mode, with a clutch for free running), a paper tape punch or
plotter for output, a tape/card reader or plain keypad for input, and a hand crank
as the clock.  The rule that keeps this safe: mechanics only ever sit on sensor
and actuator pins and never in the logic path, and the handshake just stops the
sequencer while something moves -- since nothing in the ISA can observe time,
slower is not different.  A relay-only machine is priced honestly too: 60 to 120
relays, 10 to 50 Hz, hello in 10 to 40 seconds, the calculator in four hours, so
that one is an exhibit.

Also fixed: the synthesised macro fallback file name now carries a per-run token.
When the system temp directory is not writable every r8asm falls back to the same
working directory, so parallel ctest runs could write and import the same file --
which showed up as a random one-test failure in 0.39 seconds and nothing else.
2026-11-20 16:35:02 +08:00
dsh 9b31a51fec hardware: M0 -- the packer, the RTL, and a simulator that agrees byte for byte
The two things software cannot check by reading its own source are the 3 bit
packing and the bracket strategy, so both got a tool and a test.

New in the library (r8forge/tape.hh, src/tape.cc): the opcode numbering (taken
from ROT-8-viz enum, so the packed image and the hardware decoder cannot drift),
text <-> opcodes, opcodes <-> 3 bit bytes, the .r8t image with its trailer and
crc32, and a machine model that runs a packed tape the way a board would.  The
model takes the bracket strategy as an option: backward scan with loop stack or
not, and jump-back-onto-the-[ (the contract) or past it (what the interpreters
do).  All four combinations print the same thing, and the step count differs by
exactly the number of taken ] instructions -- which is what the test asserts.

Found and fixed while writing it: the loop stack discipline depends on the jump
convention.  Jumping onto the [ means the [ re-pushes, so ] must pop on the jump;
jumping past it means the entry must stay until the loop exits.  Mixing them up
emptied the stack on the second iteration of the calculator main loop -- caught
by the equivalence test on examples/calc.r8asm, not by reading the code.

Tools: r8forge_tape_pack (text tape -> image + --hex for $readmemh + --verify,
727 instructions become 273 bytes for hello, 62%, and the trailer sits past the
halt so address 0 of a ROM is instruction 0), and r8forge_tape_run now reads an
image directly and takes --loop-stack / --retest.

hardware/rot8.v: the 8 bit / 64 cell machine -- 3 bit opcodes from a byte
addressed memory read as a 16 bit window, a 6 bit dp with free wrap, the loop
stack bracket jump, blocking input, halt on ip == length, and a step counter that
counts instructions rather than cycles.  hardware/tb_rot8.v loads a --hex image
and prints the OUT stream in tape_run format.

Verified with Icarus Verilog 14 (the RTL against tape_run --loop-stack --retest):
  hello        577 instructions  417 steps  10 outs
  term         16414            17643      11 (fed "lhi")
  calc         51378           166741      19 (fed "12 34 + .": prints the prompt,
                                                046 and the next prompt)
  flagship     43676           100142      93
Every OUT stream identical.  ctest -R rtl_sim runs that comparison from an 8 bit
build (11 tests in the default build now, where the RTL test self-skips because
the RTL is the 8 bit machine).

Two traps worth remembering: Icarus passes plusargs through as raw bytes, so an
absolute +HEX path containing non-ASCII (this checkout is under a Chinese
directory name) arrives mangled, $readmemh silently leaves the memory empty and
the machine obediently runs LEN steps of opcode 0 printing nothing -- run vvp
from the directory holding the hex with a relative name.  And in_ready must not
be qualified with !in_valid or the input handshake deadlocks.
2026-11-20 16:25:54 +08:00
dsh 0c7d0c8754 hardware: the point is Harvard, not "no RAM" -- two ways to hold the program
Restating the constraint correctly: program and data must not share storage.  That
is already guaranteed by the instruction set, not by wiring -- none of the eight
instructions can read or write the program memory, ip only moves by one or by a
bracket jump, so there is no self modifying code and no way for data to become
instructions.  The two also wrap differently: the tape is linear and halts at the
end, the data is a ring of 64 cells.

Given a strict Harvard split, the program side has two ordinary implementations:

* in place ROM: ip is the address of a parallel EEPROM or flash (28C256, 29C010,
  39SF010), fifteen to seventeen address lines and eight data lines, no glue
  logic; the chip in a wide socket is the cartridge and there is no boot step;
* on board program RAM plus a one shot load: a separate RAM or block RAM is
  filled at reset from any small source (serial flash, microSD, UART, even a
  24C512) and then executed in place.  Swapping tapes no longer means burning a
  chip; the price is a boot state machine and one more chip.  It is still not the
  data RAM -- only the boot logic can write it, so the Harvard property holds.

Both give random access, so the bracket scan question stays about speed only, and
the loop stack is still the default because the calculator main loop wraps the
whole tape.  Media that cannot be addressed at all (mechanical tape, serial only
flash, floppy) remain useful as the source for the second variant.
2026-11-20 16:04:02 +08:00
dsh 96ef30304a hardware: execute in place -- the machine does not get a program RAM or a loader
The data ring is part of the ISA and cannot go away (64 addressable cells, one 6116
or 512 flip flops), but the program RAM and the loader are not part of the
machine: copying the tape into RAM would put another machine inside this one and
lose the premise that the tape is the program.  So the default architecture is now
execute in place: ip is the address of the tape memory, the fetched byte yields
three bits of opcode, and the bracket scans are address increments and decrements.

That works with a parallel EEPROM or flash (28C256, 29C010, 39SF010): fifteen
address lines, eight data lines, no glue logic, and the chip in a socket is the
cartridge.  On an FPGA the tape is block RAM initialised from the bitstream, which
also needs no loading step and no external chip.  LOAD then RUN stays in the
document only as an optional peripheral for media that cannot be addressed:
mechanical tape, serial SPI flash, floppy.

One consequence is now stated as a requirement rather than an option: with in
place execution a bracket scan costs a clock per instruction, and the calculator
main loop wraps almost the whole 51378 instruction tape, so a scanning ] would
cost 51 k clocks per round -- 51 ms at 1 MHz, paid on every character read.  The
loop stack implementation (pop on ], no rescan) is therefore the default, and it
is also what makes mechanical media viable at all.

The packer output is correspondingly simpler: the .bin is literally the memory
contents, ready for a programmer or a block RAM init file.  No image layout, no
FAT, no loader to write.
2026-11-20 16:01:51 +08:00
dsh e5a63d0196 hardware: the medium only has to fit in a hand -- rank the candidates by size
With LOAD then RUN settled, the medium only has to deliver 19 to 51 KB once, so a
floppy is pure overkill and the useful axis is size.  Section 9 now ranks the
candidates by area:

* a DIP-8 EEPROM or SPI flash (24C512, 25Q64) is a 10 mm square in an 8 pin socket
  -- the ROM cartridge model, no filesystem at all because the chip is the address
  space, about 3-10 CNY, writable with any CH341A class programmer;
* microSD is 15 by 11 mm and holds the whole tape library; the loader reads raw
  sectors from LBA 0, so no FAT parser is needed either (dd from a PC writes the
  card);
* a credit-card punched card at 2 mm pitch holds about 1000 instructions, which
  runs hello (577) or full_add (95) but none of the big programs -- good as an art
  cartridge, not as the main medium;
* a microcassette is 50 by 33 by 8 mm, a real small tape, 150 B/s so a 19 KB image
  loads in two minutes, drives second hand;
* the 3.5 inch floppy, 90 by 94 mm, stays only if you want the clack.

Both small options also drop the filesystem question: one reads raw blocks, the
other is memory.  A small AVR can act as the tape drive for a TTL machine behind a
DATA/STROBE handshake, and on an FPGA the loader is a few dozen lines.  The packer
gains --at-lba 0 for the card case and --i2c-image for the programmer case; only
the floppy route would need --fat12.
2026-11-20 16:00:19 +08:00
dsh 9d9d64a1d9 hardware: LOAD then RUN -- which makes a floppy a perfectly good tape
A mechanical medium is only a bad *execution* memory; real machines loaded from the
medium into RAM and ran from there.  That decouples the medium speed from the
machine: the medium just has to deliver tens of KB/s once, and execution costs no
traversal at all.  With that architecture a 3.5 inch floppy is fine, and the note
now records what is still buyable: USB floppy drives are still made (about 50-120
CNY) but only expose whole 512 byte sectors, so a small microcontroller or a Pi
acts as the host and feeds them to the machine; a 34 pin drive plus an N82077AA
class controller is the all period correct route and much more work; Gotek style
emulators are the reliable but media-less option; audio cassettes are still
sold and load the 19 KB image in about two minutes, which is plenty when the
program then runs from RAM.

A floppy can even be the executing tape: at 300 rpm and 18 sectors per track it
streams 46 KB/s, so the 51378 instruction tape goes round in 0.4 s and with the
loop stack it only ever streams forward -- but you have to do MFM decoding and
sector framing yourself, and every input character waits 0.4 s.  LOAD then RUN is
an order of magnitude simpler and a hundred times faster.

The real floppy risk is not the drive, it is the media: 20 to 30 year old disks
grow mould and lose their field, so keep several NOS disks and two copies of each
image.  The software side is small: a --fat12 disk.img output on the packer,
writing HELLO.R8T and CALC.R8T into a standard 1.44 MB image that any USB drive
can put on a real disk.
2026-11-20 15:58:39 +08:00
dsh 4f7fa63048 hardware: the medium needs +-1 iteration, not random access -- but our loops are long
Correcting an over-specification: ip only ever moves by one, and a bracket scan is
made of one-step moves, so any medium that can be iterated forwards and backwards
will do.  Taking that further, the backward half is removable too: keep a five bit
LIFO of loop entry positions, push on [ when the low bit is one, and on ] always
pop -- the popped position is the matching [, and if the low bit is one we jump
back to it (it re-runs) and otherwise carry on.  [ with a zero low bit still scans
forward, which it would anyway.  That is equivalent to the reference scan for
well formed tapes, and since scans do not count as steps the four VMs still agree
on step counts.  So a forward-only medium can execute directly.

What actually rules media out is speed.  The runtime loops in our programs are
enormous: the calculator main loop wraps almost the whole 51378 instruction tape,
so every character read walks the entire tape.  A paper tape reader at 50-300
characters per second would need 170-1000 seconds per keystroke; an audio
cassette around 130 s; magnetic tape or floppy class (30-500 k chars/s) gives 0.1
to 1.7 s; RAM needs no walk at all.  So paper tape is a demo medium (the 577
instruction hello tape is about two seconds), and the practical machine stores
the tape in RAM or block RAM.  The medium table and this analysis are in section
9, the loop-stack variant in section 4.
2026-11-20 15:56:08 +08:00
dsh 6185f39f34 hardware: spell out what the program medium has to satisfy
Nothing is committed to flash yet, so section 9 now records the constraint that
decides it: the [ skip scans forward but the ] jump scans backward, so whatever
holds the tape must support random access, or the machine has to copy the whole
tape into RAM at boot.  That is why a serial SPI flash cannot execute directly:
it only streams forward.  A parallel flash or EEPROM with an address bus can be
the tape itself (29C010 at 70-150 ns is comfortable at 1 MHz), and on an FPGA the
tape simply lives in block RAM next to the bitstream, no external chip at all.

The packed image the taper pack tool will emit is medium independent on purpose:
the same bytes initialise block RAM, program an EEPROM and drive the RTL
testbench, so M0 does not have to wait for the medium decision.  Paper tape stays
a demo medium only: at 2.54 mm pitch the 577 instruction hello tape is about
1.5 m, and the calculator tape would be 130 m.
2026-11-20 15:49:27 +08:00
dsh 0c75772cbb geometry: the ring size becomes a build option, and the machine takes 64 cells
259 was never part of the machine, just the historical default, so
kDefaultMemoryCells is now R8FORGE_MEMORY_CELLS (1..65536, default 259) with a
range guard in CMake, the same way the cell width already worked.  All five VMs
read it from geometry.hh, so nothing else had to change.

Measured the highest cell each tape in the tree actually touches by walking its
> and < and recording the peak (no tape does a < at cell 0, so none of them
depend on wrapping): calc 51, hello 49, signed_demo 34, term 27, and the
asm/test.r8asm self test 155, because it lays every macro cell block out side by
side.  So a 64 cell ring runs every program we ship; only the self test needs
the default.

Verified: the full ctest suite is 8/8 at both 128 and 64 cells (11 bit); at the
hardware geometry of 8 bit plus 64 cells the widthfree label is 5/5, and the
calculator tape is byte for byte identical to the 259 cell build and its
sessions take the same 166348 steps.  The self test also produces identical
output at 64 cells but 216 more steps, because its high cells fold back onto low
ones -- which is why SPEC section 1.2 states the rule: ring size must be at
least the highest cell a program touches plus one.

Hardware payoff: at 64 cells dp is a 6 bit counter whose wrap is free, so the
TTL build loses its modulo-259 comparator logic (four to five chips), the RAM
needs 64 bytes, and the drum shrinks to 8 tracks by 64 cells (at 3000 rpm that
is 52 s for a calculator session, so it wants to spin faster).  hardware.md is
updated to the 8 bit / 64 cell machine throughout.
2026-11-20 15:34:03 +08:00
dsh d1939a687c hardware: the machine is 8 bits, and that fixes the budget too
Decision: the physical machine uses 8 bit cells.  11 bits is half decimal
semantics and half superstition; at 8 bits a cell is a byte, so , and . are
plain byte I/O, the whole 259 cell ring is 259 bytes and fits one 6116, and the
datapath is one 74HC299 plus an XOR.

It also settles the instruction pointer problem: the 8 bit calculator is 51378
instructions, back under the historical 65536, where the 11 bit one had grown
to 73624 with its terminal front end.  Measured tape sizes and step counts at 8
bits (build8, MSVC):

  full_add          95 instructions, 36 bytes
  hello            577 instructions, 217 bytes
  term           16414 instructions, 6.2 KB
  signed_demo    37511 instructions, 14.1 KB
  asm/test.r8asm 43676 instructions, 16.4 KB, 99824 steps, 52 OUTs
  calc           51378 instructions, 19.3 KB, 166348 steps for "12 34 + ."

The note now records the 8 bit numbers next to the 11/16/32 ones, recomputes the
TTL bill of materials (20-28 chips instead of 25-35: one RAM, one shift
register, four or five ip counters), gives the drum 8 tracks instead of 11, and
adds an optional M4 that widens the machine back to 11 bits by swapping the ROM
to demonstrate that width is a build parameter rather than runtime state.
Milestone M2 now expects exactly 99824 steps and M3 expects "046" from the
calculator, both of which the software side already produces.
2026-11-20 15:18:55 +08:00
dsh 12a2254078 docs: a design note for building the machine out of silicon
docs/hardware.md turns the ISA into hardware requirements and works out what a
physical ROT-8 needs.  The load-bearing observation is that nothing in the
instruction set can observe time -- no counters, no interrupts, and the I/O
behaviours are "block until a character" and "latch the cell" -- so any
implementation that reproduces the same sequence of (ip, dp, cells, output) is
the same machine, at any clock rate and any number of cycles per instruction.
That is what makes the build tractable: a microcoded sequencer, slow memory or
even a drum are all legal.

The note pins the parts that are easy to get wrong: the exact scan boundaries
for [ and ] (the ] case jumps back onto the [ itself so it re-tests, which the
reference rot8.c gets right and a naive implementation gets wrong), the halt
condition, cells starting at zero, and the input convention -- , blocks until a
character arrives and an explicit EOF reads as 0, otherwise every interactive
read would return zero and the program would exit at once.

Budget: 3 bits per instruction, so the flagship tape is 23.4 KB of ROM and the
calculator at 11 bits is 27.6 KB; the data ring is 259 cells by W bits at most
518 bytes.  Two consequences: the instruction pointer needs at least 17 bits
because the calculator now assembles to 73624, past the historical INS_SIZE of
65536, and the 32 bit calculator (126 KB) does not fit the block RAM of the
small boards.

Three carriers are compared: FPGA first (Tang Nano 9K, about 58 KB of BSRAM, a
weekend of work), discrete TTL as the real machine (25-35 chips, 0.25-0.5 M
instructions per second, a few weeks) and electromechanical as the showpiece
(a drum with 11 tracks and 259 cells per track, read and write heads one cell
apart so a read-modify-write costs one cell time: 22 s for a whole calculator
session at 3000 rpm).  The verification plan leans on what already exists: a
packer into the 3 bit format, the RTL testbench compared against tape_run step
by step, then the panel single-stepped against an exported trace.

Nothing is implemented; the note ends with the decisions that come first --
which carrier, which width (8, 11 or 16), program storage, and whether the
physical tape form matters.  The first concrete step would be M0: the packer
plus a rot8.v testbench, which needs no hardware purchase and gives all three
carriers the same golden model.
2026-11-20 15:14:42 +08:00
dsh 1513111689 synth: measure whether the address-aware metric can shrink a real program
It cannot.  The calculator assembles to 73624 characters in the default flat
metric and 73940 with --synth-chars (identity layout), 316 more.  Three reasons,
now written down in SPEC section 3.7:

* the travel term 2*(hi-lo) is translation invariant, so moving a group of cells
  farther or nearer changes nothing; only a permutation or a spread can, and the
  contiguous identity layout is already the tightest of those;
* the library blocks are expanded at dozens of call sites with different
  addresses, so a single layout line is a guess that the real sites rarely
  match;
* the model still ignores the hop between blocks, and the exact metric tends to
  pick programs with more blocks (six blocks for the adder table against five,
  82 emitted characters against 87 -- five characters, which the other tables
  give back and more).

Cell placement is the lever that works, and it is already spent: the terminal
front end first put its borrowed classifier cells at 52..57 (77164 characters)
and moving them into 20..29 gave 73624, minus 3540.  Five single-cell moves on
the current map were measured too (T and DEPTH to 17, HAVE and CNT to 52, S2
back to 52) and every one is longer: +182, +2900, +92, +134, +3810.  So the map
is a local optimum and the only way down from 73.6k is to drop features.

The experiment left three metric-0 cache entries behind; they were deleted, so
the committed cache still holds only what the flat metric needs.
2026-11-19 14:33:25 +08:00
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 d0fd127048 build: the 32 bit toolchain builds, and 8/16 bit byte tests really pass
Two separate things hid behind "32 bit works":

* tests/byte_op_test.cc could not compile at 32 bits at all (`1 << 32` in a
  constexpr plus an int typed mask), so the whole 32 bit build stopped there --
  only `r8forge` and the core library came out.  kCellMod is now clamped at
  31+ bits and main() prints "skipped" above 16 bits (every sweep there is 2^W
  rows) and exits green.  All ten targets build at 32 bits with MSVC, and the
  same tree builds clean on a Gentoo box with GCC 16 -- the missing <cstring>
  in asm_test.cc that stopped GCC first is in the previous commit.
* the digit drivers hardcoded a 4 cell window, so byte_op_test's digits /
  digits_signed / undigits failed at every other width (16 bits wants 5 digits,
  8 bits 3).  drv/digits.r8asm, drv/digits_signed.r8asm and
  drv/undigits_byte.r8asm now derive D = _CELL_SIZE * 30103 / 100000 + 1 and
  space their cells by it, and the C++ side uses the same kDigits instead of a
  literal 4 (including the T/F cells clb_digits_signed leaves behind).

With that, byte_op_test passes at 8, 11 and 16 bits (the 16 bit run takes about
450 s) and above 16 it skips.  Two more width bugs fell out on the way: the
divmod divisor sweep used 1000 and 2047 unconditionally (they wrap at 8 bits),
and the undigits garbage guard OR'ed in bits above the cell, which at 8 bits
turned '0'+digit into a value over 255.  test_divmod_signed also divided by the
recovered divisor without re-checking it, and at 8 bits the boundary value 1024
wraps to 0 -- that was a hard crash (divide by zero), not a failure.

CMakeLists.txt now refuses -DR8FORGE_CELL_SIZE outside 1..32 at configure time;
the range used to be a comment, so an out of range width was discovered as a
compiler error in whichever file shifted by it first.  geometry.hh and SPEC
section 13 record that 32 is the ceiling because every VM stores a cell in
uint32_t -- going further means widening all five VMs, the assembler's immediate
type and ROT-8-viz's rot8_data.

Also recorded there: the %synth cache is keyed by the truth table, not the
width, so a 32 bit build hits the committed entries (0.4 s for the flagship
tape of 227075 characters).  A full cold rebuild takes ~500 s on a 44 thread
machine, 479 s of which is the single 6 parameter full adder table.
2026-11-19 13:41:59 +08:00
dsh d2da61a255 build: include <cstring> in asm_test.cc
std::strcmp needs it; MSVC pulls it in transitively so the Windows build never
noticed, but GCC 16 rejects the file.  Found while trying to build a 32 bit
toolchain on a Linux box to time the %synth cache.
2026-11-19 12:27:51 +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 4eec72953a docs: README -- the calculator is done, the terminal tape is next
The TODO summary line still advertised the interactive calculator; it has been
finished (and is now an RPN stack).  Point at docs/calc.md and list what is
really left: the terminal tape, the mini printf, the tape optimiser,
--profile, the cache check and CI.
2026-11-18 21:46:36 +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 a30a19690b calc: signed display, signed division and a unary minus
'/' now goes through clb_divmod_signed and '.' through clb_digits_signed, so
the accumulator can be negative: "3 5 - ." prints "> -0002", "-5 2 * ."
prints "> -0010" and "-7 -2 / ." prints "> 0003".  Add, subtract and multiply
needed nothing -- mod 2^W arithmetic is already two's complement correct.

The one new piece of state is NEED, "a new operand is expected": expression
start, just settled, just after an operator, just after ','.  A '-' with
NEED == 1 is unary: set NEG, clear ISCMD (so step 3 leaves OP alone), and the
next number is negated in the flush.  NEED == 0 means P already holds an
operand waiting to be settled, so '-' stays the binary minus.

The original plan was "HAVE == 0 means unary", which is wrong: HAVE only says
"digits are being accumulated", so after "2 *" it is 0 too and the minus in
"2 * -5 ." would be parsed as a subtraction.

Two consequences worth knowing: 2047 is now -1, so "2047 3 / ." correctly
prints "> 0000" instead of the old unsigned 0682 (write "1023 3 / ." for 341),
and the printable range is -1024..1023.  The tape grows 59519 -> 62624
characters: the two wrappers plus the NEED/NEG judging.

The file header carries the measured sessions with their step counts and the
three cells the signed macros needed (T1 48, T2 49, SG 50), and examples_test
still checks the "12 34 + ." line.
2026-11-18 21:14:00 +08:00
dsh 1f3f453e88 signed: the two two's complement wrappers, with exhaustive sweeps
clb_digits_signed N REG S T F prints '-' (45) and then |N| as the same four
zero padded digits; clb_divmod_signed N D Q R S T1 T2 F is the C style
truncated division (q = trunc(n/d), r = n - q*d, remainder follows the
dividend).  Both are wrappers: clb_digits / clb_divmod still do the work, so
the tape only grows by the sign handling -- 572 characters for the display
(12151 vs 11579 in the same driver layout) and 1191 for the division
(6018 vs 4827).

The sign bit is read with rol + bit_copy + ror, 49 characters.  clb_bit_mov is
deliberately NOT used: it eats the source bit, so N comes back as N - HALF and
1024 -- whose magnitude 1024 only fits the unsigned range -- prints as 0000.
A clb_sub_nc against a HALF constant was the other candidate: 765 characters
for the call plus ~60 for the constant cell.

A flag has to outlive the block that consumes it, because biz/rnz only exit
once the body clears the condition bit.  So sign(N) is moved into T2, sign(D)
into F, and the remainder block flips F into sign(N)^sign(D) on its way out;
a single conditional negation of the quotient then carries the xor.  The
negation scratch is S+6: the only cell in S with a "clean on entry" contract,
and clb_neg_ip leaves it zero again for clb_divmod.

Verified by r8forge_byte_op_test: all 2048 values for the display (worst
117606 steps) and 4202 division pairs -- every |a|,|b| <= 32 plus the
0/+-1/+-1023/+-1024 boundary combinations -- compared against C's / and %.
examples/signed_demo.r8asm is the single point regression that runs as a
program (the flagship cannot carry them: +12.1k / +5.6k on a 62351 tape).
2026-11-18 21:13:52 +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 3ac4ede73d AGENTS: the machine semantics are frozen except for INP/OUT
The owner stated the rule plainly: apart from INP/OUT (which are host interface
decisions), machine semantics do not change unless explicitly asked -- the eight
instructions, biz/rnz testing the LSB, + rotating right, - flipping the low bit, how
steps are counted, the 259 cell ring, running from the first instruction to the end
of the tape.  The reason is that three implementations cross check each other and
none of them is a second specification: a "harmless" tweak in one makes the other
two look broken, with nothing to adjudicate.  Changing semantics means writing it in
SPEC first and changing all four machines together (SPEC 13); otherwise only tools
and views may change.
2026-11-18 18:57:09 +08:00
dsh c0e98eb2f4 AGENTS: a stale rot8_test.exe looks like a broken tape
The other machine's ROT-8-viz was three commits behind and still had the old serial
INP ("only the low 7 bits change, leave the rest alone"), so the calculator printed
> 0000 there while the same 62800 character tape printed > 0005 in the current
checkout.  Recompiling "fixed it by magic" -- it was the whole-cell INP commit.

Worth writing down because the failure mode is deceptive: viz is the authority, so
a stale authority looks like a program bug.  The bullet now says to verify the
binary is fresh first, and names the symptom.
2026-11-18 18:44:35 +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 55ab5dfebd examples: the terminal tape -- prompt, echo, newline, backspace, EOF
examples/term.r8asm is the "type at it and it answers" program: it prints "> ", then
echoes every character the machine reads, prints a fresh prompt after each newline,
and answers a backspace with space + backspace so the cursor erases the glyph.
EOF (the 0 that inp returns when the input is gone) erases the loop quota, so the
loop ends and the tape runs off its end after one final newline.

  tape 3467 characters, 4743 steps for a two line session (the calculator is 62585)

Measured (derive and tape_run, then the reference machine's serial output):

    in  hi            out 62 32 104 105 10                       "> hi\n"
    in  hi<LF>ok      out 62 32 104 105 10 62 32 111 107 10      two prompts
    in  h<BS>i        out 62 32 104 8 32 8 105 10                the 8 32 8 pair

All three character streams agree with ROT-8-viz byte for byte (bar CRLF).
r8forge_examples_test passes all 18 examples.

One thing worth recording: my brief for this said "a body entered on LSB==0 needs no
clear" -- that is backwards, `[` *jumps* on LSB==0, so bodies are entered on LSB==1.
Following it inverted the dispatch (EOF fired with C=0x68) and it took a
`tape_run --trace` to see it; the file now documents the real rule next to the loop.
2026-11-17 20:31:36 +08:00
dsh 67a2b16721 docs: 53 macros, and they live in 23 files now (puts_dyn.r8asm is new) 2026-11-17 20:11:11 +08:00
dsh a1f88e3d25 asm: raw_puts_dyn -- print a buffer whose length is only known at run time
A terminal has to echo the line the user just typed, and that length is a cell, not
a constant; clb_puts cannot do it because .tp takes a literal address.  So this one
walks MAX compile time slots and decides per slot whether to print: CNT starts as a
copy of LEN, clb_nonzero turns "CNT != 0" into the flag F, and the print happens
inside `biz F` with the countdown *inside* the guarded body as well.

That last detail is the whole bug this round: with clb_dec_ip outside the guard, a
CNT of 0 wrapped to 2047 on the first skipped cell and the rest of the buffer came
out (LEN=0 printed E F G H).  The fix is also why the driver covers LEN = 3, 0 and
8 -- the zero case is what caught it.

  drv/puts_dyn.r8asm   13376 chars, out 65 66 67 65 66 67 68 69 70 71 72 (ABC, nothing, ABCDEFGH)
  reference machine    "ABCABCDEFGH"     6306 steps

Also learnt: `copy` takes two arguments (%this is the source), and it wants a clean
buffer -- the first version passed three and then reused a dirty T, which showed up
as a countdown that started from the wrong value.

Not in asm/test.r8asm: an 8 slot version costs thousands of characters and the
flagship is about a thousand under the 65536 limit.  SPEC 5.3 records the contract
and that exception; the macro count is 53.
2026-11-17 20:11:01 +08:00
dsh 37d1dca0c7 docs: the macro count is 52 (48 + load + clb_puts + test.r8asm's local load twice over) 2026-11-17 19:55:47 +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 ba5a8a465d tests/widths.ps1: assert the calculator at every width, not just print it
The script used to build the toolchain per width, run the widthfree label and
print whatever the calculator produced.  It now checks:

  * widthfree ctest label passes;
  * examples/calc.r8asm assembles, and `12 34 + .` prints exactly D digits where
    D = floor(W * 30103 / 100000) + 1 -- the width's digit count, computed the same
    way the library computes it.  A build that silently ignored the width would
    print four digits and fail here instead of looking green;
  * if ROT-8-viz is built next door, it runs the same tape and prints the same
    thing, which makes the three way check part of the matrix.

Also fixes the invocation: `-Widths` is a comma separated string now, because
`powershell -File ... -Widths 11,16` binds as one string and 11,16 became 1116.

Measured at cell 11 (the default): widthfree ok, tape 62585, calc ok
`out 62 32 48 48 52 54 10`, viz ok `> 0046`.  Default list is 7,8,11,16,17,31,32;
each width is a full toolchain build, so the whole run is about twenty minutes.
2026-11-15 18:47:21 +08:00
dsh a69260522b geometry: kDefaultCellSize now really reads R8FORGE_CELL_SIZE
The build option was plumbed all the way to the compiler (the generated vcxproj
carries R8FORGE_CELL_SIZE=17) but geometry.hh still said = 11, so every width
built an 11 bit toolchain -- which is why the first matrix run printed identical
tapes for all nine widths.  My earlier '16 and 32 verified' claims were therefore
measurements of 11 bit binaries: synth_test and full_add are bit level blocks whose
tape does not depend on the width, so they never noticed.

Now at -DR8FORGE_CELL_SIZE=17: asm/test.r8asm 108789 characters (64513 at 11),
examples/calc.r8asm 112795 (62585), and one session prints '> 000046' -- D is 6 at
17 bits, which is exactly floor(17*log10 2)+1.

tests/widths.ps1 now prints the flagship and calculator tape lengths, because that
is the evidence that a width took effect; an unchanged 64513 means it did not.
2026-11-15 17:32:55 +08:00
dsh e137b09958 tests/widths.ps1: do not pipe native stderr into the output stream
The first run died at cell 1: with ErrorActionPreference=Stop a native command
whose stderr is captured through the pipeline becomes a terminating ErrorRecord,
so r8asm's harmless 'cached, 5 blocks' line killed the script.  Native calls now
report through LASTEXITCODE and their stderr goes to \; the configure no
longer passes CMAKE_BUILD_TYPE, which the Visual Studio generator ignores anyway
(it printed a warning per width).
2026-11-15 16:25:56 +08:00
dsh b7de3cad23 calc: the digit window follows _CELL_SIZE
The desk calculator hardcoded a four cell window, which is only right at 11 bits:
clb_digits and clb_undigits use D = _CELL_SIZE * 30103 / 100000 + 1 digits (3 at 8
bits, 5 at 16, 10 at 32).  D is now a .var, the window is REG..REG+D-1, every cell
after it moves by D-4 (zero at 11 bits, so the numeric map is unchanged), and the
startup fill, the shift chain, the flush reset and the D outputs are all %for
generated.

Two more width hardcodes turned up outside the window and are fixed: the C restore
after the four-ror bit 4 test was `%rep 7` (only 4+7=11 at the default), it is
`%rep _CELL_SIZE - 4` now -- which emits the same seven rors at 11 bits, so the
tape is byte for byte identical (62585 characters, every step count unchanged).

The literal descending shift was tried first and assembles fine but is wrong:
writing REG+D-2 before reading it clobbers the digit that is about to move, giving
"> 0350" for 12 34 + . instead of "> 0046".  The chain goes ascending, which is the
exact generalisation of the old four copy chain.

tests/widths.ps1 builds the toolchain at 1 2 7 8 11 16 17 31 32 bits, runs the
widthfree label at each and, where the ASCII constants fit (>= 6), runs one
calculator session.  1 and 2 cannot: '0' is 48 and a two bit cell holds 3.

Verified at 11 bits: tape unchanged, all five sessions identical, derive agrees,
r8forge_examples_test 16/16.
2026-11-15 16:22:50 +08:00
dsh b497bf0637 examples: the desk calculator -- 12 34 + . -> > 0046
The five stage drivers are now one program.  examples/calc.r8asm is a two
register desk calculator: digits build a number, + - * / set the pending
operator, . prints the accumulator (`> 0046` + newline) and , clears it.  EOF (the
0 that inp returns when the input runs out) erases the loop counter, so the loop
ends and the tape simply runs off its end.

    in 12 34 + .   out 62 32 48 48 52 54 10       (> 0046)   314777 steps
    in 2047 3 / .  out 62 32 48 54 56 50 10       (> 0682)   362281
    in 7 6 * .     out 62 32 48 48 52 50 10       (> 0042)   299352
    in 9 4 - .     out 62 32 48 48 48 53 10       (> 0005)   292030
    both of the first two in one session          659759 steps

62585 characters, under ROT-8-viz's 65536 for the first time in this series, so
the whole calculator can be cross-checked against the reference machine later.
tape_run and derive agree, r8forge_examples_test passes all 16 examples, ctest 8/8.

Four deliberate departures from docs/calc.md, each forced by a measurement:

  * settle before loading the new operand, and `.` settles too -- the literal
    order printed 0034 for 12 34 + . because the space arrives before the + and
    overwrites A;  * the operator is one-hot (1 2 4 8) so settlement is four flat
    mutually exclusive biz blocks;  * the loop quota is refilled each round
    (clb_ones can only make _CELL_SIZE ones, 11 here) instead of a fixed 128;
  * three cell moves worth ~24k of tape: clb_undigits scratch 35..45 -> 5..15
    (next to the window it decodes), result/display target 0 -> 20 (adjacent
    scratch makes the %synth blocks shorter), 35..45 reused as one shot flags.

Also found a trap worth remembering: a biz body that ended with `.tp B1; set_0`
(condition cell is FLAG) has net displacement +2, and only on the skipped path
does it desynchronise every later .tp -- the symptom was `-` and `,` sending the
tape into the weeds.  Net displacement 0 on both paths, always.
2026-11-15 16:03:45 +08:00
dsh f9821f8989 calc: stage 4 verified -- four operations, one shared scratch block
drv/calc_op.r8asm computes one case per operation and displays it with the stage 3
prompt, so the arithmetic path of the calculator is proven:

    +  12 34  ->  46        *  12 34   -> 408
    -  100 30 ->  70        /  2047 3  -> 682

    out 62 32 48 48 52 54 10 | 62 32 48 48 55 48 10
        62 32 48 52 48 56 10 | 62 32 48 54 56 50 10

tape 77356 characters, 599090 steps, tape_run and derive agree on all 28 values.

The useful result is the memory map: the four macros want different scratch, and
one 7 cell block (23..29) serves all of them -- add/sub use its first cell as the
carry, clb_mul uses exactly those 7 as Ci PH MCA S T F NR, clb_divmod uses the same
7 as its S.  They never run at the same time, so one erase before each call does
for all three.  The result cell is the display's N cell directly (add/sub write S
there, mul writes PL, divmod writes Q), which saves a copy per case.

Contract probes confirm SPEC: add leaves the carry output 0, sub reports no-borrow
1, mul keeps MC and eats MUL, divmod keeps N and D and puts the remainder in R.

Over ROT-8-viz's 65536 limit (four expanded clb_digits blocks), so it is verified
through the two r8forge machines only; stage 5 loops the display, so the real
calculator will be smaller than this.
2026-11-11 11:18:41 +08:00
dsh b2ba20b885 vms: raise the step cap from 5M to 20M
5 million steps was picked when the worst macro (clb_add_ip with B=2047) sat just
under a million, so it caught hangs quickly.  The interactive programs changed the
arithmetic: one printed line of the desk calculator costs about 225k steps (40k
for clb_undigits, up to 32k for the operation, ~141k for clb_digits), which is only
about twenty lines before the cap, and examples_test applies the same cap to every
example.

At roughly 2.3e8 steps per second a 20M cap costs 0.09 s when a program really does
run away, and byte_op_test (the only place that runs 465k programs) is unchanged --
so the safety net stays cheap while a session gets four times the room.

docs/calc.md, docs/divmod.md, docs/byte-ops.md and SPEC's "500 ?" mentions now say
2000 ?.
2026-11-11 11:04:14 +08:00
dsh b83f3b1b06 calc_disp: correct the header's tape and step count
The numbers written into the header came from an earlier revision of the file (it
had the display body in there twice as long).  Measured on what is committed:

    tape 29188 characters, 282288 steps for the two prints

which is also what makes it fit under ROT-8-viz's 65536 instruction limit.  The
out line was correct either way, which is why the mistake survived until the tape
was measured against the committed file.
2026-11-11 11:00:53 +08:00
dsh bb1a434586 calc: stage 3 verified -- prompt, four digits, newline
drv/calc_disp.r8asm prints `> ` plus a number in decimal, twice (46 and 2047), so
the display path of the calculator is proven end to end:

    out 62 32 48 48 52 54 10 62 32 50 48 52 55 10
        >  sp  0  0  4  6  LF    >  sp  2  0  4  7  LF

tape 58382 characters, 564578 steps (two clb_digits calls dominate), tape_run and
derive agree.  This one fits under ROT-8-viz's 65536, unlike the two %rep 16/6
drivers.

The probe also pinned down which scratch really is sensitive: with cell 0 or the
four REG cells preset the output does not change (load erases, and the digit
shift chain flushes REG), but cell S+10 (the round counter, only set_1, never
cleared) and S+11 (clb_add_ip scratch) do change the first print -- "0047" and
"0000" respectively.  So "the caller must hand in clean scratch" is real, and the
two prints need the erase between them.
2026-11-11 10:59:12 +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 a48adc85c6 ci: install the toolchain again, from a domestic mirror
ci / cell 16 (push) Skipped
ci / cell 32 (push) Skipped
ci / cell 8 (push) Skipped
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Failing after 1m41s
Back to apt-get per run, but archive.ubuntu.com is the slowest hop here: the step
rewrites sources.list (jammy and older) or the deb822 .sources (noble and newer)
to TUNA before updating, then installs cmake/g++/make.  APT_MIRROR is a knob --
aliyun and ustc are one edit away.  ci/Dockerfile stays as the option for a
runner that would rather bake the toolchain in.
2026-11-10 19:56:14 +08:00
dsh 5bc26f7762 ci: the image carries the toolchain, not the job
ci / cell 16 (push) Skipped
ci / cell 32 (push) Skipped
ci / cell 8 (push) Skipped
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Failing after 16s
An apt-get per run is slow, depends on the Ubuntu mirrors (the flakiest hop on
this network) and makes a run non-reproducible.  ci/Dockerfile builds the image
once -- cmake, g++, make, git -- and the runner label points at it
(ubuntu-latest:docker://r8forge-ci:24.04).

The workflow now only proves the toolchain is there and explains how to fix a
bare image, instead of installing it.
2026-11-10 19:52:35 +08:00
dsh 9b1a8fc0de ci: install cmake and g++ before configuring
ci / cell 16 (push) Skipped
ci / cell 32 (push) Skipped
ci / cell 8 (push) Skipped
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Canceled after 1m25s
The runner image is a bare ubuntu with git and node but no cmake, so the very
first step died with 'cmake: command not found' (exit 127).  Every job now installs
cmake/g++/make first and prints their versions plus the core count, which is also
the environment snapshot the logs were missing.
2026-11-10 19:51:08 +08:00
dsh fa12494e43 calc: stage 1 verified -- the character dispatch of the desk calculator
ci / cell 16 (push) Skipped
ci / cell 32 (push) Skipped
ci / cell 8 (push) Skipped
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Failing after 16s
drv/calc_lex.r8asm reads 16 characters and classifies each one: digits print
1+value, the six commands (* + , - . / = 0x2A..0x2F) print 100+index, anything
else prints 200.  The discriminator is bit 4 of the character (digits 0x30..0x39
have it, the command block does not), so four `ror`s and one `biz` split them,
and `t = C - 0x2A` is the command index.

Measured (tape_run and derive agree; tape 90738 chars, 29990 steps):

    in   0 5 9 + - . , *        (15 chars; the 16th inp is EOF -> 0)
    out  1 200 6 200 10 200 101 200 103 200 104 200 102 200 100 200

i.e. 0->1, space->200, 5->6, 9->10, +->101, -->103, .->104, ,->102, *->100,
EOF->200.  Full-alphabet cross-checks: "0123456789*+,-./" gives
1..10 then 100..105, sixteen letters give sixteen 200s, a one char input gives
its value and fifteen 200s.

Two things recorded in the file's header: 90738 characters is over ROT-8-viz's
65536 INS_SIZE because %rep 16 unrolls the body (this driver is verified through
derive/tape_run only; the final program will use a runtime loop instead), and the
bit 4 filter also sends 0x10..0x1F and 0x3A..0x3F down the digit path, which no
protocol input can reach.

This is also the file that slipped into the CI commit earlier -- now it has a
commit of its own with its measured numbers.
2026-11-10 19:47:23 +08:00
dsh 3c427bb8a5 ci: cancel the previous run of the same ref when a new push arrives
ci / cell 16 (push) Skipped
ci / cell 32 (push) Skipped
ci / cell 8 (push) Skipped
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Failing after 15s
One runner means a push that lands while an older one is still building waits for
it.  Cancel-in-progress keeps the queue at one entry per branch; a manual sweep is
still only cancelled by another push on the same ref.
2026-11-10 19:44:36 +08:00
dsh a891538c9d ci: push runs only the baseline; matrix on PR/manual; timeouts
ci / cell 16 (push) Skipped
ci / cell 32 (push) Skipped
ci / cell 8 (push) Skipped
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Canceled after 0s
One runner means one job at a time.  Run #1 took 30 minutes because a push
queued four jobs, each a cold build, and every later push waited behind them.
Now a push runs the 11 bit baseline alone (and not at all for docs only
changes), the width matrix waits for a pull request or the manual button, and
every job has a timeout so a stuck step fails instead of blocking the queue.
2026-11-10 19:42:13 +08:00
dsh 692995af59 docs: the desk calculator's design and the order to build it in
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Canceled after 0s
ci / cell 8 (push) Canceled after 0s
ci / cell 16 (push) Canceled after 0s
ci / cell 32 (push) Canceled after 0s
Back to the RPN idea, but written down before any code: the command protocol
(* + , - . / are exactly 0x2A..0x2F, digits 0x30..0x39, so one bit 4 test splits
them and t = C - 0x2A is the command index), the memory map (working cells, a
fixed 4 deep stack, library scratch, a pre-seeded constant block), the step
budget per token, and the five stages with the driver each one gets verified by.

Two decisions recorded there: EOF (0) ends the loop by erasing its counter, and
the stack stays a fixed 4 cells -- .tp is an assembly time constant, so a moving
stack pointer is the one thing this machine cannot do cheaply.
2026-11-10 19:35:24 +08:00
dsh c53d2c38f1 ci: no cron -- the wide sweep and the cache audit are manual only
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Canceled after 0s
ci / cell 8 (push) Canceled after 0s
ci / cell 16 (push) Canceled after 0s
ci / cell 32 (push) Canceled after 0s
Nothing changes in this repository every night, so a schedule only spends the
runner's time (and the cold cache job re-searches every synthesised block, which
is minutes, not seconds).  Push and PR keep the 11 bit baseline + the 8/16/32
width matrix; the wide width sweep and the cold cache audit now run only from
"Run workflow" (workflow_dispatch).

The sweep matrix is trimmed to the widths that are actually verified
(8/11/16/24/32); 1..4 bits of the library are not something we have evidence for
yet, so they are not offered as a matrix entry.
2026-11-10 19:10:56 +08:00
dsh c0144a2fcf ci: wire CTest and give the runner a pipeline
ci / nightly sweep (1) (push) Skipped
ci / nightly sweep (11) (push) Skipped
ci / nightly sweep (12) (push) Skipped
ci / nightly sweep (16) (push) Skipped
ci / nightly sweep (2) (push) Skipped
ci / nightly sweep (24) (push) Skipped
ci / nightly sweep (32) (push) Skipped
ci / nightly sweep (4) (push) Skipped
ci / nightly sweep (7) (push) Skipped
ci / cold cache (push) Skipped
ci / nightly sweep (8) (push) Skipped
ci / baseline (11 bit) (push) Canceled after 33m54s
ci / cell 8 (push) Canceled after 0s
ci / cell 16 (push) Canceled after 0s
ci / cell 32 (push) Canceled after 0s
`ctest --test-dir build -j` now runs the whole baseline (8 entries, 9 s) instead
of six commands typed from memory, and .gitea/workflows/ci.yml drives it:

  baseline    11 bits, full ctest on every push
  widths      -DR8FORGE_CELL_SIZE=8/16/32, the `widthfree` label only
  nightly     the width sweep for cell 1..32 plus a cold cache run

The tests carry labels for that reason: `widthfree` means "true at any width"
(bit level slices, the synthesizer, the looping demo, the macro comment format),
while flagship / byte_ops / examples pin the 11 bit word (2047 style values,
8 bit era pair counts) and are only meaningful at the default geometry.

Cold cache job: throw .r8forge_cache away and let the searcher find the blocks
again -- it fails if the fresh results no longer match what the repo ships, which
is the cheap version of "the cache is only recomputed when the search changes".

Labels in the workflow are `ubuntu-latest`; change them if the self hosted
act_runner advertises something else.
2026-11-10 19:09:03 +08:00
dsh 90feedb37b 32 bit cells: widen the VMs to uint32_t, fix the mask at 32, make width a build option
All five R8Forge machines stored a cell in uint16_t, so anything above 16 bits
was silently truncated even though geometry.hh (and the viz) allow 1..32; and
`(1 << cell_size) - 1` for _CELL_MAX was undefined at 32.

  * cells and out/input buffers are uint32_t in derive, tape_run, byte_op_test,
    examples_test and synth_test (r8veritas*.hh keep their uint16_t search
    state -- that is node ids, unrelated)
  * kDefaultCellMask and the injected _CELL_MAX special-case 32 instead of
    shifting by 32
  * width is now a build option: -DR8FORGE_CELL_SIZE=<1..32> (CMake cache var,
    added as a compile definition), so a whole toolchain of another width is one
    configure away; build*/ is ignored so those trees do not leak into git

Verified: 11 bits unchanged (tape 64513, byte_op ok); a 16 bit build passes
synth_test 8/8 and byte_op_test (65536 exhaustive pairs); a 32 bit build passes
synth_test, verify_clb_bit_add_nc and assembles full_add to the same 95 chars.
Exhaustive 32 bit is 2^64 pairs -- that stays sampled, not verified.

SPEC 13 checklist now says five VMs / uint32_t / the 32 bit mask case.
2026-11-10 18:23:26 +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
dsh d9689f81ba asm: drop the design-story comments, leave the contract (and a pointer)
Seven files still opened with a paragraph about how they came to be -- "the first
version cleared the same bit four times", "the older repeated-subtraction divmod
needed 1.48M steps", "last round rejected shift-and-add because it was longer",
nested with measured step counts.  None of that tells a caller how to use the
macro, and it is exactly the material that goes stale (raw_sub's figure had been
retracted, and the numbers are SPEC's job now).  The stories already live in
docs/divmod.md and docs/byte-ops.md, so:

    digits    119 -> 80 lines     mul      125 -> 98
    divmod    106 -> 80           inc_ip    81 -> 72
    undigits   95 -> 73           raw_sub   52 -> 38
    dec_ip     21 -> 18

Each now opens with two lines: what the macro computes and where the contract
lives (SPEC section, plus docs/ when there is a design write-up).  Everything
from the `;   Macro <name>` block down -- parameter types, preconditions,
what-is-eaten, the non-obvious invariants -- is untouched, which is what
r8forge_macro_docs_test checks and what a caller actually reads.

Baseline unchanged: tape 64513, 21 byte-op items, 15 examples, 48 macros.
2026-11-09 17:20:44 +08:00
dsh ae268b9442 Interactive I/O: teach the VMs INP, and let examples declare their input
The library can read characters now that the viz defaults to serial ASCII, but
R8Forge's own machines could not: r8forge_derive, r8forge_tape_run and the
examples harness all skipped ',' ("input is not modelled"), so an interactive
program could only be run through ROT-8-viz -- the wrong end of the dev loop,
and nothing in CI could cover it.

Three small pieces:

  * INP (',') reads the next scripted character (low 7 bits) and 0 once the
    text runs out, in tests/tape_run.cc, src/derive.cc and the examples VM.
    r8forge_tape_run and r8forge_derive take -i/--input "<text>", so an
    interactive program is run and checked exactly like any other:
        r8forge_tape_run t.rot8 -i "12+34="
        r8forge_derive calc.r8asm 0 -i "12+34="
  * examples_test learns an optional `;   in ...` header next to `;   out`:
    the characters after the marker are fed to INP before the run.  The marker
    must be the first word after ';' so "include" in a comment is not eaten.
  * examples/echo_chars.r8asm: the smallest interactive program -- read four
    characters, print them back.  in R8F! -> out 82 56 70 33, 8 characters,
    8 steps.

Verified the same tape three ways: tape_run -i "R8F!" -> 82 56 70 33,
derive 0 -i "R8F!" -> same, rot8_test --input R8F! -> prints R8F.  With no
input at all INP reads 0, which is how every non-interactive example keeps
running unchanged.

Baseline: examples_test is now 15 examples + asm/test.r8asm.
2026-11-09 17:14:12 +08:00
dsh ebc7b7c72e docs: split the machine-local half of AGENTS.md into an ignored AGENTS.local.md
AGENTS.md was carrying two kinds of things: project facts (semantics traps, the
do-not-retry list, baselines, pointers) and this-machine facts (the Visual Studio
cmake path, PowerShell's GBK read-modify-write trap, the git identity and the
sandbox elevation needed to push, the flaky %synth temp file, "put slow commands
in the background").  Only the first kind belongs in a repo: a contributor on
another machine gets noise from the second, and half of it goes stale the moment
the box changes.

So AGENTS.md keeps the project (124 lines) and points at AGENTS.local.md for the
rest; AGENTS.local.md is gitignored, so a fresh clone simply re-creates it for its
own machine.  The commit identity rule stays in AGENTS.md (it is repo policy) and
now defers the mechanics to the local file.

No content is lost: the moved bullets are byte-identical apart from the framing.
2026-11-09 16:37:54 +08:00
dsh a82d95658e docs: one home per fact -- README as the front door, SPEC as the contract, AGENTS as the manual
The three documents had grown to 2038 lines and quoted each other: 2199 appeared
seven times, 3977 ten times, AGENTS carried a 200-line copy of SPEC's byte-level
tables while README carried another 155-line copy still showing 8-bit-era numbers
(clb_add_nc 688, clb_not_ip 17, ...) that are wrong at 11 bits.

Split by responsibility, keep every fact exactly once:

  README.md   front door: what it is, 30-second build+run, directory map, where
              to read next                                     547 -> 143 lines
  SPEC.md     the contract: %synth, geometry, every macro's signature / cells /
              tape length / who verifies it, test matrix, boundaries, maintenance
                                                               901 -> 807 lines
  AGENTS.md   the manual: hard rules, build and self-check commands, the traps,
              current state, next candidates, do-not-touch list
                                                               590 -> 132 lines

Long-form reasoning moves into docs/ instead of being dropped:

  docs/divmod.md    the shift-restore division story (was SPEC 14, 102 lines;
                    renumbered 1..6, SPEC keeps a pointer and the references in
                    SPEC 7.6 and asm/divmod.r8asm now point there)
  docs/byte-ops.md  the byte-level design history (was README's 155-line section,
                    rewritten with 11-bit numbers since the old ones were
                    measured at 8 bits)

Also fixes what the dedupe exposed: SPEC no longer claims only the multiplier has
a step bound, and raw_sub's comment no longer repeats the retracted "1.48M steps"
figure. Every section reference in the tree resolves; the baseline still passes
(asm/test.r8asm 64513 characters, 21 byte-op items, 14 examples, 48 macros).
2026-11-09 16:34:15 +08:00
dsh ad45823768 AGENTS/SPEC: cross-checks with ROT-8-viz now need -n
ROT-8-viz switched its default I/O to serial ASCII (cells >= 8 bits) with the
old decimal numbers behind -n/--numbers, so the handoff notes that tell the
next session to compare numeric OUT streams against rot8_test have to say -n.
Also records the new commit hash of that repo (a083a34) and that its default is
serial now, which is exactly what the ASCII from clb_digits wants.

Checked: rot8_test.exe -n on the asm/test.r8asm tape gives the same 93 values
as r8forge_tape_run.
2026-11-09 16:25:28 +08:00
dsh c4048132cc asm/undigits: the inverse of clb_digits (ASCII decimal -> integer)
clb_digits could turn a number into four ASCII digits but nothing could turn
them back, so a program that stored or received a decimal string had no way
home.  clb_undigits REG N S is that way back:

    clb_digits   N REG S      ; 1234 -> 49 50 51 52
    clb_undigits REG N S      ; 49 50 51 52 -> 1234

Same number of digit cells as clb_digits writes (floor(W*log10 2) + 1, four at
11 bits), each read as its low 7 bits, so leading zeros are fine and garbage in
bits 7 and above is ignored.  No validity checking, exactly like clb_digits: a
cell that is not '0'..'9' yields a deterministic but meaningless number, and the
documentation says so.

Horner in a runtime loop, one clb_mul in the whole tape:

    N = 0 ; repeat 4: N = N*10 + digit ; shift the digit cells down one

9642 characters (minimum driver) -- smaller than clb_digits, because the reverse
direction needs no division.

Three things worth remembering, all found by testing rather than reasoning:

  * c ^ 48 == c - 48 for '0'..'9' (the top two bits cancel, the low four are
    identical), so subtracting '0' is one assembly time `.xor 48`: no
    subtraction, no constant cell.
  * The low-7-bit mask is `ror` 7, then set_0+ror per bit for the rest: the total
    rotation is W, so the cell ends up facing the same way.  The first version
    wrote `rol; set_0; ror` in a %rep and cleared the same bit four times -- it
    looks right and is undetectable on inputs whose high bits are already 0
    (measured: 0|5<<7 came through as 688).
  * The round counter must be erased before it is built: set_1 only clears the
    bit it rotates to, so high ones left in the cell turn into extra rounds
    (measured: dirty scratch gave 1234 -> 1564).

Tests and docs:

  * r8forge_byte_op_test gains test_undigits: all 2048 values x {clean, garbage
    in bits 7+} = 4096 cases, worst 36,481 steps.
  * examples/undigits_demo.r8asm: "1234" -> 1234, "0007" -> 7, and a
    digits -> undigits round trip on 2047; examples_test runs it like the rest.
  * asm/test.r8asm calls it too (round trip inside the digits section).  That
    pushed the file over ROT-8-viz's 65536 instruction limit, so the redundant
    second raw_add case, the reversed raw_sub case and the standalone divmod
    section are gone -- every macro is still called at least once, and the file
    is 64513 characters / 236439 steps / 93 outputs now.
  * SPEC 7.9 (contract + the three traps), 10.2, 10.3 and 11, the AGENTS byte
    table / verified list / naming table / baselines, and the README example
    table all updated.
2026-11-09 16:17:39 +08:00
dsh eacf6c01da r8forge: add -q / --quiet for a tape-only stdout
Assembling a library file prints one `%synth ...: cached, N blocks` line per
block (21 of them for asm/test.r8asm), plus search timings and the occasional
temp-directory notice.  That is useful when working on the searcher and noise
when the tape is the output:

    r8forge -q examples/full_add.r8asm > full_add.rot8

-q keeps stdout to the tape alone: cache hits, the layer/tape search lines and
the "temp dir is not writable, using ..." fallback are silenced.  Errors are
not: a missing file, an unknown macro, no program up to N layers, a tape search
that fell back to the layer answer and "cannot write the synthesised macro
anywhere" all still go to stderr with the same exit code.  Quiet means "don't
natter", not "hide the failure".

Implementation follows the existing per-run switches: ast::quiet, the
r8asm::set_quiet(bool) setter, one more parameter on r8asm_synth_program (the
prints live in synth.cc) and the temp-directory notice in r8asm.cc.  The CLI
parses -q and --quiet anywhere among the arguments.

Verified: -q examples/full_add.r8asm and -q asm/test.r8asm produce byte
identical tapes to the normal run (95 / 58722 characters), stderr drops from 1
line / 21 lines to 0 bytes, and -q on a missing file or an unknown macro still
prints the error and returns 1.

SPEC 3.7, the README cost-model section and the AGENTS %synth list document it.
2026-11-08 00:24:51 +08:00
dsh 2e6d9cee86 asm/test.r8asm: call every macro, exercise every language feature
The old test.r8asm was a three round hash: `clb_add_nc` + `clb_mul`, nothing
else.  It proved "add and multiply are enough for a hash" and it was the file
every session was told to check, but a regression in, say, clb_divmod or raw_sub
could not show up there.

It is now the library's kitchen sink instead: one call per standard macro,
grouped from the smallest to the biggest

    A  lib        set_0 set_1 erase rol step back .anchor copy bit_copy
                  copy_to_buffer bit_copy_to_buffer clb_bit_mov
    B  bit slices clb_bit_add_nc clb_bit_inc_nc bit_raw_add/inc/and/or/xor
                  clb_bit_and/or/xor
    C  raw_*      raw_add raw_inc raw_and raw_or raw_xor raw_sub (operands kept)
    D  clb_*      clb_add_nc clb_inc_nc clb_neg_nc clb_sub_nc clb_not_ip
                  clb_inc_ip clb_neg_ip clb_dec_ip clb_nonzero clb_add_ip
    E  big        clb_ones + loop/endloop, clb_divmod, clb_digits
    F  language   a user %macro that uses %rep and %for, .var arithmetic,
                  two inline %synth blocks (map and stat, both cache hits)
    G  the old hash, now two rounds

Each call is followed by `output`, so the OUT stream is the fingerprint.
examples_test now runs this file too and compares it with the `;   out` line in
the header (it already did that for examples/), which makes the file an actual
assertion instead of a length in the docs: an example that stops printing what
its header says fails the test.

Numbers: 58722 characters, 215169 steps, 100 values.  r8forge_derive,
r8forge_tape_run and ROT-8-viz's rot8_test produce the identical stream (the
last six values are the hash: 1322 5 82 0 1786 94).

Two layout decisions come from that cross check:

  * The tape has to stay under 65536 instructions: that is ROT-8-viz's
    INS_SIZE (include/rot8/rot8.h) and read_tape truncates silently past it.
    An earlier version of this file was 76047 and the viz stopped after 99 of
    its 104 outputs, which is how the limit was found.
  * So the hash keeps two rounds and the two rounds share one clb_mul scratch
    block (erased in between) instead of carrying three separate ones.

The hash's own rules are unchanged: the multiplier stays 141 because it is the
historical value, not because small operands must sit in MUL any more.

SPEC 10.2, the AGENTS baseline/self-check/table and the README build snippet
are updated to the new numbers and to the 65536 limit.
2026-11-08 00:15:39 +08:00
dsh b666799950 %synth: make the tape search thread count a run option (-j N)
The tape search always used std::thread::hardware_concurrency() workers with no
way to ask for fewer (or more).  It is now a run option like the cost model:

    r8forge -j N <file.r8asm>                N workers
    r8forge --synth-threads=N <file.r8asm>   same thing

0 (the default) means one worker per hardware thread, as before.
r8asm::set_synth_threads(unsigned) is the C++ side; the CLI parses -j,
--synth-threads and --synth-threads=.  The layer search stays serial (it only
takes seconds and has no split), so the knob only affects the expensive tape
search, which splits by first block (see r8veritas_phase.hh).

The search line on stderr now ends with ", N threads", which makes the setting
verifiable without timing: with a freshly written table (params 4, or4) and the
cache entry removed between runs,

    -j 1                 -> 230 states, 0.0009s, 1 threads
    -j 4                 -> ..., 4 threads
    --synth-threads=2    -> ..., 2 threads
    (nothing) / -j 0     -> ..., 32 threads (hardware_concurrency here)

Documented in SPEC 3.7, README's cost model section and the AGENTS %synth
section.  asm/test.r8asm is unchanged at 28729 characters; byte_op_test,
examples_test (all 13), macro_docs, synth_test (95 chars, 8/8) and
r8forge_derive all still green.
2026-11-07 23:56:37 +08:00
dsh b4ea79ba91 %synth: the cost model is a run option, not a per block metric line
`metric chars|flat|blocks` inside %synth meant the same truth table could be
searched twice for two call sites, and every library block had to spell out
`metric flat` to avoid the default.  The cost model belongs to the whole
assembly, so it is one now:

    r8forge <file.r8asm>                  flat (layout free), the default
    r8forge --synth-chars <file.r8asm>    charge the real .tp walk

flat stays the default because a library block is expanded at dozens of call
sites with different layouts: only a layout free result can share one cache
entry, and it is usually within a few percent (full_add: 95 vs 90 characters).
The chars search is far more expensive (full_add: 415M states, ~21 minutes,
~10 GB), which is exactly why it should be asked for on the command line.

`metric blocks` goes with it: block count is a poor proxy for tape length (and
it was only another way to ask for mode layers).

Implementation: the metric lives in the assembler (ast::synth_metric, default
1) and is set through r8asm::set_synth_metric() before import_file; the CLI in
tests/asm_test.cc parses --synth-chars / --synth-flat.  The cache key already
carried metric, so the committed entries still hit: assembling the library and
asm/test.r8asm gives byte identical tapes (28729 characters, byte_op_test all
green, all 13 examples green, synth_test still 8/8).

A `metric` line now fails with a message that names the flag instead of being
silently ignored.  examples/full_add_flat.r8asm and full_add_flat_spaced.r8asm
are removed: they only existed to demonstrate the per block metric (the flat
default makes them copies of full_add.r8asm).

Also repairs the mojibake in README's metric section: an earlier tool wrote
\x0c / \x08 / \x0d where \f, \b and \r belonged, which ate characters out of
"flat", "blocks", "biz/flb/rnz" and "rnz".  The section is rewritten for the
flag, and the %synth numbers in README/SPEC/AGENTS now match what the tree
prints.

New cache entry c16bf083bb0ccbc8.txt is full_add's stat table with mode layers
+ flat, which full_add_stat.r8asm now produces.
2026-11-07 23:44:01 +08:00
dsh 66ed7bc263 SPEC/AGENTS: why the bit level wrappers must keep their set_0
A question that came up: the %synth stat tables already carry every parameter's
initial value, so shouldn't bit_raw_* stop clearing its output cells first?

No -- and the reason is in the searcher, not in the table.
compress_stat_space() drops the bits whose initial value never changes the
target and canonicalises them to 0 in the start state.  The bit slice tables
are periodic in exactly those bits (the old hand written implementation cleared
them before working, and the derived table records that), so the search never
had to handle "the output cell already holds a 1": the block is only proven for
a cleared cell.  The wrapper's set_0 is what puts the call site inside the
block's domain.

Measured by removing all nine of them (seven wrappers plus clb_bit_or and
clb_bit_xor):

    raw_add / raw_and / raw_or / raw_xor ...   still 65536/65536 ok
    clb_mul         62064/65536 wrong
    clb_divmod      14742/16384 wrong
    clb_digits       2048/2048  wrong (one of them HANGs)

The rotation driven macros survive because they write the result at bit 0 and
rotate it away immediately, so the output LSB is 0 anyway; mul and divmod copy
accumulators around and really do feed a 1 back into the slice.  Dropping the
set_0 would save three characters per cleared bit, which is exactly why someone
will try it again.

Reverted the experiment and wrote it down: SPEC gains 3.6 (compression
semantics and this trap, with the numbers), 6.1 gets the pointer line, and
AGENTS gets an entry in the "already confirmed dead ends" list.
2026-11-07 23:31:23 +08:00
dsh 3f4149c9d0 examples: one runnable routine per macro group
SPEC is the contract and drv/ is what the tests sweep, but there was no place
that showed a reader how a group is actually used.  examples/ now has one stand
alone program per group, each ending in output calls:

    base_macros.r8asm    S5   set_0 vs erase, rol/ror, copy vs bit_copy vs
                              clb_bit_mov, step
    bit_adder.r8asm      S6   4 bit ripple carry adder built from
                              clb_bit_add_nc, then bit_raw_add for the
                              preserving variant
    byte_raw_ops.r8asm   S7.1 raw_add/raw_inc/raw_and/raw_or/raw_xor/raw_sub,
                              printing the operands afterwards to show the
                              whole point of the family: they survive
    byte_clobber.r8asm   S7.2 clb_add/sub/neg/inc_nc (operands eaten) and the
                              S7.3 clb_and residue (240 & 204 -> B = 12)
    byte_in_place.r8asm  S8   not/inc/neg/dec/add_ip and clb_nonzero
    sum_loop.r8asm       S5.1 clb_ones + loop/endloop: 1+2+...+N, count from
                              data rather than from the assembler
    mul_demo.r8asm       S9   82*141 and 2047*2047
    divmod_demo.r8asm    S7.6 2047/10 and 2047/1 (the case that used to hang),
                              reusing the scratch block on purpose
    digits_demo.r8asm    S7.7 1234 and 7 -> four ASCII digits

Every header carries a `;   out 1 2 3` line: the expected OUT stream, so the
file itself says what it prints.  The new r8forge_examples_test target runs all
of examples/*.r8asm and compares that line with the real output (a file without
the marker counts as a failure), printing the tape length and step count on the
way.  That makes examples the second place after byte_op_test that checks
behaviour instead of just "it assembles", and keeps the examples from rotting as
the macros change.  The six %synth examples get the marker too: their inputs are
all zero, so they print 0 0.

All 15 examples pass.  The values in the headers were checked with
r8forge_tape_run (the second interpreter) as well as the test's own machine.

Docs: SPEC S10.3 has the table and the convention, S11 gets the test row, and
README gets a short section plus the layout list.  AGENTS records the examples
in the handoff baseline and the "verified" table.
2026-11-07 22:34:15 +08:00
dsh c2cd0e827f clb_divmod: shift-and-restore division instead of repeated subtraction
Repeated subtraction ran N/D rounds and hit the 5M step ceiling for D = 1
(2047/1 hangs outright); it also cost 2.46M steps for 2047/2.  Binary long
division is fixed at _CELL_SIZE rounds whatever the operands are:

    R = 0 ; Q = 0
    repeat _CELL_SIZE:  R = (R << 1) | next bit   (rol N hands the bits out
                                                   MSB first and restores N
                                                   after W rounds)
                        if R >= D:  R -= D ; quotient bit = 1

The one non obvious part is the comparison.  R needs W+1 bits after the shift,
but the high bit (H, the bit rol wraps out of Rlo) only has to decide the
commit: H = 1 means R >= 2^W > D, so commit = H | Bo, where Bo is raw_sub's "no
borrow" (Rlo >= D).  SPEC 14's Shi = H & Bo is always 0 under the invariant "R
< D at the start of every round" (H = 1 and Bo = 1 together would need R >= 2D),
so that clb_bit_and and its copy do not exist in the built version.

Signature is now clb_divmod N D Q R S: N and D survive, Q and R each get their
own cell (the old version ate N into the remainder), and S is a 7 cell scratch
block (Rhi, Sd, Bo, Cm, Ci, buf, NR).  Only S+5 (the copy buffer) has to be
clean on entry; the rest is rewritten or used as a single bit, which is what
lets clb_digits pass the same dirty block back in every round.

The order that cost clb_mul two reworks is the delicate bit: rol Rlo wraps its
top bit into bit 0, so clb_bit_mov has to move that bit into Rhi (which also
clears it) before bit_copy injects N's bit.  bit_copy (not clb_bit_mov) is what
keeps N intact.

Measured on drv/divmod.r8asm (11 bit):

              repeated subtraction     shift-and-restore
    2047/10        495,986                 28,593
    2047/2       2,461,650                 31,997
    999/7          340,086                 28,661
    2047/1         HANG (>5M)              32,383

Small N/D get slower (fixed W rounds) -- the same trade clb_mul made.  Worst
case over the sweep is 32,383 steps; the tape grows 4189 -> 4499 characters.

About the numbers in SPEC 14 / AGENTS: the 1.48M steps claimed there do not
reproduce on this tree.  Measured before the change, 2047/10 was 495,986 and
clb_digits(2047) was 740,695, so the docs now carry the measured values and say
where the old figure came from.

clb_digits keeps its shape (one divmod in a 4 round loop, written digits shift
up by one cell), with S grown to 13 cells: TEN, quotient, remainder, the 7
divmod scratch cells, the loop counter and add_ip's T/F.  2047 goes from
740,695 to 145,138 steps (worst 164,867) and 10829 -> 13717 characters.  It
needs its own %include "asm/add_ip.r8asm" now: that used to arrive through the
old divmod.

Tests: test_divmod sweeps 8 divisors x all 2048 dividends (16384 pairs; the old
76 sample table is a subset) and also asserts N and D come back unchanged;
test_digits sweeps all 2048 values.  Both print the worst step count.

Two traps found on the way:

* r8forge_derive (and byte_op_test/synth_test) checked the assembler error flag
  before export_rot8(), but an unknown macro or a bad .tp target is found while
  the tree is *expanded*: a missing %include left a truncated tape that still
  ran and printed a plausible wrong answer (all four digits came out '0').  All
  three now check after the export.
* raw_sub's comment claimed Bo = 1 means A < B; the code (and clb_sub_nc) mean
  A >= B.  Comment fixed, behaviour untouched.

Also adds drv/div_shift.r8asm, the single step check for the cross cell shift
plus injection, and records the measurements in SPEC 7.6/7.7/14 and AGENTS.
2026-11-07 22:22:03 +08:00
dsh 677878779a AGENTS: hand off the divider rewrite at the top of the file
A new session should not have to reconstruct the task from git history.  The
first thing in AGENTS.md is now the job: replace clb_divmod's repeated
subtraction with shift-and-restore division, target 2047/10 going from 1.48M
steps to about 35k with the tape staying near 4k.

It names the first step (build and single step verify the R cross cell shift
plus bit injection before anything else), the order that bit clb_mul got wrong
twice, the second step (raw_sub + clb_bit_or/clb_bit_and for the commit logic),
the acceptance list, the baseline commands that must stay green, and what not
to touch.  DEC SPEC 14 holds the derivation, and raw_sub (already in the
library) is the piece that makes it possible.
2026-11-07 20:31:15 +08:00
dsh a2154ee9ac SPEC 14: the shift-and-restore divider, worked out before it is built
The divider rewrite is a multi-round build (the cross cell shift cost clb_mul two
reworks), so the design went into SPEC first.  The one non obvious part is the
comparison: R needs W+1 bits, but it does not need a W+1 bit subtraction.

With R = (Rhi:Rlo) and D < 2^W, compute S = Rlo - D and Bo = (Rlo >= D) with
raw_sub, and then

    commit (R >= D)      is  Rhi | Bo
    the new high bit is      Rhi & Bo

All four cases check out (Rhi = 0, Bo = 0 is exactly R < D, no commit).  So a
W bit subtract plus one bitwise OR and one AND replaces the W+1 bit machinery.

Also recorded: the state layout, the per round skeleton, why N is rotated with
rol (it hands out the bits most significant first and restores itself after W
rounds), the four pitfalls, and the acceptance checklist (same 76 sample pairs
against the current clb_divmod, step counts before/after, and clb_digits going
from 1.48M steps to tens of thousands).

raw_sub (the previous commit) is what makes this possible at all: the divisor
has to survive every round.
2026-11-07 20:29:51 +08:00
dsh 9a9ca48d9a raw_sub: a subtraction that keeps its operands
clb_sub_nc eats A and B, so the repeated subtraction divider has to copy both
every round (two 495 character copies, about five hundred steps each) -- that
is where clb_divmod's 1.48 million steps for 2047 comes from.  Binary long
division compares against the same divisor every round and cannot afford that,
so it needs a non destructive subtract first.

raw_sub A B S Bo Bc Ci buf is three useful lines: copy ~B, set Ci = 1, then
raw_add (which already preserves its operands).  S = A + ~B + 1 = A - B, and A
and B are untouched.  About 2900 characters, 7 cells, 9 sampled cases correct.

One trap measured: do not flip Bo at the end to turn a carry into a borrow --
clb_not_ip complements the whole cell, so 0 becomes 2047 and 1 becomes 2046.
Bo keeps the library's existing meaning instead: 1 means A >= B (no borrow),
same as clb_sub_nc's carry.

This is step one of replacing clb_divmod's O(N/D) loop with shift-and-restore
division at O(cell_size) rounds (11 instead of 205 for 2047, so roughly forty
times fewer steps for maybe a few hundred extra characters of tape).
2026-11-07 20:24:55 +08:00
dsh 91e3fed537 r8asm %for: repetition with a loop variable
clb_digits needed to name a different cell every round, which %rep cannot do: it
copies identical text N times and has no loop variable, and there is no %if
either, so the three shift steps were spelled out by hand and the macro was
only correct for 11 bit cells.

    %for k 3            ; k is 0, 1, 2 inside the body
        step k
    %endfor

%for <name> <count> binds <name> to 0..count-1 as a compile time constant that
any expression can use: %rep counts, .tp targets, macro arguments.  The loop
scope is a copy of the current scope plus the name, so a %for inside a macro
body still sees that macro's %1, %2, ...  %rep and %for nest in each other
(both closers count as a closer).  %rep itself is untouched.

With it, clb_digits lost its hardcoded chain: the digit count, the shift count
and now the constant builds (tails written as _CELL_SIZE - 5 / _CELL_SIZE - 3)
all follow _CELL_SIZE.  Checked at 16 bits with a five cell region: 4660 gave
'0' '4' '6' '6' '0' and 7 gave '0' '0' '0' '0' '7', so the count really did
become five.  65535 hangs in clb_divmod (6553 rounds, over the 5M step budget)
-- that is the divider's O(N/D), not digits.  Back at 11 bits everything is
unchanged: all eleven values, hash 28729, byte_op and docs green.

SPEC 3.5 documents the directive; it is a local extension like %synth.
2026-11-07 18:05:44 +08:00
dsh b962c345c8 clb_digits: derive the digit count from _CELL_SIZE
The round count was spelled out as four 1s in the counter; it is a function of
the cell width (L = floor(W*log10(2)) + 1, integer approximated as
W*30103/100000 + 1, which gives 3/4/5/10 for 8/11/16/32 bits), and r8asm
evaluates that inside %rep, so the counter now builds itself:

    %rep _CELL_SIZE * 30103 / 100000
        rol
        set_1
    %endrep

What is still spelled out is the shift chain (three copies with distinct
offsets), because each step names a different cell and r8asm has no %if, no
indexed %rep and no recursion -- it cannot emit L-1 different instruction
groups.  So the macro is correct for _CELL_SIZE == 11 only, and the comment now
says so loudly: a 16 bit cell needs one more step and one more cell, otherwise
the result is silently wrong.  Making it generic needs an indexed %for in the
assembler (or a ten cell region with a fixed nine step chain, which works at
any width but costs three thousand characters and six cells).

All eleven values still correct at 11 bits, 13743 characters with the driver.
2026-11-07 17:55:39 +08:00
dsh a515e823d1 clb_digits: integers become a four digit ASCII string
clb_digits N REG S writes '2' '0' '4' '7' into REG..REG+3 for 2047 -- ASCII
digits, most significant first, fixed width four, zero padded, which is what
was asked for after the ASCII/order/source questions.

divmod appears once, wrapped in a loop that runs four times.  The first
version dispatched each digit to its own cell with four branches and a one-hot
flag handoff, and only the first branch ever fired; the digits themselves were
right (checked by printing N after every division: 204, 20, 2, 0).  Rather than
keep chasing that, the dispatch is gone: each round shifts the digits already
written one cell up (high to low, so nothing gets clobbered) and the new digit
always goes to REG+0.  Four rounds later REG+0..3 are thousands, hundreds, tens,
ones in that order.  Simpler, two nesting levels less, four cells less, and it
works: 0/1/7/10/42/99/100/512/1000/1234/2047 all correct.

Two real traps found on the way, both now in the macro comments and SPEC:

  * copy's buffer cell must be *clean*: a dirty buffer makes the copy produce
    0 (measured: Q = 4, buffer = 0x7f8 -> N = 0).  The library only says the
    buffer is borrowed, never that it has to be zeroed.
  * building a constant cannot be done as 'set a bit, rotate, set another,
    rotate': the second rotation carries the first bit away.  Walk the ring
    once instead -- W rotations, set_1 at each target bit, then back home.

10829 characters with a minimal driver (13743 with the four outputs), 16 cells
in total, and r8forge_byte_op_test's test_digits covers all 11 values.
2026-11-07 17:18:02 +08:00
dsh 4a5bd836a8 clb_divmod: nine parameters down to four
Complaint received and agreed with: nine cells to pass for a division is not an
interface anybody wants to type.  Two things made it possible to shrink:

  * .tp and macro arguments accept address expressions (measured: .tp A+1
    assembles, and set_0 A+1 expands to .tp A+1 inside the callee).  So the
    four scratch cells can be passed as one block: clb_divmod N D Q S uses S,
    S+1, S+2 and S+3.
  * BUF and X were unnecessary: copy already has sources and destinations to
    spare that are dead at the moment they are needed, and clb_inc_ip can take
    a cell that the probe is about to overwrite.

So the signature is now clb_divmod N D Q S -- three data cells and one scratch
base -- and the tape dropped from 5839 to 4189 characters on the way, because
the scratch cells now sit next to each other and every .tp walk got shorter.

Still correct: all 76 sampled pairs (2047/10 = 204 7, 7/10 = 0 7, 10/10 = 1 0,
1234/100 = 12 34, 999/7 = 142 5, 2047/2047 = 1 0), and the O(N/D) limit is
unchanged.
2026-11-07 16:53:27 +08:00
dsh 0b96b76104 clb_divmod: division and modulo, so digits have something to stand on
The library had add, subtract (with a free compare in its carry), negate,
increment, decrement, multiply, and the bit ops -- but nothing that divides.
Asking for a decimal expansion without it means inlining a division per digit,
which is where the 11k character estimate came from.

clb_divmod N D Q W V T Ci X BUF leaves Q = N div D and N itself as the
remainder, eating D.  Plain repeated subtraction:

    Q = 0
    while N >= D:  N -= D ; Q += 1

Two things it took to get right:

  * clb_sub_nc eats both operands, and the subtraction cannot alias (measured:
    clb_sub_nc A B A Ci with A=15 B=10 gives 0), so each round needs copies of
    N and D.  Two of the three copies are pure overhead, but they are in the
    loop body, which appears once.
  * The first round has to be able to do nothing.  Setting T = N and Q = -1
    before the loop makes the first commit a no-op and lets the phantom count
    cancel out, so the probe can live at the *bottom* of the loop and appear
    only once.  Without that the probe is duplicated and the tape grows by
    about 1.3k.

5839 characters with a minimal driver (5845 with the two outputs), 9 cells,
all 76 sampled pairs correct in r8forge_byte_op_test.  Runtime is O(N/D): the
worst case 2047/1 crosses the 5M step budget and hangs, so the test keeps
N/D <= 600 and SPEC says so.  Division by zero is undefined, D >= 1 is the
caller's job.

Next: clb_digits on top of this, which needs a shared loop plus per-cell
conditional writes (computed addressing does not exist here) rather than four
copies of divmod.
2026-11-07 16:51:25 +08:00
dsh b89fcb0588 SPEC 5.1: do not replace an assembly time counter with clb_ones
Asked for, then stopped mid-flight: the tempting refactor was to build
clb_mul's round counter with clb_ones + loop/endloop instead of
%rep _CELL_SIZE { set_1; ror }.  It is the wrong direction and worth writing
down so the next attempt does not get as far:

  assembly time    %rep _CELL_SIZE { set_1; ror }   55 characters
  run time         clb_ones (~770) + loop/endloop (~10) + building _CELL_SIZE
                   as a value, about 850 characters, 4 more cells, tens of
                   thousands of extra steps

Same for the alignment trap: %rep N { set_1; ror } leaves the run of ones at
the top of the cell, so biz sees bit0 = 0 and the loop never starts -- N < W
needs one rol after the %endrep.  clb_mul only escapes it because its N is
_CELL_SIZE, i.e. the whole cell is ones.
2026-11-07 16:37:15 +08:00
dsh 3cfdad4313 loop/endloop: the other half of clb_ones, runtime loop counts
clb_ones turns a count into that many ones, and these two macros spend those ones
one per iteration, so a tape can loop a number of times that only exists at run
time:

    clb_ones N C T F
    loop C
        ... body ...
    endloop C

\loop c\ is .tp c + biz + set_0 + ror: test the low bit, spend it, rotate the
next one into place.  \endloop c\ is .tp c + rnz.  No .anchor is used, so the
pair nests, and endloop puts dp back on the counter whatever the body did with
it; the body must not touch c, and c is all zeros once the loop is over.

Checked with verify_loop.r8asm (939 characters): N = 0..11 makes the body run
exactly N times, A = N and C = 0 -- including N = 0, where biz skips the body
entirely.  Nesting checked too: an inner loop rebuilt from a copy of its count
gives NO * MI (11 * 11 = 121, and 0 when either count is 0).

One trap found on the way, written into SPEC 5.1: in .r8asm source a loop is
spelled biz/rnz, not [ / ] -- the brackets are the tape encoding, and writing
them makes the assembler say " unknown macro [ \.
2026-11-07 16:33:31 +08:00
dsh bfad4b5d34 clb_ones: unary expansion, a count becomes that many ones
New macro in asm/ones.r8asm: clb_ones A B T F leaves B = 2^A - 1, i.e. A
consecutive ones starting at the low bit, and eats A (it is spent as the
counter).  The contract only holds for A <= _CELL_SIZE and is not checked, as
asked: 0 -> 0, 1 -> 1, 4 -> 0x0F, 7 -> 0x7F, 11 -> 0x7FF (all ones).

The loop is "shift and stuff a one in":

    B = 0
    while A != 0:  B = 2B + 1 ; A -= 1

In this machine `2B + 1` is exactly `rol` + `set_1`: the left rotation brings
B's top bit round to the low bit and set_1 overwrites it.  A is spent as the
counter instead of being copied (a copy is 495 characters), the loop body
appears once so the length does not depend on A, and the run time is O(A) with
A <= cell size.

The other sizing option was measured and rejected: start from 1, rotate A
times, then clb_dec_ip once.  That drops set_1 from the body but pays 132
characters for the decrement and 44 for the erase, so it comes out 128 longer.

  * tests/byte_op_test.cc: test_ones walks every A the contract covers
    (0..kCellSize), which is the whole domain once the range is the caller's
    job; 742 characters with the driver, 828 with a minimal one.
  * drv/ones.r8asm: the driver the test uses.
  * SPEC.md 7.5: the contract, the algorithm, and the two identities worth
    remembering -- clb_inc_ip turns n ones into 2^n, and building it the other
    way round costs more than it saves.  Macro counts bumped to 42.
  * AGENTS.md: the tables, plus the naming row (destructive computation whose
    result lives in another cell, so no _ip suffix).
2026-11-07 16:29:17 +08:00
dsh 54ddf9b0e7 SPEC.md: the %synth grammar and every standard library macro's contract
R8Forge had no spec of its own: the language lives in r8asm_rev/SPEC.md, the assembler
and the search were documented in README.md, and the macro contracts were only in the
comments above each %macro.  This adds SPEC.md, pointed at the standard library:

  * what this spec covers and what stays upstream (so the two do not drift);
  * the five parameter types, the naming prefixes/suffixes, and the measurement
    convention for tape lengths (a minimal driver, contiguous cells, no output lines);
  * %synth: the full grammar, what map and stat mean, the three metrics, the cache key
    and kModelVersion rule, and the four limits (8 params, 8 layers, no byte level
    tables, no unconditional flip);
  * all 41 macros in asm/ in tables with signature, which cells they eat, cell count,
    tape length and implementation (hand written or %synth block + its stat table);
  * the warts: clb_and leaves B & ~A behind while clb_or/clb_xor are clean, layout being
    silently ignored when its length is not params, and set_0 clearing one bit only;
  * a verification matrix saying which test proves what, and the known dead ends.

Every number in the tables was measured for this commit with one uniform driver
(measure_macros.ps1 shape, deleted afterwards), e.g. clb_not_ip 22, clb_add_ip 722,
clb_mul 3964 minimal vs 3977 through drv/mul_byte.r8asm.  AGENTS.md and README.md now
point at SPEC.md instead of saying the %synth docs only live in the README.
2026-11-07 12:44:47 +08:00
dsh ac5810580d kDefaultCellBits -> kDefaultCellSize: the width is cell_size, not cell bits
The cell width is cell_size everywhere else now -- cell_size in the AST, in
ROT-8-viz's rot8_config, and the docs -- but the default in geometry.hh was
still kDefaultCellBits, and the four VMs spelled it that way too.

  * include/r8forge/geometry.hh: kDefaultCellBits -> kDefaultCellSize.
    kDefaultCellMask keeps its name: it is a mask, not a size.
  * src/derive.cc, tests/asm_test.cc, tests/synth_test.cc, tests/tape_run.cc,
    tests/byte_op_test.cc: same rename, and the local shorthand kBits in
    byte_op_test.cc is now kCellSize so the test file does not put the old
    word back.
  * AGENTS.md and README.md follow.  The cross check bullet now describes the
    workspace ROT-8-viz as it actually is (fork dsh/ROT-8-viz, branch main,
    runtime --cell / --mem over cell_size / mem_size), instead of the feature
    branch it used to point at, which no longer exists.

No behaviour change.  All six self checks re-run green: 28729 character hash
tape, synth_test 8/8, both verify_ tapes, byte_op_test (clb_mul 3977 chars,
65536/65536, "byte level library ok") and the macro docs test.  The hash tape
still gives 1322 1786 1600 5 94 127 from r8forge_derive, r8forge_tape_run and
ROT-8-viz's rot8_test -- three implementations, one answer.
2026-11-07 12:33:56 +08:00
dsh 94868be24f Name the two geometry numbers the same way everywhere: cell_size, cell_argc
The cell width was CELL_SIZE on the C++ side, and the searcher's CellBit count
was CELL_ARGC.  Both now match what the code and the docs around them already
called them:

  * include/r8forge/r8asm.hh + src/r8asm.cc: CELL_SIZE -> cell_size
    (set_cell_size assigns this->cell_size, its parameter already had that
    name);
  * include/r8forge/r8veritas.hh: the template parameter CELL_ARGC ->
    cell_argc, 34 uses, so the searcher reads r8veritas<cell_argc>;
  * AGENTS.md says which name means what, and why the name .r8asm programs
    see is still _CELL_SIZE: that one belongs to the macro library, not to
    the C++ side, and changing it would rewrite every macro in asm/;
  * the cross check entry now says which ROT-8-viz is which: the author's fork
    with --cell/--mem, and the upstream starcells/ROT-8 tree in the workspace,
    whose geometry is compile time cell_size/mem_size -- it is 11 / 259 too
    now, and `rot8_test <tape>` against `r8forge_derive ... -1` still gives
    1322 1786 1600 5 94 127 on the hash tape.

All six self checks pass unchanged: 28729 character hash tape, synth_test 8/8,
both verify_ tapes, byte_op_test 65536/65536 for clb_mul and the rest of the
library, macro docs test green.
2026-11-07 12:23:42 +08:00
dsh 6e67eb4678 The multiplier: shift and add, one bit at a time, 3977 characters
clb_mul was repeated addition -- add MC into the product, MUL times.  That is
the shortest thing to write, but the runtime is proportional to MUL's value:
255 * 255 took 733428 steps, and 2047 * 2047 ran into the 5000000 step ceiling
and hung outright (tape_run: HANG after 5000000 steps).  So the multiplier was
a ceiling on what any program could compute.

The new body is the plain binary multiplication from school: hold the
multiplicand, look at the multiplier's low bit, add the multiplicand into the
high half of the product when that bit is 1, then shift the whole product one
place right -- the multiplier lives in the low half of that register, so its
bits fall out one at a time.  The loop runs _CELL_SIZE rounds whatever the
operands are, and the tape got shorter as well:

    82 * 141     358586 -> 8374 steps
    255 * 255    733428 -> 17785 steps
    2047 * 2047      HANG -> 26123 steps
    tape           5007 -> 3977 characters

(Step counts are the tape's own, with no trailing newline -- tape_run counts
one if the file has one, which is where the first draft of this message got
numbers two out.)

Counter, carry and cross cell shift are the three pieces that needed care:

  * the round counter is _CELL_SIZE ones in NR, one eaten per round by
    set_0 + ror -- the same trick clb_inc_ip counts rotations with, so "how
    many rounds" costs no tape length, only runtime;
  * the carry out of the W bit add is not scratch: it is the top bit of the
    2W+1 bit shift register, and the next shift moves it into PH's top bit;
  * (F:PH:PL) >>= 1 is a cross cell shift.  ror all three, bring the bit to
    inject down to bit 0 with rol, move it with clb_bit_mov, ror back.  The
    low pair (PH -> PL) moves first, otherwise PH's bit 0 has already been
    overwritten by the carry.

And biz/rnz is a loop pair, not an if/else: a one shot conditional has to eat
the bit it tested (a trailing flb) or rnz jumps straight back.  The first
version of this hung exactly there -- no output at all, counter still 0x7ff.
The bit eaten is PL's low bit, which the shift discards anyway.

r8forge_byte_op_test now sweeps 0..255 x 0..255 exhaustively (65536/65536 ok,
6.7s instead of 1.5s) instead of sampling 64 combinations: the cost no longer
grows with the multiplier, so sampling was the only reason not to.  asm/
test.r8asm still prints 1322 1786 1600 5 94 127, now as 28729 characters and
57330 steps (was 31901 and about two million), and derive and tape_run agree.

AGENTS.md and README record all of it, plus one correction: the old note said
shift and add had been dismissed because "only tape length is the target".  It
is in fact 1000 characters shorter, so the reason given was wrong -- the
tradeoff was not.  What changed is the target function: the 5000000 step
ceiling is part of it, and a loop whose length does not depend on its operands
can still have a runtime that does.
2026-11-07 12:09:45 +08:00
dsh 9b326f3b4b AGENTS.md: read the docs before touching anything 2026-11-07 11:49:00 +08:00
dsh 2eb26b58d6 Say which operand the multiplier loops on, and what swapping costs 2026-11-07 11:42:02 +08:00
dsh 24bea4a2b5 test.r8asm: a rolling hash, (h + c) * 141 mod 2048 over R8F 2026-11-07 11:35:23 +08:00
dsh 330710aed4 test.r8asm: 32x32 and 64x32, the edge of an 11 bit cell 2026-11-07 11:27:50 +08:00
dsh 3c3e2b4779 AGENTS.md: commit ROT-8-viz with -c, its local config keeps vanishing 2026-11-07 11:13:14 +08:00
dsh b80b626c66 AGENTS.md: an old tape on a new cell width can loop forever 2026-11-07 11:12:25 +08:00
dsh 62c6f8979f Cell width and tape length: 11 bits, 259 cells, by default
The assembler already took the width as an argument (import_file(path, cell_size))
and exposed _CELL_SIZE / _CELL_MAX / _ROL_STEP to programs, so every macro that
writes %rep _CELL_SIZE follows the width on its own.  What was missing was a
single place saying what the default is, and VMs that agree with it.

include/r8forge/geometry.hh now holds kDefaultCellBits = 11,
kDefaultMemoryCells = 259 and kDefaultCellMask, and the four VMs use it:

* cells are uint16_t, the tape is kDefaultMemoryCells long
* ROR is (v >> 1) | ((v & 1) << (kDefaultCellBits - 1)), not the 8 bit version
* input and output mask with kDefaultCellMask

The tests now state their expectations in terms of the width instead of a byte
(kCellMask, kBits, kCellMod).  Two things were genuinely wrong for 11 bits and
are fixed: clb_neg_* and clb_inc_* were compared against 256 - a and 0xff, and
asm/test.r8asm set B with .xor (~126)+1 -- .xor takes its constant modulo the
cell width, so that is 1922 in an 11 bit cell, not 130.

Results at 11 x 259:

    asm/test.r8asm        7262 characters, out 127 130 0 257 0 1088 19
                          (127+130 = 257, and 200*200 = 19*2048 + 1088)
    r8forge_byte_op_test  all 17 operations pass
    r8forge_synth_test    all eight combinations ok (bit level is width free)
    r8forge_macro_docs_test  41 macros in 17 files
    asm/fibonacci.r8asm   11959 characters, 13 terms now (no wrap at 256)

ROT-8-viz moved its defaults to 11 x 259 in the same change, so the tapes cross
check: both implementations print 127 130 0 257 0 1088 19 for asm/test.r8asm.
Tapes grow when the width does (raw_add 1647 -> 2199 characters), because the
%rep _CELL_SIZE loops are longer.

AGENTS.md gains a section on how the width flows through the tools, including
the trap that 2048 % 256 == 0 makes several 8 bit expectations still pass by
accident.
2026-11-07 10:56:28 +08:00
dsh cfe56e164a AGENTS.md: commit as dsh, not as the repo owner 2026-11-07 10:40:25 +08:00
dsh 6e8e33e455 test.r8asm now multiplies as well as adds
The file was the library smoke test: it set up a few cells, called raw_add and
printed five values.  It now also calls clb_mul and prints the two product bytes,
so one tape exercises both of the expensive paths and the self check runs a
result rather than only an assembly.

    127 + 130 = 257        -> S = 1, Co = 1
    200 * 200 = 40000      -> PL = 0x40 = 64, PH = 0x9C = 156
    whole tape             5417 characters (was 1666)

Both interpreters agree on `out 127 130 0 1 1 64 156`: r8forge_derive from the
source and r8forge_tape_run from the assembled tape, 427343 steps.

The multiply half lives at cells 16 and up so it cannot disturb the add half, and
the file's existing cell layout is untouched.
2026-11-07 10:15:58 +08:00
dsh 185b4bf24a The multiplier, 3729 characters, by repeated addition
clb_mul  MC MUL PL PH MCA S Ci T F NR    (PH:PL) = MC * MUL
    10 cells, 3729 characters, 64 sampled cases, 255*255 = 0xFE01 included

For scale: fibonacci is 8761 characters and does not multiply.  The tape length
does not depend on MUL at all, because the loop body appears once.

The algorithm is repeated addition, not shift-and-add:

    (PH:PL) = 0
    while MUL != 0:  (PH:PL) += MC ; MUL -= 1

which is the same lever as clb_add_ip: length is the metric, steps are not.  Worst
case is about a million steps against the five million limit and that is fine.

The 16 bit accumulate uses clb_add_nc for the low byte because it is the one that
reports a carry out; clb_add_ip does not, so it cannot do that step.  clb_add_nc
eats its operands, so each round copies the multiplicand first.  The carry then
goes into the high byte with clb_add_ip, which costs nothing extra since it is
0 or 1.

Worth recording what this did to my own plan: I had said the multiplier needed
"cross byte shifts" and "conditional accumulate" first, and sketched a
shift-and-add design around them.  Repeated addition needs neither -- the shift
disappears entirely.  The primitive that actually mattered was the one I called
missing two messages earlier: an add that keeps the addend alive, which is what
pushed out clb_add_ip and clb_nonzero.  Look at the objective function before
copying the shape of a hardware multiplier.

byte_op_test is seventeen operations, still 1.4 s, with test_mul sampled over
8 multipliers x 8 multiplicands.
2026-11-07 09:56:03 +08:00
dsh a6560b72cf In place add, by looping instead of writing a carry chain
clb_dec_ip  A T        A = A - 1                2 cells  106 chars  256/256
    clb_nonzero B F T      F = (B != 0), B intact   3 cells  209 chars  256/256
    clb_add_ip  A B T F    A += B, B is eaten       4 cells  558 chars  2048 sampled

against raw_add (6 cells, 1647) and clb_add_nc plus a copy per round (688 + 364).
Add is the primitive the multiplier needs, so this was the expensive one.

decrement needed no new algorithm: B - 1 = ~(-B), so it is clb_neg_ip then
clb_not_ip, and both are already in place.

The add does not do a per bit carry chain, and it is worth being clear why not:
a full adder's carry is maj(a,b,c), i.e. a pairwise conjunction, and every
conditional test eats the bit it tests, so a hand written ripple needs several
copies of each bit and nested tests -- long and fragile, and it was the reason I
first called this impossible.

What works instead leans on something true of this project: the metric is tape
length, not execution steps.  So

    while B != 0:  A += 1 ; B -= 1

The loop body appears in the tape once, so the length does not depend on B.  The
cost is O(B) runtime, about 300k steps at B = 255 against a 5M limit.  This is a
general lever: anywhere length is what matters, ask whether a loop can replace
generated code.

The one thing that was genuinely awkward is "B != 0", since biz only looks at the
low bit.  clb_nonzero walks the eight bits, moves each into a work cell (which
clears that bit of B), and if it was set, sets F and puts the bit back; B comes
out untouched.  Note set_1, not flb: flb flips, so an even number of set bits
flipped the flag back to zero and 3, 5 and 255 all read as "zero" until I fixed
it.

For the multiplier this means one copy per round (364) to keep the multiplicand,
so about 920 per round, roughly 8k for the whole multiplier instead of 13k.

Tests: byte_op_test is sixteen operations now, 1.5 s.  test_add_ip is sampled
(8 accumulators x 256 addends) because the loop makes exhaustive runs slow.
2026-11-07 09:49:51 +08:00
dsh 2f79898e3d In place increment in two cells, 74 characters, by counting rotations in the
scratch cell's bits

I said a two cell in place increment was impossible.  It is not.  The version in
asm/inc_ip.r8asm does A = A + 1 with A and one scratch cell, 74 characters,
256/256 exhaustive, and there is a two cell in place negate on top of it:

    clb_not_ip A       A = ~A      1 cell    17 chars   256/256
    clb_inc_ip A T     A = A + 1   2 cells   74 chars   256/256
    clb_neg_ip A T     A = -A      2 cells   90 chars   256/256

against clb_inc_nc (3 cells, 430) and clb_neg_nc (3 cells, 448).  Five times
shorter, one cell less.

Both of my earlier impossibility arguments were about a *specific* algorithm, the
per bit carry ripple, and I stated them as if they covered the problem.  The one
worth remembering is the synthesis one, which is still true: a synthesised block
has exactly one condition cell, so it cannot tell (A=1, Ci=0) from (A=1, Ci=1),
and all four in place tables answer "no program up to 8 layers".  The hand
written argument was simply wrong.

The algorithm that works does not test the carry per bit at all:

1. `[ ... ]` already means "while the low bit is set", so clearing the run of
   low ones is a loop that falls out on the first zero (flb + ror);
2. flip that zero to one -- skip it when the input is all ones, which is exactly
   the wrap-around case;
3. rotate the rest of the way.

What is left is "how many rotations remain", with only two cells.  The counter
goes into the scratch cell's bits: T starts as 0xFF, and every rotation does
set_0 then ror, which eats one 1 -- the length of the run of ones is the number
of rotations left.  Three characters per step, and a full turn counts to eight.

The wrap case falls out for free: when the input was 0xFF the counter is spent
exactly then, so step 2 is skipped and the answer is 0.

Two smaller notes.  The dp rule from the last commit is what these macros had to
respect -- every conditional body returns to its own condition cell -- and
`[ ... ]` consuming its condition is only a problem when the condition is data;
here it is the counter.  And I mangled asm/inc_ip.r8asm once with a PowerShell
Get-Content / Set-Content round trip (the trap AGENTS.md warns about) and had to
rewrite it with the editor; no other file was touched.

byte_op_test is twelve operations now, still exhaustive, still under a second.
2026-11-07 09:40:05 +08:00
dsh 349b6d2748 tape_run --trace, and the dp rule that killed the two cell increment
r8forge_tape_run grew a `--trace` flag: it prints pc, instruction, dp and the
first four cells before every step.  Without it a wrong hand written macro is
just "the answer is wrong"; with it the failure is one line, e.g. dp jumping to
1023 because a backwards move was emitted where the runtime was already there.

That is what happened to the two cell in place increment I tried after the in
place complement.  It assembled to 155 characters (against 430 for the slice
version) and got 129 of 256 inputs right -- every input whose low bit is 0, i.e.
every input that never propagates a carry.  The algorithm was fine; the macros
were not.

The rule it broke: dp is a compile time constant in r8asm while a `[ ... ]` body
may be skipped at run time, so **every conditional body has to come back to its
own condition cell** (net zero moves).  Otherwise the taken and the skipped path
leave dp in different places and every later `.tp` is off by one.  The library
already obeys this: set_0's body never moves, clb_bit_mov ends with `.tp before`
and a `flb` that eats the condition on the way out.

For a two cell in place add both candidate condition cells hold live data (A's
bit is the result, the carry cell's bit is the carry), so each test first has to
make its condition consumable, which means moving a bit through the spare bits of
the carry cell and rotating it into place -- about eight characters of detour per
bit.  A correct version should land near 200-220 characters, still about half of
the 430 character slice version, but it stays a hand written loop with subtle
invariants.  Not added to the library yet; the scratch files are gone.

AGENTS.md now carries the dp rule under the instruction semantics section, next
to the two `set_0` / `%synth` constraints it belongs with.
2026-11-07 09:30:46 +08:00