50 Commits
Author SHA1 Message Date
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 eedd9a33a6 Negate and subtract invert the whole byte first instead of bit by bit
Asked why an in place complement does not exist, given that in place inversion
does.  The inversion half is now hoisted out of the per bit loop, which is both
simpler and shorter:

    clb_neg_nc A S Ci = clb_not_ip A ; clb_inc_nc A S Ci     468 -> 448
    clb_sub_nc A B S Ci = clb_not_ip B ; clb_add_nc A B S Ci   725 -> 707

and the unsigned complement through the same macro (carry in at 0) drops 467 ->
447.  B is eaten by the add anyway, so inverting it in place costs nothing.  The
per bit `flb` wrappers (clb_bit_neg_nc, clb_bit_sub_nc) are gone with them, so
macro_docs_test now counts 35 macros.

What does not work is the other half: there is no in place increment, so the sum
still has to land in S.  Two independent reasons, both written down:

* A synthesised block has exactly one condition cell, so it cannot tell
  (A=1, Ci=0) from (A=1, Ci=1) -- and that distinction is the whole carry rule.
  All four in place tables answer "no program up to 8 layers".
* Hand writing cannot do it with two cells either: `[ ... ]` is the only one shot
  conditional this ISA has, and it eats the bit it tests, while in place
  increment needs both cells' bits alive at the same time.

So one cell buys the ones' complement only; a two's complement negate costs three
(A, S, carry).  tests unchanged and green: ten byte level operations, 1666
character test tape, 8/8 full adder, fibonacci.

Also: the docs quoted clb_neg_nc at 468 and clb_sub_nc at 725, now 448 and 707.
2026-11-07 09:20:44 +08:00
dsh 557e2a1c38 In place: the ones' complement takes one cell and 17 characters
Asked whether two's complement can be done in place.  The negate cannot, but the
inversion half can and is absurdly cheap, so it is a macro now:

    clb_not_ip A        A = ~A, one cell, 17 characters, 256/256

`%rep 8 { flb; ror }` -- flip the low bit, rotate the next one down, eight times
puts the byte back where it started.  The same result through clb_neg_nc with its
carry at 0 costs 467 characters, because that path runs a synthesised slice once
per bit.

The in place two's complement itself: tried four tables and none of them exist.

    A <- ~A ^ Ci        A <- A ^ Ci        A <- A ^ B ^ Ci     A <- A ^ ~B ^ Ci
    no program up to 8 layers (all four)

Two separate reasons, both worth keeping:

* Synthesis cannot: a block has exactly one condition cell.  In place increment
  has to tell (A=1, Ci=0) -> (1,0) from (A=1, Ci=1) -> (0,1); A is the same in
  both and only Ci differs, and one condition cannot look at two cells.
* Hand writing cannot either (2 cells): `[ ... ]` is a while loop and the only
  one shot conditional this ISA has, and it eats the bit it tests.  In place
  negate wants "flip the low bit every round, then decide the carry from it",
  so both cells hold live bits and the test destroys one.

So a negate still has to land in a separate S (clb_neg_nc, 3 cells); one cell
buys the ones' complement only.  byte_op_test is ten operations now, AGENTS.md
and README.md carry the distinction and the two reasons.
2026-11-07 09:16:44 +08:00
dsh 026ad82455 The nc macros take a real carry in, they do not seed it themselves
They used to write the carry cell themselves -- set_0 inside clb_add_nc, set_1
inside clb_inc_nc / clb_neg_nc / clb_sub_nc -- which made the parameter a lie: a
cell the caller passes and the callee overwrites is not a carry input, it is a
scratch cell wearing a carry's name.  It also ruled out the thing a carry is for:
multi byte arithmetic.  The carry out of the low byte could not be handed to the
high byte, because the high byte's call would zero (or one) it first.

Now the macros only read it, and the caller decides:

    clb_add_nc A B S Ci     S = A + B + Ci      Ci = 0 plain add, or chained
    clb_inc_nc A S Ci       S = A + Ci          Ci = 1 gives A + 1
    clb_neg_nc A S Ci       S = ~A + Ci         Ci = 1 gives -A, Ci = 0 gives ~A
    clb_sub_nc A B S Ci     S = A + ~B + Ci     Ci = 1 gives A - B, Ci = 0 A-B-1

