SPEC.md: the %synth grammar and every standard library macro's contract

R8Forge had no spec of its own: the language lives in r8asm_rev/SPEC.md, the assembler
and the search were documented in README.md, and the macro contracts were only in the
comments above each %macro.  This adds SPEC.md, pointed at the standard library:

  * what this spec covers and what stays upstream (so the two do not drift);
  * the five parameter types, the naming prefixes/suffixes, and the measurement
    convention for tape lengths (a minimal driver, contiguous cells, no output lines);
  * %synth: the full grammar, what map and stat mean, the three metrics, the cache key
    and kModelVersion rule, and the four limits (8 params, 8 layers, no byte level
    tables, no unconditional flip);
  * all 41 macros in asm/ in tables with signature, which cells they eat, cell count,
    tape length and implementation (hand written or %synth block + its stat table);
  * the warts: clb_and leaves B & ~A behind while clb_or/clb_xor are clean, layout being
    silently ignored when its length is not params, and set_0 clearing one bit only;
  * a verification matrix saying which test proves what, and the known dead ends.

Every number in the tables was measured for this commit with one uniform driver
(measure_macros.ps1 shape, deleted afterwards), e.g. clb_not_ip 22, clb_add_ip 722,
clb_mul 3964 minimal vs 3977 through drv/mul_byte.r8asm.  AGENTS.md and README.md now
point at SPEC.md instead of saying the %synth docs only live in the README.
This commit is contained in:
dsh committed 2026-11-07 12:44:47 +08:00
1 parent ac5810580d
commit 54ddf9b0e7
3 files changed
+454 -5

No files matched your search

