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

21 KiB
Raw Blame History

给接手的 agent 的话

这个文件是给下一个会话(或者下一个 agent)看的交接说明。内容都是这个仓库里实测过的结论, 不是推测;每条后面基本都跟着一次失败的尝试,别再踩。

工作方式(上一轮踩到的)

  • 超过 ~30 秒的命令一律丢后台(run_in_background),前台只做短轮询。 一次搜索可以跑 680 秒、缓存预热 885 秒,前台干等会撞上客户端和 API 的传输超时。

  • 别让大段 stderr 进上下文。PowerShell 遇到原生命令出错会吐一整套 NativeCommandError 堆栈;用 2>$null 收干净,判断结果靠 $LASTEXITCODE 和 stdout。

  • 写含中文的文件用编辑工具(UTF-8)。不要用 PowerShell 做"读-改-写":这台机器上 Get-Content 默认按 GBK 读 UTF-8 文件,再 Set-Content -Encoding utf8 写回去就是 二次转码、整篇变乱码(AGENTS.md 就这么被我毁过一次,靠 git checkout -- AGENTS.md 救回来)。Set-Content -Encoding ascii 更糟,汉字直接变 ? (examples/full_add_flat*.r8asm 就这么坏过一次)。

  • 构建要用 VS 自带的 cmake:build/ 是 Visual Studio 18 2026 生成器配的, 直接敲 PATH 上的 scoop cmake(4.4)会因为版本不一致重新配置,然后死在 No preprocessor test for "PellesC"。用这个:

    "C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe" \
        --build build --config Release
    
  • %synth 的临时文件:汇编器把生成的宏写到系统临时目录再 import,然后删掉。这台机器上 这一步偶尔会失败(r8asm: cannot open 'C:\Users\...\Temp\xxx.synth.r8asm';同目录下 cmd 能写、r8forge 不能,原因没查清,重跑一次可能就好了)。现在代码会退回到当前工作 目录重试,stderr 留一句 <临时目录> is not writable, using <cwd>。看到这句不用管; 看到 cannot write the synthesised macro anywhere 才是真坏了。*.synth.r8asm 已在 .gitignore 里。

  • 会话很长时传输容易失败,重要结论要落到 commit message 和文件注释里,别只留在对话里。

  • 写结论之前先对虚拟机:这个仓库最贵的一次事故就是虚拟机语义写错,然后在错的东西上 写了一整套"实测结论"(见「字节级运算」)。字节级结论必须能被 ROT-8-viz (C:\Users\peng0\git\ROT-8-viz,权威实现)复现。

  • 推代码:origin = https://gitea.starcells.ltd/dsh/R8Forge.git。这台机器上 schannel 会报 schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS, fetch / push 都得走 openssl 后端 —— 已经写在这个 repo 的 local config 里 (git config http.sslBackend openssl),正常 git push 就行。 如果当前会话的沙箱是 workspace-write,push 还要一次提权:git 的凭证助手要开命名管道, 沙箱会拒绝(sh.exe: fatal error - couldn't create signal pipe, Win32 error 5 + could not read Username);danger-full-access 下不需要。fetch 两种模式都不需要 (仓库可匿名读)。

构建与自检

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

# clang-cl(scoop 的 llvm,比 MSVC 严格,能抓出模板推导问题)
clang-cl /nologo /std:c++20 /EHsc /O2 /I include src/r8asm.cc src/synth.cc tests/asm_test.cc /Fe:r8forge.exe

自检:

r8forge asm/test.r8asm                            # 应 exit 0,1666 字符,7/7 命中缓存
r8forge_synth_test examples/full_add.r8asm        # all eight combinations ok
r8forge verify_clb_bit_add_nc.r8asm               # 4 cell 加法切片(进位进->出)
r8forge verify_clb_bit_inc_nc.r8asm               # 3 cell 自增切片,进位同样进->出
r8forge_byte_op_test                              # 字节级库:12 个操作穷举,0.8 秒
r8forge_macro_docs_test                           # asm/ 里每个宏的注释格式

r8forge_byte_op_test 是唯一按返回值判断字节级对错的;前三个只证明"汇编得出来"或 "位级正确"。

r8forge_derive 是验证工具:

r8forge_derive <file.r8asm> 4 0 2         # 按输入组合跑,打印 stat
r8forge_derive <file.r8asm> -1 0=100 1=50 # 指定 cell 初值跑一遍,打印 out
r8forge_derive <file.r8asm> -2 0=100      # 同上,另外倒出所有非零 cell