which also turns the negate into two operations for free: two's complement
negation at Ci=1 and the ones' complement (~A) at Ci=0.  The second one has its
own driver and test now (drv/raw_not_nc_byte.r8asm).

The drivers set the bit explicitly before the call, which is where that
instruction belongs -- the tapes end up the same length as before (688/430/468/725
instead of 693/433/471/730: one setup instruction moved out of the macro).

All nine byte level operations still pass, and the docs (AGENTS.md, README.md and
the four file headers) now state the carry in contract instead of describing a
constant.
2026-11-07 09:12:47 +08:00
dsh 5f0ce78861 Two's complement: negate and subtract, 3 and 4 cells
clb_neg_nc  A -> -A           3 cells  471 chars   256/256
    clb_sub_nc  A - B             4 cells  730 chars   65536/65536

Both are "invert, then add", which is all two's complement needs:

    -A      = ~A + 1
    A - B   = A + ~B + 1

so the carry cell starts at 1 (that bit is the +1) and each bit flips its input
with one flb right before the slice reads it.  Subtraction's carry out turns out
to be "no borrow": 1 when A >= B, so the same macro answers an unsigned
comparison for free.  Negation's carry is 1 only for A == 0, where -0 is 0 but
does carry out.

The bit level wrappers come along too: clb_bit_neg_nc (flb + clb_bit_inc_nc) and
clb_bit_sub_nc (flb + clb_bit_add_nc).

Tried first, and it does not work: a slice that inverts its own input.  The
table S = ~A ^ Ci, carry = ~A & Ci with 3 params answers

    r8asm: %synth clb_bit_neg_nc_synth: no program up to 8 layers

That is a model limit, not a search budget problem: a synthesised block
"sacrifices one cell, conditionally flips others", so when A is 0 the whole
block is skipped and S can only keep the 0 the wrapper gave it -- while inverting
needs S = 1 exactly then.  Unconditional flip is not expressible, so the flip has
to stay outside the slice.  Both facts are in the file comment and in AGENTS.md.

byte_op_test now covers nine operations, exhaustive, 0.72 s:

    raw_add/and/or/xor  65536 each      raw_inc  512
    clb_add_nc 65536    clb_inc_nc 256
    clb_neg_nc 256      clb_sub_nc 65536

macro_docs_test: 36 macros in 12 files, all in the house format.
2026-11-07 09:06:43 +08:00
dsh 4be8aa15ad Byte level add and increment with 4 and 3 cells: clb_*_nc
The nc slices do drive a rotation, so two more library macros fall out of them:

    clb_add_nc  A + B -> S, carry in/out in one cell   4 cells   693 chars
    clb_inc_nc  A + 1 -> S, carry in/out in one cell   3 cells   433 chars

against raw_add (6 cells, 1647) and raw_inc (5, 1214).  Both are in
r8forge_byte_op_test now, exhaustive: 65536 and 256 combinations, all pass.
clb_inc_nc has to start its carry cell at 1 -- that bit is the "+1"; the add
version starts at 0.  A rotation driver reads the low bit, throws it away and
rotates, so eating the operands is exactly what it wants.

This retracts a sentence that has been in the tree for a while: "rotation needs
A and B preserved".  It does not.  Preserving them is a separate wish (raw_*
grants it, with two more cells).  AGENTS.md said the wrong thing in the do not
retry list; that bullet now says what was really measured, which is only that a
4 cell slice asked to *preserve* A and B has no solution up to 8 layers.

Renamed for the same reason: bit_add_nc -> clb_bit_add_nc, bit_inc_nc ->
clb_bit_inc_nc, verify_add_nc.r8asm -> verify_clb_bit_add_nc.r8asm,
verify_inc_nc.r8asm -> verify_clb_bit_inc_nc.r8asm.  Measured what the prefixes
actually separate here:

    bit_raw_and  A=1 B=1 -> cells 0=1 1=1 2=1   operands preserved, has tmp
    bit_raw_add  A=1 B=1 -> cells 0=1 1=1 4=1   operands preserved, has buf
    clb_bit_and  A=1 B=1 -> cells 2=1           operands eaten, no tmp
    clb_bit_add_nc A=1 B=1 -> cells 2=1 3=1     operands eaten, no tmp

