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.
7.3 KiB
给接手的 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 都能跑。 - 全绿基线(这台机器约 1 分钟;命令见下)。
- 另一个仓库
../ROT-8-viz(forkdsh/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 -j 4` 一次跑完 8 条,约 9 秒)
r8forge asm/test.r8asm # 64513 字符(每个标准宏至少一次 + 每个语言特性)
r8forge_byte_op_test # 21 项(divmod 16384 组、digits 2048、undigits 4096)
r8forge_examples_test # 16 个 example + asm/test.r8asm,核对头部 `; out`/`; in`
r8forge_macro_docs_test # 48 macros in 22 files
r8forge_synth_test examples/full_add.r8asm # all eight combinations ok
r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0
asm/test.r8asm 的纸带必须留在 65536 条指令以下(ROT-8-viz 的 INS_SIZE),所以里面
只有"每个宏一次 + 两轮 hash",现在离上限只剩 ~1k。加东西前先算长度。
r8forge_byte_op_test 是唯一按返回值判断字节级对错的;其它自检只证明"汇编得出来"或
"位级正确"。r8forge_derive 会检查汇编错误(漏 %include 时纸带是截断的,以前不看 error
位会跑出一个看起来正常的错答案)。
工作方式(踩过的)
-
写结论之前先对虚拟机:字节级结论必须能被 ROT-8-viz 复现。注意它现在默认串行输出, 要比数值流就加
-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(默认串行)。 -
一次会话很难把结论留在对话里 —— 落进 commit message 和文件注释。
语义上会咬人的几条
'-' flb 翻转最低位 cell ^= 1
'+' ror 右旋整个 cell (注意:和 Brainfuck 的 +/- 不一样,写仿真器时别按常识猜)
'[' biz 最低位 0 -> 跳到匹配的 ']' 之后
']' rnz 最低位 1 -> 跳回匹配的 '['
biz/rnz判的是cell & 1,不是"整格是否为零"。所以set_0=[-]只清最低位 (255→254、128 原样、5→4),清整格要%rep _CELL_SIZE { set_0; ror }(erase)。- 条件块的身体必须回到它自己的条件 cell(净位移 0):
dp是汇编期常量,跳过/进入两条 路径的dp不一致之后所有.tp全部错位(症状:dp跑到 1023)。set_0的身体不移动、clb_bit_mov最后.tp before再flb(顺便吃掉条件)。 - 合成块只保证"输出位初值为 0" 的调用点(
compress_stat_space把初值无关的位清成 0), 所以位级包装宏里的set_0不能删 —— 删了clb_mul62064/65536 错、clb_divmod14742/16384 错、clb_digits2048/2048 错(其中一个 HANG)。见 SPEC §3.6。 - 位宽是
_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写成整格零判断,于是 所有字节级程序看起来都在死循环 —— 别再把库判成坏的。
下一步
候选、想清楚但没做的优化、以及工具侧的小尾巴都收在 TODO.md;
SPEC.md §12 是"别试"的结论,不是待办。
索引
| 想查 | 去哪儿 |
|---|---|
%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 |