+9 -5
View File
@@ -1,6 +1,7 @@
# 给接手的 agent 的话
> **动手之前,先把这份文件从头读完**,再看 `README.md`、`SPEC.md`
> **动手之前,先把这份文件从头读完**,再看 `SPEC.md`(本仓库自己的:`%synth` 指令 +
> `asm/` 里每个宏的契约、纸带长度、验证口径)、上游语言规格
> (`C:\Users\peng0\git\r8asm_rev-fork\SPEC.md`)和 `asm/lib.r8asm` 里的宏注释。
> 这条不是客套:上一轮我没先读,把「位移-加法乘法器比重复加法快」当成新发现又推了一遍。
> 那次它被否掉了(当时只认纸带长度),后来乘数一大就撞 500 万步上限,真的换成了移位-加法
@@ -437,11 +438,14 @@ W 轮之后 `(PH:PL)` 就是积;`PL`(原来的 Q)被移空,所以 **MUL
## 命名与注释格式(照 `SPEC.md`,别自己发明)
R8ASM 的语言规格不在这个仓库里:
规格分两份:
* **`SPEC.md`**:`C:\Users\peng0\git\r8asm_rev-fork\SPEC.md`(`r8asm_rev` 里那份一模一样)。
语言、内建指令、运算符优先级、作用域、标准宏前缀都在里面。**`%synth` 不在里面** ——
那是 R8Forge 自己的扩展,只有本仓库的 README 有文档。
* **本仓库的 `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**)。
+4
View File
@@ -466,6 +466,9 @@ cost(layer) = 2 # biz + rnz
以及一列**已经确认走不通**的方案(3 cell 加法切片、轮转配合成切片、字节级真值表交给搜索……)。
那些都是失败换来的结论,别重试。
要查"某个宏到底怎么调、吃什么、留什么、占几个 cell、纸带多长、谁验证的",看
[`SPEC.md`](SPEC.md):`%synth` 的完整语法 + `asm/` 里 41 个宏的契约表。
## 构建
```powershell
@@ -490,6 +493,7 @@ build\Release\r8forge_macro_docs_test.exe # 宏注释格式(asm/ 下每个 %macr
## 布局
```
SPEC.md 规格:%synth + asm/ 里每个宏的契约
include/r8forge/r8asm.hh 汇编器 + %synth 指令
include/r8forge/r8veritas.hh 搜索器
src/r8asm.cc 汇编器实现
+441
View File
@@ -0,0 +1,441 @@
# R8Forge SPEC
R8Forge = R8ASM 汇编器 + `%synth` 搜索器 + 标准库。这份文件规定 **R8Forge 自己这一层**
的契约,重点在 **`asm/` 里的每个标准库宏**:签名、参数类型、吃什么、留什么、占几个 cell、
纸带多长、由谁验证过。
不在这里的东西:
| 内容 | 在哪 |
|---|---|
| R8ASM 语言本体(词法、运算符优先级、`%macro`/`%rep`/`%include`、`.tp`/`.anchor`/`.var`/`.xor`/`.loop`、作用域、标准宏前缀) | `r8asm_rev/SPEC.md`(`C:\Users\peng0\git\r8asm_rev-fork\SPEC.md`,本仓库**不重复**) |
| ROT-8 指令集(8 条指令、LSB 语义) | `ROT-8-viz/README.md` |
| 踩过的坑、失败过的方案、交接话 | `AGENTS.md`、`README.md` |
本文的每个数字都是在 **11 位 cell / 259 格**、MSVC Release 构建上**实测**的;口径见 §1.3。
---
## 1. 术语与数字口径
### 1.1 参数类型(宏注释里只准用这五个)
| 类型 | 含义 |
|---|---|
| `Cell` | 一个 cell 地址,装整个机器字(默认 11 位) |
| `CellBit` | 一个 cell 地址,但只用它的 **LSB** 当一位用(`biz`/`rnz` 判的就是 `cell & 1`) |
| `Unit` | 一个 cell 地址,它的 **下一个 cell** 是它的辅助格(SPEC:地址 n+1 是 n 的 aux) |
| `UnitBit` | 同上,但按位用 |
| `Count` | 纯数字,不是 cell 地址(比如 `step` 的重复次数、`%rep` 的轮数) |
### 1.2 机器几何
```cpp
// include/r8forge/geometry.hh
inline constexpr size_t kDefaultCellSize = 11; // 一个 cell 多少 bit
inline constexpr size_t kDefaultMemoryCells = 259;
inline constexpr uint32_t kDefaultCellMask = (1u << kDefaultCellSize) - 1u;
```
汇编器把三个名字注入 `.r8asm` 程序的作用域,宏库靠它们与位宽解耦:
| 名字 | 值(11 位) | 用途 |
|---|---|---|
| `_CELL_SIZE` | 11 | `%rep _CELL_SIZE { … }` 跟着位宽走 |
| `_CELL_MAX` | 2047 | 全 1 的 cell |
| `_ROL_STEP` | 10 | `rol` 要转的步数(= 位宽 − 1) |
### 1.3 纸带长度的口径
本文 §5–§9 的"纸带"列一律是**最小驱动**的长度:只 `%include` 该宏所在的库文件,
把形参按顺序摆到地址 `0..N-1`,宏调用**一次**,**不带** `output`。
- `%this` 类宏(`set_0`、`rol`、`copy` …)的驱动先把 `.tp` 指向源 cell(地址 0),
所以**不含**"从别处走到操作数"的行走;宏内部自己的 `.tp` 都算在内。
- 换布局、加 `output`、多摆几个 cell 都会让长度变;`drv/*.r8asm` 里的驱动更长
(比如 `raw_add`:最小驱动 1522,`drv/raw_add_byte.r8asm` 2199)。
- 想复现:`r8forge <那个驱动>.r8asm | 数一下字符数`。
步数(运行代价)是另一回事,只有 §9 的乘法器给了上界,因为它是唯一有明确界的。
---
## 2. 机器(汇编器眼里的实现)
```
'-' flb cells[dp] ^= 1 '+' ror cells[dp] = ror(cells[dp], cell_size)
'[' biz if (cells[dp] & 1) == 0 -> 跳到匹配的 ']' 之后
']' rnz if (cells[dp] & 1) == 1 -> 跳回匹配的 '['
'.' out 输出整个 cell 的值 ',' inp 读入并只留低 cell_size 位
'>' stp dp++ '<' btp dp--
```
两条**必须记住**的约束(标准库全部遵守,写新宏也得遵守):
1. **`biz`/`rnz` 判的是最低位,不是"整格为零"。**
于是 `set_0` = `[-]` 只清 LSB:`255 → 254`、`128 → 128`、`5 → 4`。
要清整个 cell 得 `%rep _CELL_SIZE { set_0; ror }`,也就是 `erase`。
反过来,字节里的任意一位都能读:`ror` 若干次把目标位转到 LSB,再 `biz`。
2. **每个条件块的身体必须回到它自己的条件 cell(净位移 0)。**
`dp` 是**汇编期**常量,而 `[...]` 的 body 运行期可能被跳过;跳过的路径和进入的路径
必须在同一个 `dp` 上会合,否则之后所有 `.tp` 全部错位(症状:`dp` 跑到 1023 这种地方,
`r8forge_tape_run --trace` 能看见)。`set_0` 的身体不动、`clb_bit_mov` 的身体最后
`.tp before` 再 `flb`,都是为了这一条。
附带的自然后果:**`biz`/`rnz` 是一对循环**,不是 if/else —— body 必须把被测位吃掉
(最后那个 `flb`),否则 `rnz` 看到还是 1 就跳回去。
---
## 3. `%synth` 指令
R8Forge 唯一的语言扩展:在汇编期现场搜出一段最短的块序列,拼成一个普通宏。
### 3.1 语法
```asm
%synth <名字>
params <N> ; 1..8
mode tape|layers ; 默认 tape
metric chars|flat|blocks ; 默认 chars
layout <addr> ... ; 可选,按 %1..%N 顺序给 cell 地址
map <2^K 项> ; 或者 stat <2^params 项>
%endsynth
```
- `stat` = **整张状态表**:每项是该输入组合下所有参数的取值(按 `%1..%N` 的位拼成一个数)。
- `map` = 只写输出位:项数 `2^K`(必须是 2 的幂)就表示 `%1..%K` 是输入,值里 bit j 落到
`%(K+j+1)`,剩下的参数是**必须结束为 0 的草稿位**。
- `layout` 只影响 `metric chars`。**给错个数不会报错**:数量不等于 `params` 时静默退回
`0..N-1`(想按真实布局算就得数对,`metric flat` 下本来也无所谓布局)。
- 定义完就是一个普通宏:`<名字> a1 a2 ... aN`。
### 3.2 语义
- 目标是一张状态表:`2^N` 个输入组合,每个组合下 N 个 cell 的终值。
- **输入永远是排在最前面的参数**(`%1..%K`),搜索器拿真值表下标直接当输入值;
输入不在最前面就只能用 `stat`。
- 生成的块是 `sacrifice + mask` 模型:选中一个 cell(条件位),清掉它,然后按 mask
对其它 cell 做 `set_1`(OR)或 `flb`(XOR)。所以**合成的块只适用于"每格一位"的世界**,
高位不追踪。
- `mode layers`:只求层数最少(快)。`mode tape`:接着按纸带长度做精确 Dijkstra 搜索,
用层数解的代价做上界。
- `metric`:`chars`(默认,按 layout 算真实字符数)、`flat`(不计 `.tp` 行走,结果与布局
无关、缓存可跨调用点复用;**库里的块统一用 flat**)、`blocks`(只数块)。
- 生成的代码走正常宏展开:写成临时文件 `<名字>.synth.r8asm`(系统临时目录,写不进去就退到
当前目录并提示),再 `import_file`,然后删掉。因此生成物不依赖 `lib.r8asm`
(`set_1` 展开成 `biz/flb/rnz` + `flb`)。
### 3.3 缓存
- 目录 `.r8forge_cache/`,**已入库**(克隆下来直接命中,第一次构建不用等搜索)。
- 键 = 模型版本 + params + mode + metric + **解析后的整张目标表**(metric 是 chars 时再加
layout)。所以同一张表、任何写法、任何调用点,共用一份结果。
- 改指令模型必须 bump `kModelVersion`(`src/synth.cc`),否则旧结果会被当成最优。
- 代价参考:`bit_raw_add` 的 flat 搜索 990,636,137 状态 / 680 秒 / 峰值 ~22 GB。
### 3.4 限制
| 限制 | 原因 / 后果 |
|---|---|
| `params` 最大 8 | 状态是位平面塞进 64 位字 |
| 层数上限 8 | 5 会把一些可行表误判成不可能;再高搜索爆炸 |
| 字节级(`2^16` 项)真值表不可行 | 搜索空间 |
| 表达不出"无条件翻转" | 模型只会"牺牲一个 cell → 条件翻转别的 cell",输入为 0 时整块被跳过 |
| 原地写回的表(`A←~A^Ci` 等四个)无解 | 一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"(手写可以,见 §8) |
---
## 4. 标准库 `asm/` —— 总则
### 4.1 命名
| 前缀 | 全称 | 含义 |
|---|---|---|
| `clb` | clobber | 破坏性:会破坏原始输入(多数情况是清零) |
| `bit` | bit | 对 cell 的 **LSB** 操作的宏 |
| `raw` | raw | 未经封装:**草稿 cell 要调用者自己传** |
后缀(不是前缀):
| 后缀 | 含义 |
|---|---|
| `_nc` | 历史命名(no carry),实际含义是"把操作数吃干净"的切片版 |
| `_ip` | in place:结果写回原来的 cell |
| `_synth` | `%synth` 生成的块本身,不是给人调用的;包装它的 `%macro` 才用不带后缀的名字 |
例:`raw_add`(保留操作数、要你自己给 `Co`/`tmp`)、`clb_add_nc`(吃 A/B、4 cell)、
`clb_add_ip`(原地、B 被吃)、`bit_raw_add_synth`(合成的块)+ `bit_raw_add`(包装宏)。
### 4.2 注释契约(机器检查)
`asm/` 里每个 `%macro` 必须有注释块,`r8forge_macro_docs_test` 会逐条检查:
```asm
; Macro clb_bit_add_nc
; %1: CellBit A
; %2: CellBit B
```
- `; Macro <名字>` 必须和实际宏名一致;
- `%N: <类型> <名字>` 条数必须等于 argc,类型必须是 §1.1 的五种之一;
- `%this` 表示"dp 当前所指的 cell";
- 注释块贴在 `%macro` 上方或生成它的 `%synth` 块上方都行。
### 4.3 布局
标准库**不假设** cell 地址。所有地址都是形参,由调用者自己排;宏内部的 `.tp` 行走算在
这个宏的纸带长度里(所以同样的宏在不同布局下长度不同)。宏返回时 `dp` 回到调用点的 cell。
---
## 5. 基础宏(`asm/lib.r8asm`)
| 宏 | 签名 | 干什么 | cell | 纸带 |
|---|---|---|---|---|
| `step` | `step N` | `N` 次 `stp stp`(一个 Unit) | 0 | 2 |
| `back` | `back N` | `N` 次 `btp btp` | 0 | 2 |
| `set_0` | `set_0`(`%this`) | 清 `%this` 的 LSB(= `[-]`) | 1 | 3 |
| `set_1` | `set_1`(`%this`) | 置 `%this` 的 LSB(= `set_0` + `flb`) | 1 | 4 |
| `erase` | `erase c` | 清 `c` 的**整个** cell(`%rep _CELL_SIZE { set_0; ror }`) | 1 | 44 |
| `rol` | `rol`(`%this`) | 左旋一格 = `%rep _CELL_SIZE - 1 { ror }` | 1 | 10 |
| `clb_bit_mov` | `clb_bit_mov d`(`%this`) | 把 `%this` 的 LSB **搬**到 `d` 的 LSB,源被吃掉 | 2 | 11 |
| `bit_copy` | `bit_copy d b`(`%this`) | 位拷贝,`b` 是借来的缓冲,**源保留** | 3 | 38 |
| `copy` | `copy d b`(`%this`) | 整个 cell 拷贝(位拷贝转满 `_CELL_SIZE` 圈) | 3 | 495 |
| `bit_copy_to_buffer` | `bit_copy_to_buffer t`(`%this` 是 UnitBit) | 位拷到 Unit 的辅助格,`t` 是缓冲 | 3 | 40 |
| `copy_to_buffer` | `copy_to_buffer t`(`%this` 是 Unit) | 整 cell 拷到 Unit 的辅助格 | 3 | 497 |
| `output` | `output c` | `.tp` 到 `c` 再 `out`(输出整个 cell 的值) | 1 | 1 |
要点:
- **`set_0` 只清一位**,`erase` 才清整格;别把 `set_0` 当"清零 cell"用。
- `copy` 比 `bit_copy` 长十倍多,是因为它对每个 bit 调一次 `bit_copy` 并转圈
(`copy` 495 vs `bit_copy` 38)。只搬一位用 `clb_bit_mov`(11)。
- `clb_bit_mov` 会把源位清掉 —— 它顺手就"吃条件",这正是 `set_0`/`clb_bit_mov`
身体里那个 `flb` 的作用(见 §2 第 2 条)。
---
## 6. 位级宏(一个 cell 装一位)
### 6.1 总表
| 宏 | 签名 | 语义 | 吃什么 | cell | 纸带 | 实现 |
|---|---|---|---|---|---|---|
| `clb_bit_add_nc` | `A B Ci S` | `S = A^B^Ci`,进位进→出 | A、B | 4 | 66 | `%synth` |
| `clb_bit_inc_nc` | `A Ci S` | `S = A^Ci`,进位 = `A&Ci` | A | 3 | 50 | `%synth` |
| `clb_bit_and` | `a b ans` | `ans = a&b` | a;b 只在"两位都是 1"时清 | 3 | 25 | **手写** |
| `clb_bit_or` | `a b ans` | `ans = a\|b` | a、b | 3 | 25 | `%synth` |
| `clb_bit_xor` | `a b ans` | `ans = a^b` | a、b | 3 | 20 | `%synth` |
| `bit_raw_add` | `A B Ci S Co buf` | 完整全加器:`S=A^B^Ci`,`Co=maj(A,B,Ci)`;**A、B 保留**,`buf` 结束是垃圾 | 无(buf 草稿) | 6 | 106 | `%synth` |
| `bit_raw_and` | `arg1 arg2 ans tmp` | `ans = arg1&arg2`,两个操作数保留 | tmp | 4 | 57 | `%synth` |
| `bit_raw_or` | `arg1 arg2 ans tmp` | `ans = arg1\|arg2`,保留 | tmp | 4 | 59 | `%synth` |
| `bit_raw_xor` | `arg1 arg2 ans tmp` | `ans = arg1^arg2`,保留 | tmp | 4 | 49 | `%synth` |
| `bit_raw_inc` | `A Ci S Co tmp` | `S = A^Ci`,`Co = A&Ci`,A 保留 | tmp | 5 | 77 | `%synth` |
所有位级宏都**只碰低 1 位**,喂进来的输入必须是 0/1;`clb_bit_add_nc`/`clb_bit_inc_nc`
的进位 cell 是"进→出"的同一个 cell。
### 6.2 为什么 `clb_bit_and` 是手写的
三个参数、没有草稿位,而"与"需要**同时**保住两个输入,只能靠嵌套 `biz`(一层一个条件)。
搜索器在 3 个平面、9 层内穷尽无解 —— 这是模型的表达力边界,不是搜索没跑够。
`or`/`xor` 可以先清一个操作数,所以能合成(`0 4 4 4` / `0 4 4 0`)。
### 6.3 `%synth` 块与它们的表
| 块 | params | 表(`stat`) | 用它的宏 |
|---|---|---|---|
| `bit_raw_add_synth` | 6 | `0 9 10 19 12 21 22 31` ×8 | `bit_raw_add` |
| `bit_raw_and_synth` | 4 | `0 1 2 7` ×4 | `bit_raw_and` |
| `bit_raw_or_synth` | 4 | `0 5 6 7` ×4 | `bit_raw_or` |
| `bit_raw_xor_synth` | 4 | `0 5 6 3` ×4 | `bit_raw_xor` |
| `bit_raw_inc_synth` | 5 | `0 5 6 11` ×8 | `bit_raw_inc` |
| `clb_bit_add_nc_synth` | 4 | `0 8 8 4 8 4 4 12` ×2 | `clb_bit_add_nc` |
| `clb_bit_inc_nc_synth` | 3 | `0 4 4 2` ×2 | `clb_bit_inc_nc` |
| `clb_bit_or_synth` | 3 | `0 4 4 4` ×2 | `clb_bit_or` |
| `clb_bit_xor_synth` | 3 | `0 4 4 0` ×2 | `clb_bit_xor` |
这些表**不是手写的**,是 `r8forge_derive` 从旧的手写实现上穷举出来的
(例:`r8forge_derive drv/bit_raw_add.r8asm 6` → `stat 0 9 10 19 …`)。
所以合成结果与旧实现**逐位一致**,连"某个输入没被清掉"这类怪癖都保住了;要改语义就改表。
---
## 7. 字节级宏(一个 cell 一个机器字)
### 7.1 `raw_*` 家族:保留操作数
| 宏 | 签名 | 语义 | cell | 纸带 | 验证 |
|---|---|---|---|---|---|
| `raw_add` | `A B Ci S Co tmp` | `S = A+B+Ci`,`Co` 进位出 | 6 | 1522 | `drv/raw_add_byte.r8asm`,65536/65536 |
| `raw_and` | `arg1 arg2 ans tmp` | `ans = arg1 & arg2` | 4 | 697 | 65536/65536 |
| `raw_or` | `arg1 arg2 ans tmp` | `ans = arg1 \| arg2` | 4 | 719 | 65536/65536 |
| `raw_xor` | `arg1 arg2 ans tmp` | `ans = arg1 ^ arg2` | 4 | 609 | 65536/65536 |
| `raw_inc` | `A Ci S Co tmp` | `S = A + Ci`,`Co` 进位出 | 5 | 1179 | 512/512(A 与 Ci) |
`raw` 的含义是"草稿 cell 你自己传":`tmp` 结束是垃圾(`bit_raw_add` 的 `%6: buf` 同理)。
**`raw_add` 不吃操作数**:实测 `5+3 → A=5 B=3 S=8`,`255+255 → A=255 B=255 S=254 Co=1`。
(历史注释里"每圈都要重新复印"是过度保守 —— 复印了也没错,但没必要。)
### 7.2 `clb_*_nc` 家族:把操作数吃干净
| 宏 | 签名 | 语义 | 吃什么 | cell | 纸带 | 验证 |
|---|---|---|---|---|---|---|
| `clb_add_nc` | `A B S Ci` | `S = A+B+Ci` | A、B | 4 | 741 | 65536/65536(`drv/raw_add_nc_byte.r8asm`) |
| `clb_inc_nc` | `A S Ci` | `S = A+Ci` | A | 3 | 552 | 256/256 |
| `clb_neg_nc` | `A S Ci` | `S = ~A+Ci`(Ci=1 → `-A`) | A | 3 | 574 | 256/256(Ci=1 取负、Ci=0 反码) |
| `clb_sub_nc` | `A B S Ci` | `S = A+~B+Ci`(Ci=1 → `A-B`) | A、B | 4 | 765 | 65536/65536 |
**进位 cell 是真正的进位输入**:宏自己**不动**它的初值,只把它变成进位输出。
调用者给 0 就是普通运算,给 1 就是"自带 +1",也可以把上一字节的进位输出接过来串多字节。
(这条踩过:早先加法里 `set_0`、自增里 `set_1`,那就不是输入了,还把串接堵死。)
补码那两条的做法是**先原地取反、再走加法/自增**:`-A = ~A + 1`、`A - B = A + ~B + 1`,
那个 `+1` 由调用者的 Ci 给。取反整个字节一次(`clb_not_ip`)比"每 bit 取反一次"短二十来个
字符,而且 B 本来就会被加法吃掉,取反它没有代价。
进位输出的附带语义:`clb_sub_nc` 的进位是**没有借位**(`A >= B` 时为 1)——顺带就是
无符号比较;`clb_neg_nc` 的进位只在 `A` 原本是 0 时为 1(`-0 = 0`,但确实进了位)。
### 7.3 `clb_and` / `clb_or` / `clb_xor`:半破坏,读清楚再用
| 宏 | 签名 | `ans` | A 之后 | B 之后 | cell | 纸带 |
|---|---|---|---|---|---|---|
| `clb_and` | `arg1 arg2 ans` | `arg1 & arg2` | **0** | **`B & ~A`(有残留!)** | 3 | 352 |
| `clb_or` | `arg1 arg2 ans` | `arg1 \| arg2` | 0 | 0 | 3 | 323 |
| `clb_xor` | `arg1 arg2 ans` | `arg1 ^ arg2` | 0 | 0 | 3 | 268 |
`clb_and` 是这三个里唯一不清零 B 的:每位只有在"A、B 都是 1"时才清 B,
所以 B 结束在 `B & ~A`(实测 `240 & 204 → ans=192, A=0, B=12`)。
**别拿它当"两个操作数都能回收"的宏**;要干净的与运算,就用 `raw_and`(保留操作数)
或者自己再 `erase` 一次。`clb_or`/`clb_xor` 是干净的。
### 7.4 三个家族怎么选
| 需求 | 用 |
|---|---|
| 操作数要还回来 | `raw_*`(6/4 cell,多的那个是草稿) |
| 操作数可以扔,要省 cell | `clb_*_nc`(4/3 cell) |
| 结果要写回原 cell | `_ip` 家族(§8) |
**轮转驱动不吃亏**:`clb_*_nc` 和 `raw_*` 的区别只在"要不要还操作数",两者都是
"读走 LSB → 丢掉 → `ror`" 的轮转驱动,吃掉操作数完全没问题。
---
## 8. 原地 `_ip` 家族(结果回到原来的 cell)
| 宏 | 签名 | 语义 | cell | 纸带 | 验证 |
|---|---|---|---|---|---|
| `clb_not_ip` | `A` | `A = ~A`(反码) | 1 | 22 | 256/256 |
| `clb_inc_ip` | `A T` | `A = A + 1` | 2 | 88 | 256/256 |
| `clb_neg_ip` | `A T` | `A = -A`(补码取负) | 2 | 110 | 256/256 |
| `clb_dec_ip` | `A T` | `A = A - 1` | 2 | 132 | 256/256 |
| `clb_nonzero` | `B F T` | `F = (B != 0)`,**B 不动** | 3 | 280 | 256/256 |
| `clb_add_ip` | `A B T F` | `A += B`,**B 被吃** | 4 | 722 | 2048 抽样 |
对比写回 S 的切片版(`clb_inc_nc` 552 / `clb_neg_nc` 574,各 3 cell):
**原地版短 5 倍、少一个 cell**。
算法不是逐位测进位(那在两个 cell 里确实不行),而是:
1. 用 `[ ... ]` 的自然语义把**最低位连续的 1 清掉**(`flb` + `ror`),遇到第一个 0 退出;
2. 那个 0 翻成 1(输入全 1 时跳过,正好是回绕那一格);
3. 剩下的位置只旋转,转满 `_CELL_SIZE` 格。
"还要转几格"用 **T 的位**计数:T 先做成 `_CELL_MAX`,每转一格 `set_0` + `ror` 消掉一个 1,
一串 1 的长度就是剩余圈数。于是两个 cell 够用 —— 关键认识是**被测的是计数器,不是数据**,
所以"`[...]` 跑一次就吃掉被测位"不是障碍。
- `clb_neg_ip` = `clb_not_ip` + `clb_inc_ip`;
- `clb_dec_ip` = `clb_neg_ip` + `clb_not_ip`(恒等式 `B - 1 = ~(-B)`),不用新算法;
- `clb_nonzero` 每轮把 B 的一位**搬进** T(`clb_bit_mov` 顺手清掉 B 那一位),是 1 就把 F
**置一**(`set_1`,不是 `flb` —— 翻转会被偶数个 1 翻回 0)并把 B 那一位还原;
- `clb_add_ip` 不写逐位进位链,而是 **`while B != 0: A += 1; B -= 1`**:
循环体在纸带里只出现一次,长度与 B 无关,代价是运行 O(B)(B=255 时约 30 万步)。
---
## 9. 乘法器(`asm/mul.r8asm`)
`clb_mul MC MUL PL PH MCA S Ci T F NR`:`(PH:PL) = MC * MUL`,10 个 cell,最小驱动
**3964 字符**(`drv/mul_byte.r8asm` 3977)。MC 保持原样,**MUL 结束为 0**。
算法是**二进制移位-加法**(竖式乘法),一位一位串:
```
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,最低位(刚看的那位)丢掉
```
- 轮数 = 位宽,与两个操作数的**值**无关;11 位下最坏 **26123 步**(`2047*2047`)。
- 纸带长度与 MUL 无关(循环体只出现一次)。
- `MCA`/`S`/`Ci`/`T` 是草稿;`F` 是移位寄存器的最高位(进位),`NR` 是轮数计数器
(`%rep _CELL_SIZE { set_1; ror }` 做成全 1,每轮 `set_0` + `ror` 吃掉一个)。
- 跨格移位:三格先各 `ror`,把要注入的位搬到 bit0(`rol`),`clb_bit_mov` 搬过去,再
`ror` 回来;**低位那对先搬**(PH→PL 先做),否则 PH 的 bit0 已被 F 覆盖。
---
## 10. 拼起来是什么样
### 10.1 16 位加法:靠 `clb_add_nc` 的进位输出串
```
clb_add_nc PL B_lo T Ci ; 低字节相加,进位出到 Ci(A、B 被吃)
clb_add_ip PH Ci S F ; 把进位加进高字节(Ci 被吃)
```
### 10.2 `asm/test.r8asm`:一个滚动的 hash
`h = (h + c) * 141 mod 2048`,消息 `"R8F"`(82 56 70),只用 `clb_add_nc` + `clb_mul`:
先把消息字节加到 h 上,再乘 141,跑三轮。11 位下纸带 **28729 字符**,
`r8forge_derive` / `r8forge_tape_run` / ROT-8-viz 三份实现都给出
`1322 1786 1600 5 94 127`(前三 = 三轮的 h,后三 = 三轮的 PH,即 `(h+c)*141 >> 11`),
共 **57330 步**。
---
## 11. 验证矩阵
| 测试 | 覆盖 | 断言口径 |
|---|---|---|
| `r8forge_byte_op_test` | 17 个测试项 = 16 个宏(`clb_neg_nc` 的 Ci=1 / Ci=0 各算一项),见 §7.1、§7.2、§8、§9 | **按返回值**:穷举 0..255(`clb_add_ip` 2048 抽样、`clb_mul` 65536 全穷举),任一不符即退出码非 0 |
| `r8forge_synth_test examples/full_add.r8asm` | `%synth` 端到端:汇编 + 跑 8 种输入 | `all eight combinations ok` |
| `r8forge verify_clb_bit_add_nc.r8asm` | 4 cell 加法切片(进位进→出) | 单点:`0+0+Ci` |
| `r8forge verify_clb_bit_inc_nc.r8asm` | 3 cell 自增切片 | 单点 |
| `r8forge verify_set_0.r8asm` | `set_0` 只清 LSB | `-1 0=255 → 254`、`0=128 → 128` |
| `r8forge_macro_docs_test` | `asm/` 里 41 个宏的注释格式 | 全绿或报错行号 |
| `r8forge_tape_run <tape.rot8>` | 第二个解释器,直接跑纸带 | 与 `r8forge_derive` 对答案 |
| `r8forge_derive <src> -1/-2` | 拿汇编源码跑,打印 `out` / 非零 cell | 人工/脚本比对 |
只有 `r8forge_byte_op_test` 是**按返回值**判断字节级对错的;其它要么只证明"汇编得出来"、
"位级正确",要么是单点探针。改宏之后跑 §11 前四个(外加 docs test)。
---
## 12. 已知边界(别重试)
| 想做的 | 结论 |
|---|---|
| 3 个 cell 做加法切片 | 层数上限 5 和 8 都报 `no program up to N layers`(自增/取负 3 cell 有解,两个操作数塞不进 3 个 cell) |
| 用 `%synth` 写"原地"表(`A←~A^Ci` 等四个) | 全部无解(原因见 §3.4);**手写可以**(§8 的 `_ip` 家族) |
| 让切片自己在输入上取反 | 无解(表达不出"无条件翻转");取反放在切片外面(一条 `flb`) |
| 4 cell 加法切片要保留 A、B | 无解;要留操作数用 6 cell 的 `bit_raw_add` |
| 字节级(`2^16` 项)交给 `%synth` | 搜索空间不可行 |
| "每个 bit 一个 cell" 拼字节级运算 | 能跑通但没意义(一个 cell 已经能放一个字节、位也读得出来);这份实现**已删,别再加回来** |
---
## 13. 维护
- **改位宽/纸带长度**:`include/r8forge/geometry.hh` 两个常量 + 四份虚拟机
(`tests/synth_test.cc`、`tests/byte_op_test.cc`、`src/derive.cc`、`tests/tape_run.cc`)
一起改;`asm/` 里的宏靠 `_CELL_SIZE` 自动跟随,不用动。
- **加宏**:先按 §4.1 选前缀/后缀,再写 §4.2 的注释块,跑 `r8forge_macro_docs_test`;
能进 `byte_op_test` 就进(那才有按返回值的验证)。
- **改指令模型**(合成器的块集合、代价):必须 bump `kModelVersion`,否则
`.r8forge_cache/` 里的旧结果会被当成最优。
- **改本文的数字**:照 §1.3 的口径重新量,别把驱动长度和最小驱动长度混在一列。