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

42 KiB
Raw Blame History

给接手的 agent 的话

下一轮从这里开始(2026-11-07 交接:移位-恢复除法已落地)

上一轮的任务做完了:clb_divmod 已经是二进制长除法(asm/divmod.r8asm)。 契约看 SPEC.md §7.6,设计推理、踩过的坑和实测数据看 §14。摘要:

  • 签名变成 clb_divmod N D Q R S:Q = 商、R = 余数,N 和 D 都保持原样, S 起 7 个连续草稿格。11 个 cell,最小驱动纸带 4499(旧 4189)。
  • 固定 11 轮(位宽),2047/1 不再 HANG。步数(drv/divmod.r8asm): 2047/10 49.6 万 → 2.86 万、2047/2 246 万 → 3.2 万、999/7 34 万 → 2.87 万、2047/1 HANG → 3.24 万;16384 组里最坏 32,383 步。 小 N/D 反而慢(旧版 N/D 轮就结束)——和 clb_mul 一样的取舍。
  • clb_digits 跟着换了布局(S 起 13 格,divmod 的草稿块从 S+3 开始): 0=2047 从 74 万降到 14.5 万步(最坏 164,867),test_digits 现在穷举 全部 2048 个值。纸带 10829 → 13717。
  • 单点验证驱动:drv/div_shift.r8asm(跨格左移 + 注入那一步,SPEC §14.4 第 1 条)。
  • 顺带修了两处会骗人的东西:r8forge_derive 以前不看汇编器的 error 位,漏 %include(unknown macro)时会拿截断的纸带跑出一个看起来正常的错答案 (这轮踩过一次,四个数字全变成 '0');raw_sub 注释里把 Bo 的语义写反了 (Bo = 1 是"没借位"= A >= B,实测 15-10 → 1、10-15 → 0)。

下一步可以做的(这轮没做):

  • 想再快一档:SPEC §14.6 那条"开循环前预计算 ~D、每轮走 raw_add",按单轮实测 差值估计 clb_divmod 28.6k → 约 17.6k 步,纸带基本不变;没换是因为 §14.3 指名 用 raw_sub,而它是上一轮专门为长除法加的。
  • 纸带还能短:clb_digits 的布局没优化过(13 格草稿跨得很开,.tp 行走占了纸带的 七成);clb_divmod 里提交时那个 495 字符的 copy 也还是全展开的。
  • 小 N/D 的慢是"固定 W 轮"的必然代价。真要治,得加"跳过前导 0 轮"(R == 0 的轮 只剩 Q 的旋转),但那会给每一轮加一次 clb_nonzero(约 300 步),大数反而更慢 —— 这轮权衡过,没做。

别动:asm/ 里其它宏;%synth 的指令模型(改了就 bump kModelVersion); geometry.hh 的位宽(真要改照 SPEC §13 的清单,四份虚拟机一起)。

当前基线(都通过,别弄坏):

r8forge asm/test.r8asm                         # 58722 字符(调用每个标准宏 + 每个语言特性)
r8forge_byte_op_test                           # 20 项(clb_divmod 16384 组、clb_digits 2048 个值)
r8forge_examples_test                          # 13 个 example + asm/test.r8asm,头部 `;   out` 逐个核对
r8forge_macro_docs_test                        # 47 macros in 21 files
r8forge_synth_test examples/full_add.r8asm     # all eight combinations ok
r8forge_derive verify_loop.r8asm -1 0=5        # out 5 0

另一个仓库:../ROT-8-viz(fork dsh/ROT-8-viz,main = 6e51df5)有串行 7E1 (-s / --parity / --stop / --7e1),clb_digits 产出的 ASCII 正好能直接喂它的 OUT。那边的工作树也是干净的。