so raw means "the caller passes the scratch cell" and those variants happen to
keep their inputs, while clb means the inputs are gone.  These slices eat A and
B, so they are clb.

One self inflicted mess to own up to: I rewrote AGENTS.md with a PowerShell
Get-Content / Set-Content round trip, which on this machine decodes UTF-8 as GBK
and wrote the file back as mojibake.  Restored it with git checkout -- AGENTS.md
and redid every edit through the editor.  The work rule in AGENTS.md now names
that exact trap instead of only warning about -Encoding ascii.

Green: test.r8asm 1666, full_add 8/8, both verify_*.r8asm, byte_op_test
(65536x4 + 512 + 65536 + 256), macro_docs_test 32 macros in 10 files, fibonacci.
2026-11-07 09:03:08 +08:00
dsh adb3c8d71a bit_raw_add_nc is now bit_add_nc, and here is a 3 cell increment slice
The rename: the four cells of that slice all carry meaning -- A and B are
inputs, the third is a carry that is read on the way in and written on the way
out, the fourth is the sum.  There is no scratch cell, so SPEC.md's `raw`
("the caller passes the scratch cell") does not apply and the name now says so.
Measured before renaming: A=0 B=0 carry-in=1 gives S=1, so the cell is an input,
not a spare.

The cache survived the rename because the key is model version + params + mode +
metric + the resolved table (src/synth.cc), never the block name:
"bit_add_nc_synth: cached, 5 blocks".

verify_raw_add_nc.r8asm is now verify_add_nc.r8asm.

New asm/raw_inc_nc.r8asm, asked as an experiment ("can we even make one"):
bit_inc_nc, a 3 cell increment slice -- A, carry in/out, S -- three parameters
instead of raw_inc's five.  Table 0 4 4 2 0 4 4 2 resolved to a 4 block program
that was already in the cache, emitted tape is 54 characters, and all four input
combinations check out:

    A=0 carry=0 -> S=0 carry=0      A=1 carry=0 -> S=1 carry=0
    A=0 carry=1 -> S=1 carry=0      A=1 carry=1 -> S=0 carry=1

so S = A ^ Ci and the carry becomes A & Ci, with A eaten -- the same shape as
bit_add_nc, and like that one it cannot drive a byte level rotation (the operand
is consumed).  verify_inc_nc.r8asm drives it.

AGENTS.md: the two slices are in the self check list, the verified table and the
naming table; the "every macro" doc check now counts 30 macros in 10 files.
2026-11-07 08:53:25 +08:00
dsh 87ab064121 Delete the duplicate slice file, and say what the carry cell really is
asm/raw_add_nc4.r8asm carried the same 4 cell table as asm/raw_add_nc.r8asm --
same stat line, same metric, only the wrapper was named bit_add_nc4 -- and
nothing included it.  Gone; raw_add_nc.r8asm stays, it is the one
verify_raw_add_nc.r8asm and the docs point at.

While looking at it: is the third parameter a scratch cell, and does the slice
have a carry input at all?  Measured with verify_raw_add_nc.r8asm:

    A=0 B=0 carry-in=0 -> S=0 carry-out=0
    A=0 B=0 carry-in=1 -> S=1 carry-out=0
    A=1 B=1 carry-in=1 -> S=1 carry-out=1

so the cell is read on the way in and written on the way out -- a carry input
and a carry output sharing one cell, not a scratch.  All four parameters carry
meaning, which is why the `raw` in bit_raw_add_nc is history rather than
something SPEC.md asks for (raw = the caller passes the scratch cell).  AGENTS.md
now spells that out instead of repeating "and the scratch cell is passed by the
caller", which was wrong for this one.

The macro count in the docs drops to "every macro" rather than a number, so
adding or removing one does not leave a stale count behind.

