Files
R8Forge/AGENTS.md
T
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

13 KiB
Raw Blame History

给接手的 agent 的话

这是 R8Forge 的工作手册:怎么干活、哪些坑已经踩过、现在交接到哪儿。契约和数字不在 这里 —— 那在 SPEC.md;设计推理的长文在 docs/。

这份文件入库,只写项目事实。只对某台机器/某个会话成立的东西(VS 的 cmake 路径、 PowerShell 的编码坑、git 身份和 push 提权、临时目录抽风……)放在 AGENTS.local.md, 它被 .gitignore 忽略、换机器重新写一份。新接手的环境先看那份。

动手前请把这份文件读完(约 5 分钟),需要细节时再按索引跳。历史教训里最贵的一条是: 有一轮把"移位-加法乘法器更快"当成新发现重推了一遍,其实早被否过又复活过 —— 结论都在 docs/byte-ops.md 和 SPEC §12 里,先读再推翻。

现在是什么状态

  • 汇编器 + 搜索器 + 标准库都齐了:%synth 汇编期合成、位级/字节级/原地/乘除/数字 转换(clb_digits ↔ clb_undigits)、动态循环、串行 ASCII I/O 都能跑。
  • 有符号数已经做完(SPEC §5.4 的约定、§7.10 的实现):clb_digits_signed(-0042 这种显示)、clb_divmod_signed(截断除法、余数随被除数)、计算器的一元负号 (examples/calc.r8asm)。加、减、乘按二补码天然正确,没有改。
  • 计算器是 3 格 RPN 栈(64983 字符):数字压栈、运算符立刻算(弹二压一)、. 显示 栈顶但不动栈。旧的两寄存器版算不了嵌套(1 2 + 3 4 * + . 打 0007,现在 0015)。
  • examples/term.r8asm 是行编辑终端(21721 字符):4 格行缓冲 + 退格编辑 + 回车/EOF 提交 + 按行首字符分派命令(l 长度、r 反着打、q 退出)。表头那组 in lhi 就能 测到整条分派链(EOF 会把没提交的行也提交掉)。
  • 全绿基线(这台机器约 1 分钟;命令见下)。
  • 另一个仓库 ../ROT-8-viz(fork dsh/ROT-8-viz,分支 main)是权威虚拟机 + 可视化:默认 I/O 是串行 ASCII(cell ≥ 8 位),数值 I/O 用 -n / --numbers, 另有 7E1 帧(--parity / --stop / --7e1)。clb_digits 产出的 ASCII 直接喂它的 OUT。

构建与自检

cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release

# 注意:必须用给 build/ 配的那个 cmake(PATH 上的另一个版本会重新配置,然后死在
# "No preprocessor test for PellesC")。本机路径见 AGENTS.local.md。

# 当前基线:都通过,别弄坏(`ctest --test-dir build -C Release -j 4` 一次跑完 8 条,约 12 秒。
# VS 是多配置生成器,**`-C Release` 不能省**,否则 8 条全报 "Not Run")
r8forge asm/test.r8asm                      # 62351 字符(除两个有符号包装宏外每个宏一次 + 每个语言特性)
r8forge_byte_op_test                        # 23 项(divmod 16384 组、digits 2048、digits_signed 2048、divmod_signed 4202、undigits 4096);8/11/16 位真跑,17 位以上打印 skipped
r8forge_examples_test                       # 19 个 example + asm/test.r8asm,核对头部 `;   out`/`;   in`
r8forge_macro_docs_test                     # 55 macros in 23 files
r8forge --opt asm/test.r8asm                # 纸带窥孔优化 62351 -> 56338(>< 净位移、+ mod W、- mod 2)
r8forge_tape_opt in.rot8 out.rot8           # 同一优化,但作用在已有纸带上
r8forge_tape_run t.rot8 --profile          # 剖面:指针移动占 66~73% 步数(实测,见下)
r8forge_synth_test examples/full_add.r8asm  # all eight combinations ok
r8forge_derive verify_loop.r8asm -1 0=5     # out 5 0
powershell -File tests\widths.ps1             # 位宽矩阵:每个位宽一套工具链 + 断言(约 20 分钟)
powershell -File tests\widths.ps1 -Widths 32  # 32 位:整套 10 个 target 能建,byte_ops 只打印 skipped

位宽上限是 32(每份 VM 的 cell 都是 uint32_t;CMake 里 -DR8FORGE_CELL_SIZE 越界直接 FATAL_ERROR,所以别再指望 C++ 报错才发现)。想往上要按 SPEC §13 的清单同时改五份 VM、 geometry.hh、汇编器的立即数类型和 ROT-8-viz 的 rot8_data。drv/ 里的驱动必须 用 .var D _CELL_SIZE * 30103 / 100000 + 1 算位数 —— 写死 4 格导致 digits 三项在 8/16 位 一直挂着,2026-11 才修。