动手之前,先把这份文件从头读完,再看 SPEC.md(本仓库自己的:%synth 指令 + asm/ 里每个宏的契约、纸带长度、验证口径)、上游语言规格 (C:\Users\peng0\git\r8asm_rev-fork\SPEC.md)和 asm/lib.r8asm 里的宏注释。 这条不是客套:上一轮我没先读,把「位移-加法乘法器比重复加法快」当成新发现又推了一遍。 那次它被否掉了(当时只认纸带长度),后来乘数一大就撞 500 万步上限,真的换成了移位-加法 —— 而且它比重复加法还短(5007 → 3977 字符),见「乘法器」。 下面「乘法器」「指令集语义」两节把要命的地方都写了 —— dp 净位移、flb 吃条件、rol = 10 次 ror、 位串行要的跨格移位该怎么拼。尤其把「已经确认走不通的」那节看完, 别把别人踩过的坑再踩一遍;想推翻某条结论,先照它写的验证方法实测一遍再改文字。

这个文件是给下一个会话(或者下一个 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/ 里那些带中文注释的 .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,权威实现)复现。

  • 提交身份:这个 repo 和 C:\Users\peng0\git\ROT-8-viz 的 local config 都是 user.name = dsh、user.email = dsh@gitea.local(凭证里那条 git:https://gitea.starcells.ltd 就是 dsh@gitea.local)。agent 的提交用 dsh,不要用 StarCells <peng080306@foxmail.com> —— 那是仓库主人的身份。这条踩过:ROT-8-viz 一开始没配 user.name,我照抄了历史作者, 结果两个 repo 的提交都挂在了主人名下,后来用 rebase --reset-author / filter-branch 改回 dsh 并 force-push 才修好。git commit 报 Author identity unknown 就是这条配置又没了, 补 git config user.name dsh + git config user.email dsh@gitea.local 就行。 ROT-8-viz 上这个 local config 被清掉过两次(原因没查清),所以那边提交时更稳的写法是 直接带上:git -c user.name=dsh -c user.email=dsh@gitea.local commit ...。

  • 推代码: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,58722 字符(全家桶:每个宏至少一次)
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_derive verify_loop.r8asm -1 0=5           # 动态循环:跑 5 次,out 应该是 5 0
r8forge_byte_op_test                              # 字节级库:20 个操作穷举/抽样,这台机器约 10 秒
r8forge_macro_docs_test                           # asm/ 里每个宏的注释格式

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

r8forge_derive 会检查汇编错误(2026-11 修的):import_file 只表示"文件打开了", 漏一条 %include 时汇编器会报 unknown macro '...' 并把 error 位置上、纸带是截断的。 以前 derive 不看这个标志,于是拿半截纸带跑出一个看起来正常的错答案(这轮实测踩到: clb_digits 少了 add_ip 的 include,四个数字全变成 '0')。现在它会打印 could not assemble 并返回 1 —— 看到 out 结果"太整齐"就先看 stderr。

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_size 与纸带长度是怎么用的

位宽叫 cell_size(一个 cell 多少 bit),纸带长度叫 kDefaultMemoryCells; 搜索器里"有多少个 CellBit 形参"叫 cell_argc(r8veritas<cell_argc>)。这三个名字 在两边的仓库里是统一的:C/C++ 侧 cell_size、搜索器侧 cell_argc、.r8asm 程序里看到的 常量仍是 _CELL_SIZE(那是源语言的常量,属于宏库的公开词汇,不要跟着改)。

两个默认值集中在 include/r8forge/geometry.hh,现在是 11 位 / 259 格:

inline constexpr size_t kDefaultCellSize = 11;
inline constexpr size_t kDefaultMemoryCells = 259;
inline constexpr uint32_t kDefaultCellMask = (1u << kDefaultCellSize) - 1u;

位宽和长度都不在指令集里(ROR 只是在一个 cell 里转圈,纸带是环),所以它们只以 "参数 + 常量"的形式存在,落在三处。改位宽时照这个清单走:

  1. 汇编器:import_file(path, cell_size) 的第二个参数就是位宽,6 个调用点都传 kDefaultCellSize。set_cell_size 顺手把三个名字注入程序作用域: _CELL_SIZE(位宽)、_CELL_MAX = (1 << 位宽) - 1、_ROL_STEP = 位宽 - 1。 宏里写 %rep _CELL_SIZE { … } 就自动跟着位宽走(erase、rol、所有字节级驱动都这么写), 所以位级宏、%synth 切片、位运算天然与位宽无关 —— 实测 r8forge_synth_test 在 11 位下照样 8/8 全过。
  2. 四份虚拟机(tests/synth_test.cc、tests/byte_op_test.cc、src/derive.cc、 tests/tape_run.cc):cell 存 uint16_t、数组长 kDefaultMemoryCells、 旋转必须是 (v >> 1) | ((v & 1) << (kDefaultCellSize - 1))、输入输出掩码用 kDefaultCellMask。四份要一起改,少改一份就会出现"两个实现不一致"的假象。
  3. 测试期望:一律用 kCellMask / kCellSize 写,不要出现 0xff、>> 8、256 - a。 注意 2048 % 256 == 0,所以不少 8 位期望在 11 位下碰巧还成立(and/or/xor/not/dec/sub 就是),别把"没报错"当成"不用改" —— neg、add、inc、mul 一改位宽当场就错。

踩过的坑:

  • .xor 的常数按当前位宽解释。asm/test.r8asm 原来写 .xor (~126)+1 想置 130, 11 位下变成 2048-126 = 1922;改成直接写 .xor 130。
  • 纸带会变长:%rep _CELL_SIZE 从 8 轮变 11 轮,raw_add 1647 → 2199 字符, fibonacci 8761 → 11959。写死的长度断言要跟着改。
  • output 打印整个 cell 的值,不再是一个字节;out 里出现 257、1088 这种数是对的 (127+130 = 257、200*200 = 19*2048 + 1088)。
  • 交叉验证要先对齐几何:几何一致时同一条纸带输出完全相同(asm/test.r8asm 的最后 6 个值 1322 5 82 0 1786 94,三份实现逐位一致);不一致时不是谁错了,是两台不同的机器。workspace 里的 ROT-8-viz/ 是 upstream starcells/ROT-8 的 fork(origin = dsh/ROT-8-viz,main), 默认 11 位 x 259 格,几何还能运行期改(--cell / --mem;默认值与字段在 include/rot8/rot8.h,名字就是 cell_size / mem_size)。对答案的办法: ROT-8-viz/build/Release/rot8_test.exe <tape.rot8> 把每个 OUT 按行打出来, 和 r8forge_derive <src.r8asm> -1 的 out 逐位比即可。
  • 位宽变大还有个正面效果:fibonacci 不再在 256 处回绕,现在跑出 13 项(到 233)。
  • 旧 tape 换到新位宽上不只是算错,还可能永远跑不完:按 8 位写死的程序里 %rep 8 只转了 8 圈,在 11 位下 cell 没转回原位,"循环到某位清零"的条件于是永远不成立。 实测把改默认值之前的 test.r8asm 纸带喂给 11 位的 rot8_test --dump,它会一直跑 (ROT-8-viz 的普通/--dump 模式没有步数上限)。换位宽就重新汇编,别复用旧纸带。

字节级运算(一个 cell 一个机器字,默认 11 位)

结论:库里的字节级宏是对的,穷举全过。r8forge_byte_op_test 实测(这台机器约 10 秒; 2026-11 把 clb_divmod 扩到 16384 组、clb_digits 扩到全部 2048 个值之后)。 下面的纸带长度都是 11 位 cell 下的值(8 位时代的数字见 git 历史):

宏 驱动 纸带 结果
raw_add(a+b,含进位) drv/raw_add_byte.r8asm 2199 字符 65536/65536
raw_and drv/raw_and_byte.r8asm 870 字符 65536/65536
raw_or drv/raw_or_byte.r8asm 782 字符 65536/65536
raw_xor drv/raw_xor_byte.r8asm 628 字符 65536/65536
raw_inc(a+进位) drv/raw_inc_byte.r8asm 1619 字符 512/512
clb_add_nc(a+b+进位,4 cell) drv/raw_add_nc_byte.r8asm 937 字符 65536/65536
clb_inc_nc(a+进位,3 cell) drv/raw_inc_nc_byte.r8asm 586 字符 256/256
clb_neg_nc(~a+进位,3 cell) drv/raw_neg_nc_byte.r8asm 610 字符 256/256(取负)
同上,进位 0 drv/raw_not_nc_byte.r8asm 609 字符 256/256(反码 ~a)
clb_sub_nc(a-b,4 cell) drv/raw_sub_nc_byte.r8asm 962 字符 65536/65536
clb_not_ip(~a,原地,1 cell) drv/not_ip_byte.r8asm 23 字符 256/256
clb_inc_ip(a+1,原地,2 cell) drv/inc_ip_byte.r8asm 89 字符 256/256
clb_neg_ip(-a,原地,2 cell) drv/neg_ip_byte.r8asm 111 字符 256/256
clb_dec_ip(a-1,原地,2 cell) drv/dec_ip_byte.r8asm 133 字符 256/256
clb_nonzero(a!=0 的标志,原地) drv/nonzero_byte.r8asm 284 字符 256/256
clb_add_ip(a+=b,原地,4 cell) drv/add_ip_byte.r8asm 726 字符 2048 抽样全过(O(b) 运行)
clb_mul(mc×mul → 两 cell 积,10 cell) drv/mul_byte.r8asm 3977 字符 65536/65536(O(位宽) 运行)
clb_ones(数量 → 从末位起 N 个 1,4 cell) drv/ones.r8asm 742 字符(带 output)/ 828(最小驱动) 12 个计数全对(N=0..11)
clb_divmod(N div D / N mod D,11 cell) drv/divmod.r8asm 4499 字符(最小驱动)/ 4511(带 output) 16384 组全对(8 个除数 × 全部 2048 个被除数;固定 11 轮,最坏 32,383 步,2047/1 不再挂)
clb_digits(整数 → 4 位 ASCII 十进制,18 cell) drv/digits.r8asm 13717 字符(最小驱动)/ 13741(带 output) 全部 2048 个值全对(最坏 164,867 步;2047 是 14.5 万步)
raw_sub(A-B,保留 A、B,Bo = 没借位,7 cell) drv/raw_sub.r8asm ≈2900 字符 9 组抽样全对;长除法要用它(clb_sub_nc 会把操作数吃掉)
asm/fibonacci.r8asm — 11959 字符 跑出 13 项 1 1 2 3 5 8 13 21 34 55 89 144 233

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 包装): 8 位时代是 468 → 448、467 → 447、725 → 707;11 位下的实测值见上表(610 / 609 / 962)。 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 纸带(11 位) 穷举
clb_not_ip A A = ~A(反码) 1 23 256/256
clb_inc_ip A T A = A + 1 2 89 256/256
clb_neg_ip A T A = -A(补码取负) 2 111 256/256
clb_dec_ip A T A = A - 1 2 133 256/256
clb_nonzero B F T F = (B != 0),B 不动 3 284 256/256
clb_add_ip A B T F A += B,B 被吃掉 4 726 2048 抽样