Everything still green: test.r8asm 1666, full_add 8/8, verify_raw_add_nc,
byte_op_test 65536x4 + 512, macro_docs_test 29 macros in 9 files, fibonacci.
2026-11-07 00:26:03 +08:00
dsh 56ea288cd6 Tidy the standard library's macro docs, and check them by machine
Audited all 30 %macro in asm/.  The format was already followed almost
everywhere -- the doc block sits above the %macro, or above the %synth block
that generates its body -- but four things were wrong:

  raw_and.r8asm  the two doc blocks still carried the old names (bit_and, and)
  raw_xor.r8asm  raw_xor's first two parameters were typed Unit, not Cell
  lib.r8asm      step / back / output had no type at all ("%1: step_count")

and two files still repeated the retracted claim that set_0 only converges on 0
and 1 (raw_add_nc.r8asm, raw_add_nc4.r8asm).  Those now say what set_0 really
does -- it clears the low bit -- and stay on the point that matters for a bit
level slice: A, B and the carry must be single bits because the searched
program only tracks the low K bits.

Parameter types are now a closed set: Cell, CellBit, Unit, UnitBit, Count
(Count is for step/back's repeat count).  It is written down in AGENTS.md
together with the format, so the next macro has something to copy.

New r8forge_macro_docs_test checks the format instead of trusting review: a doc
block must exist, its ";   Macro <name>" line must match the macro, the number
of documented parameters must equal argc, and every type must be one of the
five.  Negative tested by deleting a parameter line and by renaming a block --
it reports both and exits 1.

Also fixes a real annoyance found while running the checks: %synth writes its
generated macro to the system temp directory and imports it.  That write fails
intermittently on this machine (same directory, cmd can write, r8forge cannot;
cause unknown), which turned every assembly into "cannot open ...synth.r8asm".
The body is now built in memory and written to the temp directory or, if that
open fails, to the working directory, with one stderr line saying so.

Full suite green: test.r8asm 1666 characters, full_add 8/8, verify_raw_add_nc,
byte_op_test 65536x4 + 512, macro_docs_test 30/30, fibonacci prints its ten
numbers.
2026-11-07 00:23:28 +08:00
dsh e30725247e Delete the one bit per cell layer
It was written from a wrong diagnosis.  Because the interpreters in this repo
read biz/rnz as a whole cell zero test, every packed byte program looked hung,
and the conclusion was "byte level arithmetic has to be one bit per cell".
With the interpreters fixed (86a54aa) that reason is gone: raw_add does the same
job with 6 cells instead of 32, and this repository had already deleted the same
approach once before for the same reason.

Removed: asm/byte_add.r8asm, asm/pack_byte.r8asm, examples/add8.r8asm,
examples/add8_inc.r8asm, tests/byte_add_test.cc and its CMake target.
AGENTS.md and README.md stop listing them and each keeps one paragraph saying
the direction was tried and dropped, so the next person does not add it back.

Still green after the deletion:

    asm/test.r8asm        1666 characters, 7/7 cache hits
    full_add              8/8 combinations
    verify_raw_add_nc     assembles
    byte_op_test          raw_add/and/or/xor 65536 each, raw_inc 512
    fibonacci             1 1 2 3 5 8 13 21 34 55
2026-11-07 00:07:34 +08:00
dsh 43390efe8a Byte level add, one bit per cell: 65536 combinations ok
The rotation based byte layer never ran.  Measured with r8forge_derive -2:

    raw_add   A=0,B=0 / 1+1 / 3+5 / 1+0   out empty (step limit hit)
    raw_add   A=127,B=130                 out 0 0 0 0 0, everything destroyed
    raw_and   0xF0 and 0xCC, 1 and 1, 0 and 5   out empty
    copy      A=5                         out empty (A=0 returns fine)

Not "only operand preservation is missing": set_0 (= [-]) cannot clear a cell
that holds more than one bit, and biz only answers "is this whole cell zero",
because ror does not change zero-ness.  So the bits of a packed byte are
unreadable, and the whole ror + set_0 layer has no future.  The docs now say
that instead of blaming operand preservation.

What replaces it is one bit per cell:

  asm/byte_add.r8asm   8 bit adder.  Bit i owns four adjacent cells at base+4i:
                       A, B, carry (in -> out), scratch.  The synthesised four
                       cell slice bit_raw_add_nc does the bit, clb_bit_mov moves
                       the carry into the next quartet.  A doubles as the
                       accumulator, so calling byte_add again continues the sum.
  asm/pack_byte.r8asm  eight flags -> one byte, the only direction that works.
                       bit_raw_flip_if consumes a flag into flipping bit 0 of an
                       accumulator that may already hold bits (no set_0 there).
  examples/add8.r8asm  a+b, 1308 characters.  A shared carry cell layout needs
                       only 25 cells but was measured at 2517: paying .tp travel
                       eight times beats saving seven carry cells.
  examples/add8_inc.r8asm   add 1 three times, proving the block composes.
  tests/byte_add_test.cc    r8forge_byte_add_test: runs the tapes on the ROT-8
                       machine over every input pair, 0.3 s.

Also: AGENTS.md gains the measurement table, the third instruction set
constraint (packed bytes are unreadable), the new files, and the note that
build/ has to be rebuilt with the VS bundled cmake -- scoop's 4.4 reconfigures
it and dies with "No preprocessor test for PellesC".
2026-11-06 23:40:14 +08:00
dsh 505ff509eb Rotation and synthesised slices do not mix; naming fixed
Tried the rotating byte level driver with the 4 cell slice.  It cannot work, and
the search says why: rotation needs A and B preserved, because every round reads
their current bit, while a synthesised program consumes its operands.  Rewriting
the table to keep A and B and letting %synth search it gives

    no program up to 8 layers

so 'read without destroying' does not exist in this block model at four cells.
The hand written bit_raw_add can do it (loops), which is exactly why the original
library rotates inside the macro and the synthesised one cannot.

What is committed instead:

  asm/raw_add_nc.r8asm   bit_raw_add_nc, the destroying 4 cell slice, flat cost
                         27 against bit_raw_add's 38, with the naming and the
                         comment format of lib.r8asm:

                            ;   Macro bit_raw_add_nc
                            ;   %1: CellBit A
                            ;   %2: CellBit B
                            ;   %3: CellBit Ci
                            ;   %4: CellBit S

                         The synth body is named bit_raw_add_nc_synth, so the
                         'raw' in the name marks the macro that takes cells.

  verify_raw_add_nc.r8asm  feeds A, B, Ci to one slice and prints sum and carry:
                         8/8 combinations correct, 78 characters.

The rotation limitation is written into the file header so it is not retried
blind, and the library still assembles from cache (1666 characters, 7/7).
2026-11-06 23:24:27 +08:00
dsh c6bfaca349 Drop the bit per cell adders, keep the slice
Splitting every bit into its own cell bought nothing: the 25 cell adder was a
workaround for a workaround, and it made the cell count worse than the hand
written library it was meant to improve on.

Removed: raw_add_nc (5 cell, broken driver), raw_add_nc3 (the 3 cell dead end),
raw_add_bits4, raw_add_bits8, raw_inc_bits8, verify_add8, verify_inc8.

Kept:
  asm/raw_add_nc4.r8asm            the 4 cell slice, flat cost 27 against the
                                   6 cell full adder's 38, with the two
                                   constraints written down (only the low K bits
                                   are modelled, and set_0 only converges on 0/1)
  verify_bit_add_nc4.r8asm         driver that feeds A, B and the carry to one
                                   slice and prints sum and carry, 8/8 correct

The byte level stays with the hand written library, which rotates inside the
macro and keeps whole bytes in a cell; that is 6 cells for an 8 bit add instead
of 25, at the price of not being synthesised.  %synth earns its keep on the small
bit macros (asm/test.r8asm 1714 -> 1666 characters), not on byte level tables
where the 2^16 entry truth table would be hopeless anyway.
2026-11-06 23:17:19 +08:00
dsh d480c001b1 Three cells for the destructive slice: tried, impossible here
Writing the sum back into A's cell would drop the separate S cells and cost no
extra instructions -- the driver would even get simpler.  So it was worth
trying, and it does not work: %synth reports

    no program up to 5 layers

and raising the layer bound to 8 does not help either:

    no program up to 8 layers

So the obstacle is not runtime cost, it is feasibility: three cells cannot do
' two inputs plus a carry in -> a sum plus a new carry' in this instruction
model, the same class of limit that stopped clb_bit_and.  Keeping the four cell
slice (and the 25 cell bit-per-cell adder) is the right call, and the file is
committed with that conclusion written into it so nobody retries it blind.

The layer bound is now 8 rather than 5 (src/synth.cc), since 5 was low enough to
call some feasible tables impossible; a feasible table still costs the same,
only a hopeless search takes 60% longer before giving up.

Cache untouched: restored from git after the experiments, asm/test.r8asm still
assembles from it in a fraction of a second, 7/7 hits, 1666 characters.
2026-11-06 23:09:45 +08:00
dsh 32b16eb077 Base addresses instead of 25 parameters
The eight bit adder took 25 macro arguments because every cell address was
passed in.  That was laziness: .tp accepts expressions, so the macro can take
four base addresses and add the offsets itself.

    raw_add_bits8 0 8 16 24     ; A0..7 at 0, B0..7 at 8, S0..7 at 16, carry at 24
    raw_inc_bits8 0 8 16        ; a0..7 at 0, s0..7 at 8, carry at 16

The bodies are unchanged apart from '%1 + 1' style addresses, so the tapes and
the behaviour must be identical, and they are: add8 still 2550 characters, inc8
still 1514.

Re-verified after the change, on the built in machine:
  add8  7 sums (100+50, 128+127, 200+55, 43+199, 255+0, 1+1, 0+0)  7/7
  inc8  7 values (0, 1, 5, 127, 200, 253, 254)                     7/7

Also committed two verify_*.r8asm drivers so the numbers are reproducible.
2026-11-06 23:07:09 +08:00
dsh 1b8ff08455 Eight bit adders and increments, one bit per cell
raw_add_bits8   A0..A7, B0..B7, S0..S7, carry = 25 cells
raw_inc_bits8   a0..a7, s0..s7, carry       = 17 cells

Both follow the same protocol as the four bit version: no rotation, every cell
holds a single bit, one slice per bit, and the final carry is dropped because
the caller promises the result fits.

The increment slices down to 3 cells -- a, carry (in -> out), s -- and %synth
finds cost 25 in 4 blocks for it: s = a^Ci, carry = a&Ci.  Its table was written
as 8 entries because a 3 parameter stat line wants 2^3 values, and the s bit in
the index does not matter, so the four entry pattern repeats.

One mistake worth recording: set_1 takes no arguments and acts on the current
cell, so 'set_1 %17' silently did nothing and the carry started at 0 instead of
1 -- which made 1+1 give 1 instead of 2 while 42+1 and 200+1 looked fine, since
only the low bit was affected.  The driver now does '.tp %17' then 'set_1'.

Verified on the built in machine:
  raw_add_bits8  9 sums (100+50, 128+127, 200+55, 254+1, ...) 9/9
  raw_inc_bits8  9 values (0, 1, 5, 15, 127, 200, 253, 254, ...) 9/9

Tapes: 2550 and 1514 characters.
2026-11-06 23:02:09 +08:00
dsh 7cf2fabeb7 A bit per cell adder, and it works
The chained version kept every bit in one cell and rotated, which broke the rule
that set_0 needs a cell holding 0 or 1.  This one gives each bit its own cell
instead:

    %1..%4  A0..A3      %5..%8  B0..B3
    %9..%12 S0..S3      %13     carry

    erase carry
    bit_add_nc4 A0 B0 carry S0
    ... one slice per bit, no rotation at all
    last carry dropped (assumes A+B fits)

No rotation means every cell stays a bit, which is the invariant set_0 needs.
Verified against the built in machine over eight sums including 0+0, 1+1,
15+0 and 9+6: 8/8 correct, and the cell dump after a run shows only the S bits
set, so the operands and the carry are consumed as the table says.

Cost: it needs three cells per bit plus the carry (13 for 4 bits, 25 for 8)
instead of 4 rotating cells, and the expansion is longer because each slice now
has a fixed pair of operands.  That is the price of not breaking the invariant,
and it is why the original hand written library rotates inside the macro instead:
it keeps whole 8 bit cells and loops over the bits itself.
2026-11-06 22:06:58 +08:00
dsh cbadc3936a Document what set_0 really is
Checked instead of assuming, and it explains the chained hang:

    '-'  flb  flips bit 0                    cells[dp] ^= 1
    '['  biz  if the cell is zero, jump past the matching ']'
    ']'  rnz  if the cell is not zero, jump back to the matching '['

so set_0 = [ - ] is 'while the cell is not zero, flip its lowest bit', which only
terminates for 0 and 1.  Measured with the cell dump: X=5 goes 5 -> 4 -> 5 -> 4
until the step limit, X=0x80 never changes, and in both cases the tape never
reaches the next instruction.  erase = %rep 8 { set_0; ror } hangs on the same
set_0, so it cannot clear an arbitrary cell either.

That is the whole story of the 8 bit chain: after a slice and a ror the S cell
holds 0x80, the next wrapper calls set_0 on it, and there is no way out.  The
slice itself is fine, as the dump showed (A and B fully cleared, carry a clean
0/1).

Consequence: a cell always holds one bit in this world, so clearing has to
happen while it still is a bit, not after it has been rotated out.
2026-11-06 22:04:46 +08:00
dsh 13b831ec8b A 4 cell adder slice: the carry borrows the scratch cell
Asked why the slice still needs 5 cells.  It does not: the scratch cell was
doing nothing the carry could not do, so the 4 cell version is

    p1..p4 = A, B, carry (in -> out), S

and the table says S = A^B^Ci, carry = AB|AC|BC, A and B consumed.  %synth
finds cost 27 in 5 blocks for it -- the same tape length as the 5 cell version
(cell count is not part of the cost metric, only the instructions are) but one
cell cheaper, 73 characters for a single slice.

All eight input combinations verified through the built in machine.

Diagnosis of the chained hang, from dumping the cells after one slice plus the
ror rotation:

    A=1 B=0  ->  cells: 4=80        (only the rotated sum bit survives)
    A=1 B=1  ->  cells: 1=1         (only the carry)

so a slice leaves A and B fully clear, and the carry is a clean 0/1.  The dirty
one is S: after the rotation its bit 7 is set, and set_0 in the next slice does
not remove it -- the dump after two slices shows 4=81 and, worse, the tape then
runs off the end instead of reaching 'output S'.

So the fix is not in the slice but in the driver: it must not rotate the sum
into a cell that the next slice clears, or must clear the whole cell (set_cell,
not set_0 over the modelled bits).  That is the next step, together with
re-checking whether set_0 is the right primitive here at all.
2026-11-06 21:31:04 +08:00
dsh 18bf78273e A 5 cell adder that ignores carry in and out
The idea: for an adder whose operand sum is known not to overflow, there is no
need for a separate carry in cell or a carry out cell -- the carry can live in
one cell and be overwritten each bit, and the final carry is simply dropped.
That takes the slice from 6 cells (A, B, Ci, S, Co, tmp) down to 5 (A, B,
carry, S, tmp).

The slice was not hand written: the table was derived from S = A^B^Ci and
carry = AB|AC|BC, and %synth searched it with metric flat:

    bit_add_nc_synth: tape cost 27 in 5 blocks   (1891406 states)
    bit_raw_add_synth (the 6 cell full adder):   tape cost 38 in 5 blocks

so 11 units of the metric cheaper, about 29%, plus one cell less per slice.

Verified: all eight input combinations of a single slice are correct through the
built in machine (A, B, Ci -> S), including the all zero one.

Known limitation, found rather than guessed: the synthesised program only
touches the low K bits of each cell, the bits the truth table knows about.  The
caller therefore has to hand it cells whose high bits are zero.  Chaining slices
with ror breaks that: the rotated cell keeps bit 7, and a block that loops until
its cell reaches zero can never get there.  So the 8 bit raw_add_nc hangs; the
slice itself is fine, the driver needs to move each bit into a clean cell first.

Also added: r8forge_derive <file> -1 addr=value ... runs a tape with chosen cells
and prints OUT, which is how the slice was checked.
2026-11-06 21:19:19 +08:00
dsh 14af0ca6ff Standard library: flat metric, cache pre-warmed and committed
Every synth block in asm/ now says 'metric flat', so the seven block bodies are
optimised without the .tp walk and therefore do not depend on where the caller
puts its cells.  The resulting bodies are cached in .r8forge_cache/ and the
cache is committed, so a fresh clone assembles the library without waiting for
a single search.

asm/test.r8asm: 1674 -> 1666 characters.

The seven tables were re-derived after the switch and all match the hand written
implementations bit for bit (bit_raw_add still 0 9 10 19 12 21 22 31 repeated,
bit_raw_inc 0 5 6 11, and so on), so this is a pure length win.

One caveat: bit_raw_add's flat search still runs out of state budget (700M, the
table stops fitting in a laptop) and falls back to the layer answer, which is
what got cached for it.  The other six converge in milliseconds; the whole warm
up took 396 seconds, almost all of it that one block.
2026-11-06 18:55:18 +08:00
dsh 30089af06d Rewrite the bit macros as %synth blocks
The eight bit-level macros in asm/ are now synthesised instead of hand written.
Their tables were not typed in by hand: r8forge_derive (new, src/derive.cc)
runs the OLD implementation over every input combination and reads the cells
back, so the replacement is bit-for-bit identical, quirks included.  big two
findings:

  * a synth block assumes the parameters that do not take part in the
    computation start at 0 (that is what compress_stat_space means).  These
    macros are called repeatedly inside a loop, so S/Co/tmp arrive dirty; each
    one now has a thin %macro wrapper that clears them and then calls the
    synthesised body.  With that, bit_raw_add derives to exactly the old table
    (0 9 10 19 12 21 22 31 repeated) and bit_raw_and to 0 1 2 7 repeated.
  * clb_bit_and stays hand written.  Three parameters leave no scratch bit and
    "and" needs both inputs alive at once, so it needs nested biz; the searcher
    exhausts nine layers over three planes without finding anything.  That is
    the model's expressive limit, not a shallow search.