asm/test.r8asm 的纸带必须留在 65536 条指令以下(ROT-8-viz 的 INS_SIZE;现在的 虚拟机缓冲是按纸带长度现算的,这条是历史口径 + 交叉验证,别指望它)所以里面只有"每个宏 一次 + 两轮 hash",现在离上限只剩 ~3.2k。两个有符号包装宏不在里面:它们各自要把 clb_digits / clb_divmod 再展开一份(+12.1k / +5.6k)。它们的回归是 examples/signed_demo.r8asm(examples_test 会跑),穷举在 r8forge_byte_op_test。

r8forge_byte_op_test 是唯一按返回值判断字节级对错的;其它自检只证明"汇编得出来"或 "位级正确"。r8forge_derive 会检查汇编错误(漏 %include 时纸带是截断的,以前不看 error 位会跑出一个看起来正常的错答案)。

工作方式(踩过的)

  • 写结论之前先对虚拟机:字节级结论必须能被 ROT-8-viz 复现。先确认那台机器的 viz 是重编过的—— 旧二进制的串行 INP 只改低 7 位(2026-11 改成整格写入),症状是交互程序打出 > 0000, 曾经被误判成"纸带坏了"。注意它现在默认串行输出, 要比数值流就加 -n:

    ROT-8-viz/build/Release/rot8_test.exe -n <tape.rot8>   # 每个 OUT 打一行十进制
    r8forge_derive <src.r8asm> -1                          # 另一份实现,out 逐位比
    r8forge_tape_run <tape.rot8> [addr=value...]           # 直接喂纸带的第二份实现
    
  • 提交身份是 dsh,不是仓库主人:两个仓库都用 dsh <dsh@gitea.local>(仓库主人的 StarCells <peng080306@foxmail.com> 别用)。具体命令和本机的 git 配置见 AGENTS.local.md。

  • 数字要能被别人复现:§1.3 的口径写死了怎么量(最小驱动、不带 output);改宏之后 顺手跑一遍基线,别只信自己这次跑出来的数。

  • 交互程序这样测:r8forge_tape_run t.rot8 -i "12+34="(字符喂给 inp,低 7 位,读空后为 0), r8forge_derive <src> 0 -i "..." 是同一份输入的第二个实现;例程把输入写在头部 ; in ...,r8forge_examples_test 会自动喂。实时终端那一侧在 ROT-8-viz(默认串行)。

  • 代价的大头是"走"不是"算":tape_run --profile 实测,计算器 71.1%、全家桶 73.0% 的步数是 >/<,旋转只占 7%、翻转 46%。这台机器没有随机寻址,每次访问的代价就是 |Δ地址|,所以布局才是性能旋钮:clb_digits 的 13 格草稿重排一轮,全家桶 64513 -> 62351 字符、236439 -> 202159 步(SPEC §7.7);--opt 再省 1415% 步数,正是因为它砍的是往返移动。

  • 一次会话很难把结论留在对话里 —— 落进 commit message 和文件注释。

一条硬规矩:不许动机器语义

除了 INP/OUT 的语义(那是宿主接口,允许按需定义),机器语义在没有明确要求的情况下一个字都 不许改:8 条指令的行为、biz/rnz 判 LSB、+ 是右旋、- 翻最低位、步数怎么算、 内存是 259 格环、纸带从第一条指令跑到尾 —— 全部冻结。

这条规矩是有来由的:三份实现(derive / tape_run / ROT-8-viz)互为对拍,任何一边"顺手修一下" 都会让另外两边看起来是错的,而我们没有第二份规格可以裁决。要改语义,先在 SPEC 里写清楚、 再四份一起改(见 §13),否则只改工具和视图。

语义上会咬人的几条

'-'  flb  翻转最低位        cell ^= 1
'+'  ror  右旋整个 cell     (注意:和 Brainfuck 的 +/- 不一样,写仿真器时别按常识猜)
'['  biz  最低位 0 -> 跳到匹配的 ']' 之后
']'  rnz  最低位 1 -> 跳回匹配的 '['
  1. biz/rnz 判的是 cell & 1,不是"整格是否为零"。所以 set_0 = [-] 只清最低位 (255→254、128 原样、5→4),清整格要 %rep _CELL_SIZE { set_0; ror }(erase)。
  2. 条件块的身体必须回到它自己的条件 cell(净位移 0):dp 是汇编期常量,跳过/进入两条 路径的 dp 不一致之后所有 .tp 全部错位(症状:dp 跑到 1023)。set_0 的身体不移动、 clb_bit_mov 最后 .tp before 再 flb(顺便吃掉条件)。
  3. 合成块只保证"输出位初值为 0" 的调用点(compress_stat_space 把初值无关的位清成 0), 所以位级包装宏里的 set_0 不能删 —— 删了 clb_mul 62064/65536 错、clb_divmod 14742/16384 错、clb_digits 2048/2048 错(其中一个 HANG)。见 SPEC §3.6。
  4. 位宽是 _CELL_SIZE(默认 11),宏里写 %rep _CELL_SIZE 就与位宽无关;改几何要照 SPEC §13 的清单四份虚拟机一起改。换位宽后旧纸带要重新汇编(写死的 %rep 8 在新位宽下 可能永远跑不完)。