对比写回 S 的切片版:clb_inc_nc 586(3 cell)、clb_neg_nc 610(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、23 字符。 自减用补码恒等式拼出来,不用新算法:B - 1 = ~(-B),所以 clb_dec_ip = clb_neg_ip + clb_not_ip(133 字符)。

原地加法,以及"只有纸带长度是目标"这条

clb_add_ip A B T F:A += B,原地,4 个 cell(A、B、T、F),726 字符, B 被吃干净。对比:raw_add 2199(6 cell,保留操作数)、clb_add_nc 937 + 每轮一次 copy。

没有去写逐位的进位链加法:全加器的进位是 maj(a,b,c),也就是两两的合取,而每个条件测试 都会吃掉被测的那一位,所以要么先拷贝好几份位、要么嵌套测试 —— 又长又脆。

改成利用一件在本仓库里成立的事:只有纸带长度是目标,运行步数不是。

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

循环体在纸带里只出现一次,所以长度和 B 的大小无关;代价是运行 O(B)(B=255 时约 30 万步, r8forge 的上限是 500 万)。这个取舍在别处也能用 —— 凡是"长度优先"的地方都可以想 "能不能用循环把代码压掉"。

剩下的难点是"B != 0"怎么测(biz 只测最低位)。clb_nonzero B F T 的做法:每位先把它 搬进工作位 T(这一步清掉 B 的那一位),若 T 是 1 就把 F 置一并还原 B 的那一位, 转一格看下一位;八轮后 B 原样、F = (B != 0)。注意是 set_1 不是 flb —— 这里踩过: flb 是翻转,偶数个 1 位会把标志翻回 0(3、5、255 都测错过)。

乘法器(asm/mul.r8asm)

clb_mul MC MUL PL PH MCA S Ci T F NR:(PH:PL) = MC * MUL,10 个 cell,3977 字符, r8forge_byte_op_test 现在穷举 65536 组(0..255 × 0..255)全对,最坏运行 26123 步 (2047 * 2047,11 位下的整个域)。

用的是二进制移位-加法(竖式乘法),一位一位串:

A:PH = 0 ; C:F = 0 ; Q:PL = MUL
repeat _CELL_SIZE:
    if Q & 1:  (C:PH) += MC        ; 一次 W 位加法,进位出到 F
    (C:PH:PL) >>= 1                ; 跨格右移,最高位补 0,最低位(刚看的那位)丢掉

W 轮之后 (PH:PL) 就是积;PL(原来的 Q)被移空,所以 MUL 结束为 0,和原来的约定一样。

为什么换掉重复加法:重复加法的轮数 = MUL 的值,成本 ∝ MUL。MUL = 2047 时实测直接 HANG after 5000000 steps——也就是大乘数根本算不完。移位-加法的轮数 = 位宽,跟操作数的 值无关,11 位下封顶 26123 步:

算式 重复加法(旧) 移位-加法(现在)
82 * 141(MC=82, MUL=141) 358586 步 8374 步
82 * 141(MC=141, MUL=82) 214741 步 6974 步
255 * 255 733428 步 17785 步
100 * 403 1026648 步 10208 步
2047 * 2047 HANG(>500 万步) 26123 步
2047 * 0 270 步 1863 步

纸带同时短了:5007 → 3977 字符。代价只有一条:乘数是 0/1 这种小值时反而慢一点点 (旧版循环 0/1 次就完了,新版固定要转满 _CELL_SIZE 轮)——拿它换「乘数再大也不会挂」。 所以 asm/test.r8asm 现在把 141 放在乘数位只是沿用历史值,不再有"小操作数放 MUL" 这条规矩要守(hash 的两轮各乘一次 141,步数一共两万多)。

拼法上踩过两个坑:

  • 跨格移位:(C:PH:PL) >>= 1 得当成一个 2W+1 位的寄存器来移。做法是三格先各 ror 一格,把要注入的那一位搬到 bit0(rol 回来),用 clb_bit_mov 搬过去,再 ror 回去。 顺序必须是低位那对先搬(PH→PL 先做),否则 PH 的 bit0 已经被 F 覆盖了。
  • biz/rnz 是循环对,不是 if/else:条件块的身体必须把被测位吃掉(最后一条 flb), 否则 rnz 看到还是 1 就跳回去 —— 第一版就是这么写成死循环的(现象:out 一个都没有、 计数器停在 0x7ff 没动)。被测的正好是 PL 的最低位,而它本来就要被右移丢掉,吃掉它 不影响移位。set_0 / clb_bit_mov 身体里那个 flb 是同一个道理。

轮数用什么数:计数器 NR 先做成 _CELL_SIZE 个 1(%rep _CELL_SIZE { set_1; ror }), 每轮 set_0 + ror 吃掉一个 —— 和 clb_inc_ip 数圈数是同一个法子。一串 1 的长度就是 剩余轮数,所以"做几轮"不占纸带长度,只占运行时间。

设计上的教训(这一版):上一轮把"移位-加法"否掉了,理由是「只有纸带长度是目标」—— 可那只说明当时的取舍,而且结论其实反了:移位-加法不但更短(3977 < 5007), 步数还少一到两个数量级。真正的原因不是它更长,而是把"跨格移位 + 条件累加"想复杂了 —— rol/ror 加一条 clb_bit_mov 就能拼,三行的事。 先看目标函数再选算法这条本身没错,但目标函数里得把「500 万步上限」写进去: 长度优先的循环写法(clb_add_ip、旧的 clb_mul)在纸带上不吃亏,运行时间上会随值线性长大。

顺带纠正一个流传下来的说法: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 + layout ...(可选,只在 --synth-chars 下有用)
    • 目标表 stat ... 或 map ...。stat 的项数必须是 2^params(3 参数要 8 项)。 参数是输入位 %1..%K、输出位、剩余草稿位(草稿位必须结束为 0,语义见 compress_stat_space)。
  • 代价口径是隐式的(源码里没有 metric 行了,写了会报错):默认 flat —— 不计 .tp 行走、结果与 cell 布局无关、缓存可跨调用点复用;r8forge --synth-chars <file> 才对这次 汇编里的所有块按真实布局算(r8asm::set_synth_metric(0),CLI 在 tests/asm_test.cc)。 full_add 上两个口径分别是 95 / 90 字符。metric blocks 已删(块数不是纸带长度的好代理)。
  • 缓存:.r8forge_cache/(已入库,克隆下来直接命中)。键 = 模型版本 + params + mode + metric + 解析后的整张目标表(+ layout,仅 chars)。改指令模型时要 bump kModelVersion(src/synth.cc)。
  • 纸带搜索的线程数:-j N / --synth-threads N / --synth-threads=N(0 = 每个硬件 线程一个,是默认);C++ 侧是 r8asm::set_synth_threads(unsigned)。搜索按"第一个块"切 (r8veritas_phase.hh 的 search_tt),所以多 worker 安全;层数搜索是串行的。 搜完在 stderr 那行末尾会打 , N threads,可以直接确认参数生效(实测 -j 1 → 1、 -j 4 → 4、-j 0 → 32(本机硬件线程数))。
  • 缓存代价参考:bit_raw_add 的 flat 搜索 990,636,137 状态 / 680 秒 / ~22 GB 内存。 层数上限现在是 8(原来是 5,5 会把一些可行的表误判成不可能)。

已经验证可行的东西

东西 结论
库里的 7 个位运算块(and/or/xor/inc/add) 合成版比手写短(8 位时代 1714 → 1666;位宽改了以后位级块不受影响,长度变的是字节级那层)
asm/test.r8asm 全家桶测试 11 位下 58722 字符、215169 步、100 个 out。asm/ 里每个宏至少被调一次(含 bit_raw_*/clb_bit_*/raw_*/clb_*_nc/clb_*_ip/clb_nonzero/clb_ones/clb_mul/clb_divmod/clb_digits/copy/bit_copy/*_to_buffer/loop),语言特性也各走一遍(%macro/%rep/%for/%synth 的 map 和 stat/.var/.anchor/step/back)。头部 ; out ... 是期望值,r8forge_examples_test 逐项核对;derive、tape_run、ROT-8-viz 三份实现一致。必须留在 65536 条指令以下(ROT-8-viz 的 INS_SIZE),所以 hash 只留两轮(尾 6 个值 1322 5 82 0 1786 94)
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;4/4 组合正确(与位宽无关)
clb_add_nc(4 cell 加法) 11 位下 937 字符,65536 组合全对;比 6 cell 的 raw_add 少 2 个 cell
clb_inc_nc(3 cell 自增/加 0-1) 586 字符,256 组合全对;比 5 cell 的 raw_inc 少 2 个 cell
clb_neg_nc(3 cell 取负/取反) 610 / 609 字符,各 256 组合全对(Ci=1 取负、Ci=0 反码)
clb_sub_nc(4 cell 减法) 962 字符,65536 组合全对;进位输出顺带是无符号比较(A >= B)
clb_not_ip(1 cell 原地取反) 23 字符,256 组合全对
clb_inc_ip(2 cell 原地自增) 89 字符,256 组合全对;切片版 clb_inc_nc 是 586
clb_neg_ip(2 cell 原地取负) 111 字符,256 组合全对;切片版 clb_neg_nc 是 610
clb_dec_ip(2 cell 原地自减) 133 字符 = neg + not(B-1 = ~(-B)),256 全对
clb_nonzero(非零标志) 284 字符,256 全对,B 保持原样
clb_add_ip(4 cell 原地加) 726 字符,2048 抽样全对;raw_add 2199
clb_mul(10 cell 乘法,积占两个 cell) 3977 字符,65536 组穷举全对;轮数只跟位宽有关(最坏 26123 步),跟 MUL 的值无关
clb_ones(4 cell,数量 → 从末位起 N 个 1) 828 字符(最小驱动),N=0..11 全对;rol + set_1 就是 B = 2B + 1,A 当计数器吃干净
clb_ones + loop/endloop 动态循环:次数由运行期数据决定。verify_loop.r8asm 939 字符,N=0..11 正好跑 N 次(A=N、C=0,N=0 一圈不跑);嵌套也对(NO×MI,11×11=121)。见 SPEC §5.1
bit_raw_add(6 cell 全加器切片) 保留 A、B;字节级 raw_add 2199 字符,65536 组合全对
raw_and / raw_or / raw_xor / raw_inc 870 / 782 / 628 / 1619 字符,各 65536(inc 512)全对
asm/fibonacci.r8asm 11959 字符,跑出 13 项(… 89 144 233),比 8 位时代多 3 项
examples/ 里的例程 每组宏一份,9 个程序(§10.3 的表)+ 4 个 %synth 例子。每个都是能跑的程序,头部 ; out ... 是它打印什么;r8forge_examples_test 全部跑一遍逐项核对(缺那行也算失败),顺带打印纸带长度和步数 —— 它还会跑 asm/test.r8asm(全家桶)

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

  • 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 89 字符、clb_neg_ip 111 字符,见「原地」)。别把这条读成"手写也不行"。
  • 让切片自己在输入上取反(表 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:搜索空间不可行。
  • 删掉位级包装宏里的 set_0(想法是"%synth 的 stat 已经把初值算进去了, 输出位不用先清"):错的。stat 表对输出位的初值是周期的(旧实现先清再算), 而 compress_stat_space() 把"初值不影响终值"的位从搜索初态里清成 0 —— 搜出来的块 只保证初值为 0 的调用点。2026-11 实测删掉 9 处 set_0:raw_add/raw_and/ raw_or/raw_xor 照样全过(轮转驱动每轮把结果写在 bit0 上就转走,输出位的 LSB 一直是 0),但 clb_mul 62064/65536 错、clb_divmod 14742/16384 错、 clb_digits 2048/2048 错(其中一个 HANG)。见 SPEC §3.6。

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

规格分两份:

  • 本仓库的 SPEC.md:%synth 指令、机器几何、asm/ 里每个宏的契约 (签名 / 参数类型 / 吃什么留什么 / cell 数 / 纸带长度 / 由哪个测试验证)、 纸带长度的测量口径。加宏、改宏、写文档之前先看它。
  • 上游语言规格:C:\Users\peng0\git\r8asm_rev-fork\SPEC.md(r8asm_rev 里那份一模一样)。 语言、内建指令、运算符优先级、作用域、标准宏前缀都在里面。%synth 不在里面 —— 那是 R8Forge 自己的扩展,看本仓库的 SPEC.md。
  • 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 / clb_dec_ip / clb_add_ip 同上再加 _ip(in place):结果回到原来的 cell,草稿 cell 由调用者传
clb_nonzero 破坏性的纯计算(把 B 抄成"非零"标志),不带 _ip 后缀
clb_ones 破坏性的纯计算(把"数量"展开成从末位起的一串 1,输入被吃干净);结果写在另一个 cell 里,所以也不带 _ip
clb_divmod 破坏性的纯计算(除/取模,商 Q、余数 R 各落在自己的 cell 里,S 起 7 格草稿由调用者传);N、D 现在保留,clb 指的是 Q 和草稿块会被覆盖
clb_digits 破坏性的纯计算(整数 → 一串 ASCII 数字),输入被吃干净、结果写在连续区域里,所以不带 _ip
loop / endloop 结构性的宏对(开/收一个运行时循环),不带前缀;不开 anchor 所以能嵌套,收口后 dp 停在计数器上
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、类型是否在上面这五个里。 加完新宏跑一下,别让它的输出从全绿变红。