注意 -1/-2 是拿汇编源码跑的(内部会先 import_file),不能直接喂 .rot8 纸带。 r8forge_tape_run <file.rot8> [addr=value...] 是第二个实现,直接喂纸带,用来交叉验证 derive(两个实现同时写错的可能性比一个低)。

指令集语义(这些搞错会浪费一整轮)

'-'  flb  翻转最低位        cells[dp] ^= 1
'+'  ror  右旋整个 cell
'['  biz  最低位为 0 -> 跳到匹配的 ']' 之后
']'  rnz  最低位为 1 -> 跳回匹配的 '['

最后两条的关键在"最低位"三个字:biz/rnz 判的是 cell & 1,不是"整格是否为零"。 权威实现是 ROT-8-viz/src/rot8.c:

void rot8_biz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 0) { ... } }
void rot8_rnz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 1) { ... } }

由此推出两条关键约束:

  1. set_0 = [-] 清的是最低位,不是整个 cell。 set_0 把 255 变成 254、把 128 原样留着、把 5 变成 4。要清整个字节就 %rep _CELL_SIZE { set_0; ror }(erase 就是这么写的)。一个字节的位能读: ror 若干次把目标位转到最低位,再 biz。
  2. 合成的程序只碰每个 cell 的低 K 位(K = 参与运算的输入位数),高位不追踪。 所以 %synth 出来的块只适用于"每格一位"的世界。

写手写宏还有第三条:dp 是汇编期算的常量,而 [...] 的 body 在运行期可能被跳过。 所以每个条件块的身体必须回到它自己的条件 cell(净位移 0),否则跳过路径和进入路径的 dp 会不一致,之后所有 .tp 全部错位 —— 症状是 dp 跑到 1023 这种地方( r8forge_tape_run --trace 能直接看到)。库里的宏都遵守:set_0 的身体不移动、clb_bit_mov 的身体最后 .tp before 再 flb(顺便把条件吃掉)。

曾经这里还写过第三条("多字节 cell 的位读不出来")—— 那是把 biz 当成 Brainfuck 的 整格零判断推出来的,错的,已删。

字节级运算(一个 cell 一个字节)

结论:库里的字节级宏是对的,穷举全过。r8forge_byte_op_test 实测(0.7 秒):

宏 驱动 纸带 结果
raw_add(a+b,含进位) drv/raw_add_byte.r8asm 1647 字符 65536/65536
raw_and drv/raw_and_byte.r8asm 639 字符 65536/65536
raw_or drv/raw_or_byte.r8asm 575 字符 65536/65536
raw_xor drv/raw_xor_byte.r8asm 463 字符 65536/65536
raw_inc(a+进位) drv/raw_inc_byte.r8asm 1214 字符 512/512
clb_add_nc(a+b+进位,4 cell) drv/raw_add_nc_byte.r8asm 688 字符 65536/65536
clb_inc_nc(a+进位,3 cell) drv/raw_inc_nc_byte.r8asm 430 字符 256/256
clb_neg_nc(~a+进位,3 cell) drv/raw_neg_nc_byte.r8asm 448 字符 256/256(取负)
同上,进位 0 drv/raw_not_nc_byte.r8asm 447 字符 256/256(反码 ~a)
clb_sub_nc(a-b,4 cell) drv/raw_sub_nc_byte.r8asm 707 字符 65536/65536
clb_not_ip(~a,原地,1 cell) drv/not_ip_byte.r8asm 17 字符 256/256
clb_inc_ip(a+1,原地,2 cell) drv/inc_ip_byte.r8asm 74 字符 256/256
clb_neg_ip(-a,原地,2 cell) drv/neg_ip_byte.r8asm 90 字符 256/256
asm/fibonacci.r8asm — 8761 字符 跑出 1 1 2 3 5 8 13 21 34 55,和文件注释一致

raw_* 保留操作数(A、B 原样还回来),clb_*_nc 把 A、B 吃干净 —— 所以后者能省掉 Co 和 tmp:4 cell 加法/减法、3 cell 自增/取负。两者都用轮转驱动,差别只在 "操作数要不要还回去"。

clb_*_nc 的进位 cell 是真正的进位输入:宏自己不动它的初值(曾经写错过 —— 加法里 set_0、自增里 set_1,那就不是输入了,而且把多字节串接堵死了)。 调用者给 0 就是普通运算,给 1 就是"自带 +1"的那种,或者把上一字节的进位输出接过来串。