已经确认走不通的(别重试,理由见 SPEC §12)

  • 3 个 cell 的加法切片:层数 5/8 都报 no program up to N layers(3 cell 的自增/取负 切片有解,两个操作数塞不进 3 个 cell)。
  • 原地写回的 %synth 表(A←~A^Ci 等四个)全部无解 —— 一个合成块只有一个条件 cell, 区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"。但手写可以:clb_inc_ip 是 89 字符。
  • 让切片自己在输入上取反、4 cell 加法切片保留 A、B:都无解。想保留操作数用 6 cell 的 bit_raw_add。
  • 字节级真值表(2^16 项)交给 %synth:搜索空间不可行。
  • "每个 bit 一个 cell"再拼字节级运算:能跑通但没有意义,实现已删(一个 cell 能放一个字节、 位也读得出来)。要拼字节级就用 raw_* / clb_*_nc / clb_*_ip。
  • 字节级程序"跑不动"先怀疑虚拟机:仓库里曾有三份解释器把 biz 写成整格零判断,于是 所有字节级程序看起来都在死循环 —— 别再把库判成坏的。

刚做完的三件大事:有符号数、RPN 栈、终端纸带

二补码、-0042 显示、截断除法、静默溢出,约定在 SPEC §5.4、实现在 §7.10。 clb_digits_signed / clb_divmod_signed 都是包装(真活还是 clb_digits / clb_divmod 干的),加、减、乘一个字没改。两条容易踩的:

  • 符号位靠 rol + bit_copy + ror 读(49 字符)。别换 clb_bit_mov —— 它吃掉源位, 于是 1024 会打成 0000(examples/signed_demo.r8asm 就是这条例子的回归)。
  • 标志位在 biz/rnz 里必须被吃掉才能退出,所以"用完还要留"的符号位要搬到另一格 (clb_bit_mov),这就是为什么 clb_divmod_signed 要 T1、T2、F 三格。

计算器接着换成了 3 格 RPN 栈(S0 栈顶 / S1 / S2):运算符立刻算、. 是真 peek、 一元负号按栈深判(DEPTH == 0)。旧的"两寄存器 + 待结算 OP"版本算不了嵌套 (1 2 + 3 4 * + . 打 0007,现在是 0015)。栈深只有 3 格是纸带逼出来的: 一格一次 copy(约 500 字符),4 格就顶上 65536 了。挪栈的次序不能反(从高往低搬)。

examples/term.r8asm 又是另一种东西:**行缓冲(左对齐 + LEN)+ 退格编辑 + 回车/EOF 提交

  • 命令分派**(l 长度、r 反着打、q 退出)。三条硬教训:
  • "else" 必须用标志格写:biz 只在最低位是 1 时进身体,"没命中就做 B"不能靠推断 —— 先 set_1 一个 FLAG,命中那支清 0,出块再看。而且 biz 的条件格是当前 dp, 所以顺序必须是"先 set FLAG、再 .tp 到条件格、再 biz"(写反了就是每轮都命中)。
  • 被减数会被吃掉:分类用的 clb_sub_nc 吃操作数,所以回显/追加都要用副本 CE; 拿 C 当追加源的那一版,行缓冲永远是空的。
  • 热单元格要挨着排:copy/clb_sub_nc/clb_nonzero 内部都有 .tp,有的还在 %rep _CELL_SIZE 里 —— 常数格排到 22..28 时整条纸带 33k,挤进 0..27 就回到 21.7k。

下一步

候选、想清楚但没做的优化、以及工具侧的小尾巴都收在 TODO.md; SPEC.md §12 是"别试"的结论,不是待办。眼下最靠前的是 TODO 里的"交互计算": 迷你 printf(做完终端纸带之后用处要重新评估)、把终端纸带接上计算器(卡在纸带预算)、 以及栈要不要再深一格。

索引

想查 去哪儿
%synth 语法语义、几何、宏契约、验证矩阵、边界、维护清单 SPEC.md
除法为什么这么写、实测步数、没做的优化 docs/divmod.md
字节级库的取舍、原地补码的突破、乘法器那一课 docs/byte-ops.md
上游语言规格(%synth 不在里面) r8asm_rev/SPEC.md(本机路径见 AGENTS.local.md)
ROT-8 指令集(BIZ/RNZ 判 LSB) ../ROT-8-viz/README.md 与 src/rot8.c