asm/test.r8asm assembles to 1674 characters, down from 1714, with identical
block semantics.

%synth results are cached in .r8forge_cache/ keyed by the table, so the
twenty minute tape search happens once per table rather than once per build.

Note on verification: r8forge_derive validates one block at a time, which is
what the tables above are.  The little VM inside it is not solid enough to
vouch for whole programs (fibonacci prints two numbers instead of ten), so
"the whole library still computes the right answer end to end" is NOT verified
here -- that needs the real ROT-8 virtual machine.
2026-11-06 11:04:29 +08:00
dsh 19cbfb36f6 R8Forge: assembler and searcher in one repo, %synth directive
The searcher stops being a separate program: %synth is an assembly-time
directive.  It describes a truth table, the assembler runs the search while
parsing, and the block list comes back as ready-to-paste r8asm.

Merging is what makes the cost model honest.  The price of a layer is
  cost = 2 (biz + rnz) + sum(move distance + op cost)
and the move distance depends on the call site's cell layout, not on anything
the assembler knows in advance: the same five-layer adder is 87 characters
with the cells adjacent and 136 with them two apart.  Only the side that sees
the layout can price it, which is now the assembler itself.

Working: the assembler (asm/test.r8asm still assembles to the same 1714
characters), the searcher (bit planes + backward one-step lookup, full_add in
5 layers, proven shortest in 7.2s), and %synth parsing plus the search itself.
Not working yet: splicing the synthesised body into the tape -- a synth call
fails loudly with 'unknown macro' instead of emitting anything, so nothing can
silently assemble wrong.  The two ways to finish it are in the README.

Also carries over the CMake fix: no set(CMAKE_CXX_FLAGS ...), which used to
drop /EHsc, push -O3 into Debug and fight /RTC1.
2026-11-05 23:59:15 +08:00