补码

-A = ~A + 1、A - B = A + ~B + 1,所以取负/减法都是"取反 + 加法/自增", 那个 +1 由调用者通过进位输入给:

宏 做法 Ci=1 Ci=0
clb_neg_nc A S Ci 先 clb_not_ip A 把整个字节原地取反,再走 clb_inc_nc -A(补码取负) ~A(反码)
clb_sub_nc A B S Ci 先 clb_not_ip B 把整个字节原地取反,再走 clb_add_nc A - B A - B - 1

取调整字节一次、提到循环外面,比"每 bit 取反一次"更短(也少两个 flb 包装): clb_neg_nc 468 → 448、反码那一版 467 → 447、clb_sub_nc 725 → 707。 B 本来就会被加法吃掉,所以在原地取反它没有任何代价。

clb_sub_nc 的进位输出是没有借位(A >= B 时为 1),所以它顺带就是无符号比较; clb_neg_nc 的进位输出只在 A 原本是 0 时为 1(-0 = 0 但确实进了位)。

取反必须发生在切片外面:想让 %synth 自己取反(表 S=~A^Ci、进位 ~A&Ci,3 参数) 报 no program up to 8 layers。原因是模型只会"牺牲一个 cell → 条件翻转别的 cell", A=0 时整块跳过、S 只能留在 0,而取反要求 A=0 时 S=1 —— "无条件翻转"表达不出来。

原地(结果回到原来的 cell)

宏 干什么 cell 纸带 穷举
clb_not_ip A A = ~A(反码) 1 17 256/256
clb_inc_ip A T A = A + 1 2 74 256/256
clb_neg_ip A T A = -A(补码取负) 2 90 256/256

对比写回 S 的切片版:clb_inc_nc 430(3 cell)、clb_neg_nc 448(3 cell)—— 原地版短 5 倍、少一个 cell。clb_neg_ip 就是 clb_not_ip + clb_inc_ip。

"原地补码不可能"这个结论是错的,这里记一下它是怎么错的(别再复现同样的推理):

  • %synth 的四个原地表(A←~A^Ci、A←A^Ci、A←A^B^Ci、A←A^~B^Ci)确实全部报 no program up to 8 layers,原因是一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"。这一步是实测,没问题。
  • 错在把它当成了整条路的结论。手写不一定要照逐位进位链写。

真正可行的算法换个思路,不去逐位测进位:

  1. 用 [ ... ] 的自然语义(最低位非零就继续)把最低位连续的 1 清掉(flb + ror), 遇到第一个 0 时退出循环;
  2. 那个 0 翻成 1 —— 输入是全 1(0xFF)时跳过,正好就是回绕那一格;
  3. 剩下的位置只旋转,转满八格为止。

卡点变成"还要转几格",而 cell 只有两个。解法是把计数塞进 T 的位里:T 先做成 0xFF, 每转一格就 set_0 + ror 消掉一个 1 —— 一串 1 的长度就是剩余圈数(每步 3 字符的移位寄存器 计数器,一圈正好数八格)。于是两个 cell 够用,而且比切片版短得多。

顺带纠正另一半:[ ... ] 的"跑了就必然消耗被测位"不是死路 —— 只要被测的是计数器, 不是数据。这条以前被写成"手写也做不到(2 cell)",错的。

原地取反仍然是最便宜的一个:%rep _CELL_SIZE { flb; ror },一个 cell、17 字符。

顺带纠正一个流传下来的说法:raw_add 不吃掉操作数。实测 5+3 → A=5 B=3 S=8, 255+255 → A=255 B=255 S=254 Co=1。asm/fibonacci.r8asm 里"每圈都要重新复印"的注释 是过度保守(它确实复印了,但不复印也对)。

这次差点被写进文档的错误诊断(别再犯)

有一轮里,raw_add / raw_and / copy / fibonacci 全被判定"运行时是坏的", 理由是 set_0 对多字节 cell 不收敛、纸带跑到步数上限。那是虚拟机写错了: 仓库里有三份解释器(tests/synth_test.cc、src/derive.cc、tests/tape_run.cc) 把 biz/rnz 实现成了"整格是否为零"(Brainfuck 直觉),于是每个字节级程序 都变成死循环。改回 & 1 之后全部通过。

为什么之前没被发现:位级程序在两种语义下行为完全一样(0/1 的最低位就是它自己), %synth 的表、asm/test.r8asm、full_add 全都不受影响;只有字节级驱动能区分。 所以以后凡是"字节级看起来跑不动",第一个怀疑对象是虚拟机,不是库。

验证方法:拿 ROT-8-viz/build/rot8_test.exe 跑同一条纸带对答案。 tests/tape_run.cc 现在是正确语义(& 1),可以直接对。

另一位一 cell 的实现在这里被删过一次(别再加回来)

"每个 bit 一个 cell、用 clb_bit_add_nc 串成 8 位加法器"这条路能跑通(32 cell, 1308 字符,65536 组合全对),但它是上面那个错误诊断的产物:既然一个 cell 能放一个字节、 位读得出来,就没必要为每个 bit 花一个 cell。R8Forge 之前也删过一次同样的东西 (交接文档原话:"8 位加法 25 个 cell,没有实用价值")。 要拼字节级运算就用 raw_* / clb_*_nc / clb_*_ip。

%synth 相关

  • 语法:params N + mode tape|layers + metric chars|flat|blocks + layout ...(可选)
    • 目标表 stat ... 或 map ...。stat 的项数必须是 2^params(3 参数要 8 项)。 参数是输入位 %1..%K、输出位、剩余草稿位(草稿位必须结束为 0,语义见 compress_stat_space)。
  • metric flat:不计 .tp 行走代价 → 结果与 cell 布局无关、缓存可跨调用点复用。 metric chars 才是按实际布局最优。库里的块统一用 flat。
  • 缓存:.r8forge_cache/(已入库,克隆下来直接命中)。键 = 模型版本 + params + mode + metric + 解析后的整张目标表(+ layout,仅 chars)。改指令模型时要 bump kModelVersion(src/synth.cc)。
  • 缓存代价参考:bit_raw_add 的 flat 搜索 990,636,137 状态 / 680 秒 / ~22 GB 内存。 层数上限现在是 8(原来是 5,5 会把一些可行的表误判成不可能)。

已经验证可行的东西

东西 结论
库里的 7 个位运算块(and/or/xor/inc/add) 合成版比手写短:asm/test.r8asm 1714 → 1666 字符
clb_bit_add_nc(4 cell 忽略进位切片) flat 代价 27,完整全加器切片是 38;8/8 组合正确
clb_bit_inc_nc(3 cell 自增切片) 表 0 4 4 2 0 4 4 2(3 参数)缓存里就有,4 blocks;纸带 54 字符,4/4 组合正确
clb_add_nc(4 cell 字节加法) 688 字符,65536 组合全对;比 6 cell 的 raw_add 少 2 个 cell、短 959 字符
clb_inc_nc(3 cell 字节自增/加 0-1) 430 字符,256 组合全对;比 5 cell 的 raw_inc 少 2 个 cell
clb_neg_nc(3 cell 取负/取反) 448 / 447 字符,各 256 组合全对(Ci=1 取负、Ci=0 反码)
clb_sub_nc(4 cell 减法) 707 字符,65536 组合全对;进位输出顺带是无符号比较(A >= B)
clb_not_ip(1 cell 原地取反) 17 字符,256 组合全对;比走切片那条路快 26 倍
clb_inc_ip(2 cell 原地自增) 74 字符,256 组合全对;切片版 clb_inc_nc 是 430
clb_neg_ip(2 cell 原地取负) 90 字符,256 组合全对;切片版 clb_neg_nc 是 448
bit_raw_add(6 cell 全加器切片) 保留 A、B;字节级 raw_add 1647 字符,65536 组合全对
raw_and / raw_or / raw_xor / raw_inc 639 / 575 / 463 / 1214 字符,各 65536(inc 512)全对
asm/fibonacci.r8asm 8761 字符,跑出 10 项斐波那契,和注释一致

已经确认走不通的(别重试)

  • 3 个 cell 做加法切片:层数上限 5 和 8 都报 no program up to N layers (3 cell 的自增/取负切片是有解的,两个操作数塞不进 3 个 cell)。
  • 原地写回的 %synth 表:A←~A^Ci、A←A^Ci、A←A^B^Ci、A←A^~B^Ci 四个表全部报 no program up to 8 layers。原因是一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"。但手写可以:换成"清连续 1 + 计数器旋转"的算法,2 cell 就够 (clb_inc_ip 74 字符、clb_neg_ip 90 字符,见「原地」)。别把这条读成"手写也不行"。
  • 让切片自己在输入上取反(表 S=~A^Ci、进位 ~A&Ci,3 参数):no program up to 8 layers。 模型只会"牺牲一个 cell → 条件翻转别的 cell",输入为 0 时整块被跳过、S 只能保持 0, 表达不出"无条件翻转"。取反只能放在切片外面(一条 flb)。
  • 4 cell 的加法切片要做到"保留 A、B":表改成保留 A、B 后报 no program up to 8 layers。 想拿回操作数只能用 6 cell 的 bit_raw_add。 但这不等于"轮转需要保留操作数" —— 这句以前写错过。轮转只是 "读走最低位 → 丢掉 → ror",吃掉操作数完全没问题:clb_add_nc(4 cell)就是这么跑的, 65536 组合全过。
  • 字节级(2^16 项真值表)交给 %synth:搜索空间不可行。

命名与注释格式(照 SPEC.md,别自己发明)

R8ASM 的语言规格不在这个仓库里:

  • SPEC.md:C:\Users\peng0\git\r8asm_rev-fork\SPEC.md(r8asm_rev 里那份一模一样)。 语言、内建指令、运算符优先级、作用域、标准宏前缀都在里面。%synth 不在里面 —— 那是 R8Forge 自己的扩展,只有本仓库的 README 有文档。
  • ROT-8 指令集规格:C:\Users\peng0\git\ROT-8-viz\README.md("1-Bit Brainfuck 变体", 指令表里写明 BIZ/RNZ 判 LSB)。

SPEC 第 136-150 行的标准宏前缀:

前缀 全称 含义
clb clobber 破坏性宏,会破坏原始输入(多数情况是清零)
bit bit 对 cell 的 LSB 操作的宏
raw raw 未经封装的宏,通常要手动传入 tmp cell 作为实参

raw 不是"暴露 cell 作为参数"(这条以前写错过):raw_add 之所以叫 raw, 是因为它要你自己给 Co 和 tmp 那两个草稿 cell。bit 则说明所有 CellBit 形参 指的都是最低位 —— 这跟 biz/rnz 判 & 1 是同一件事:整套语言是围绕"1 位"设计的。

既有宏对号入座:

宏 为什么这么叫
raw_add / raw_and / raw_or / raw_xor / raw_inc 字节级,且草稿 cell 由调用者传
bit_raw_add(6 cell) 位级,且 %6: buf 是真正的草稿:内容无关,结束是垃圾
clb_bit_add_nc(4 cell) 四个 cell 都有意义,没有草稿 cell(所以没 raw),而 A、B 被吃掉(所以有 clb):第 3 个是"进→出"的进位,A=0 B=0 进位入=1 时 S=1
clb_bit_inc_nc(3 cell) 同样:A 被吃掉,进位进→出,没有草稿 cell
clb_add_nc(4 cell)/ clb_inc_nc(3 cell) 字节级版本,同样吃 A、B
clb_neg_nc(3 cell)/ clb_sub_nc(4 cell) 补码取负/减法,同样吃 A(和 B)
clb_not_ip / clb_inc_ip / clb_neg_ip 同上再加 _ip(in place):结果回到原来的 cell,只借一个草稿 cell
clb_bit_mov 位级搬运,并且把源吃掉
bit_copy / copy 位级/字节级拷贝,缓冲由调用者传(历史命名,少了 raw)
set_0 / set_1 / erase / rol / step / back / output 基础操作,不带前缀

%synth 块名 = <宏名>_synth,包装的 %macro 用不带 _synth 的名字。

后缀不是前缀:_nc 是手写库留下的历史命名,_ip 是本仓库加的(in place,结果写回原来的 cell)。选名字时先按 SPEC 的三个前缀定位,再挑后缀。

宏里的注释:

;   Macro clb_bit_add_nc
;   %1: CellBit A
;   %2: CellBit B
  • %this 表示"dp 当前所指的 cell"(set_0、clb_bit_mov 都这么写)。
  • 新宏先按上表选前缀。套不上的(块级、自己管草稿 cell 的)就在注释里写清吃什么、留下什么。
  • 参数类型只用这五个:Cell、CellBit、Unit、UnitBit、Count(纯数字,比如 step 的重复次数)。注释块贴在 %macro 上方,或者贴在生成它的 %synth 块上方,都行。
  • r8forge_macro_docs_test 会检查 asm/ 里每个 %macro:有没有注释块、 ; Macro <名字> 和实际宏名是否一致、参数条数是否等于 argc、类型是否在上面这五个里。 加完新宏跑一下,别让它的输出从全绿变红。