# moonair spec —— 结构事实与契约版本:**v0.1**(2026-11-02 立卷,K0 骨架期) 定位:aria2 协议核 MoonBit 验证实现的**结构事实与契约**卷(世界卷 spec 卷型: 全局可信源)。勘证 / 路线 = `.mingspace/aria2_survey_ming.md` / `roadmap_review_ming.md`(本地卷);架构契约 = bitbang2 AGENTS「新项目架构契约」15 条律,本仓受约;分层体例承 moonswim。 ## 一、范围 ### 做 - **下载生命周期六态**(aria2 RPC 词表:Waiting / Active / Paused / Complete / Error / Removed);迁移表显式穷尽(§3.2),无静默默认臂。`[已落]` - **段账纯核**(SegmentMan 拆段 / 分配 / 回收 + 位图账本律,§3.6)。 `[已落]` - **协议文法**(Range / Content-Range / Content-Disposition + 控制文件 + session,§3.7)。`[已落]` - **sim 对打床**(四形假源 + 页/持久双层假存储 + kill -9 两点注入 + 段协议参照驱动,§3.8)。`[已落]` - **HTTP(S) 多连接分段 + 断点续传**(engine / io 缝 + StoragePort,§3.9)。 `[已落 K4]` - **JSON-RPC 控制面**(类型墙 + 安全三件)。`[已落 K5(§3.10 形)+ K6(§3.11 服务)]` - **Metalink v4(RFC 5854)**:下载描述格式解析(Milky2018/xml 拉取面)+ 多镜像调度(priority 排序 / 故障切换)+ 整文件与分片校验(§3.4)。 `[阶段 2.5 已落:M0(§3.12 XML port)/ M1(§3.13 抽取机)/ M2a–M2d (摘要 port / 多源调度 / 引擎真缝 / RPC addMetalink)]` - **BT 子集 / BT 扩展**。`[阶段 3 已落:K7(§3.14 bencode + 元信息)/ K8a(§3.15 线协议)/ K8b(§3.16 片管线与可外发律)/ K8c(§3.17 会话真缝)/ K9(§3.18 词面 + §3.19 真缝回环)/ M3(§3.20 词面 + §3.21 混合源真缝, 全讫)——aria2 双向对拍 oracle 台带绿(ORACLE-K9);阶段 4(BEP 9/10 扩展消息解码口等)候]` ### 暂不做 - 一比一复刻 aria2 CLI 选项全集;替代 aria2 生产使用。 - uTP(aria2 本无)。 - SFTP / 文件预分配(FFI 边界,候阶段 5)。 - FTP(路线卷裁决 6);Metalink 中的 ftp:// 镜像解析保留、调度跳过并记账。 - Metalink v3 旧格式;PGP 签名校验。 ## 二、形状锚 - **核心零依赖**:core import 面空;无 async、无传输、无存储。纯包全后端, 不钉 supported_targets;缝包(随役入)native+wasm 显式双钉(X 役 2026-11-05:async 在 wasm 走 moonrun 宿主实现,moonx 命令面同源;async 不支持 js / wasm-gc,留空则全后端 check 红),模块 `preferred_target = "native"`(接口件由真身后端生成,接口件零漂移经核)。命令面 = 薄模块 `thy1016/air`(bitbang2 独立仓;`air ` 下载 / `air --enable-rpc` aria2 兼容 JSON-RPC 服务;air spec 自持)。 - **时间注入**:`tick` 一律显式入参,核不藏钟——全决策可确定性回放。 - **错误面**:生命周期纯决策无错路(满表 + 无守卫 ⇒ `step` 恒 Ok);段账错误面 = `SegmentError`;协议面错误 = `RangeError` / `DispositionError` / `ControlFileError` / `SessionError` 四族(皆 raise 形——负例是闸门不是数据,K2 已落)。 - **gen 骨架**:`core/gen.mbt` 纯生成输出;用户填充住 `core/types.mbt`(印章桩面)与 `core/download_law.mbt`(律法动作)——两界物理分离,永不串联。 - **六边形**:外部能力(摘要 / XML 解析 / 落盘 / 传输)一律住 port(trait) 后——port 由消费它的纯包立(core 的 port 不带任何实现依赖,core import 面仍空),参考实现住 adapter 包,组合根一行装配;增强实现(如 OpenSSL 摘要)= 同 port 的第二 adapter,装配差异,禁 flag / 条件编译分叉;消费方只认 port 面,不穿透直摸实现词。 - **大 gen**:业务词表住 TOML 数据面、经 airgen 发射,生成物禁手编——生命周期六态(已落)、摘要算法名表、Metalink 抽取状态机、RPC 方法表(随役落);词汇改名 = 改表再生,零生成器改动。 ## 三、契约 ### 3.1 生命周期律(守恒罐逐条钉) 1. **终态吸收**:Complete / Error / Removed 对任何事件恒持——态不翻、tick 不刷、错误码不动。 2. **唯 Active 能完成 / 失败**:Waiting / Paused 收 Finish / Fail 一律吸收 (迟到信号不越权,再激活时重新判定)。 3. **恢复 = 重新排队**:Paused --Unpause--> Waiting,不直跳 Active。 4. **调度唯作用于 Waiting**:Paused 收 Dispatch 吸收(调度器不得启动暂停者)。 5. **移除可自任一非终态**:Waiting / Active / Paused --Remove--> Removed。 6. **失败记码,tick 随真迁移**:Active --Fail--> Error 记 `error_code`; `status_change_tick` 只在真迁移时刷,吸收行不动账。 ### 3.2 迁移表(显式穷尽) **表源 = `download_fsm.toml`(唯一事实源)**:本表是投影;迁移语义变动 = 改表 → `moon run skelgen/airgen/cmd`(主仓仓根)→ `moon fmt` → 黄金门对拍 (skelgen/airgen gate,regen + fmt ≡ core/gen.mbt 逐字节)。生成物禁手编。 | 状态 \ 事件 | Dispatch | Pause | Unpause | Remove | Finish | Fail | |---|---|---|---|---|---|---| | Waiting | → Active | → Paused | 恒持 | → Removed | 恒持 | 恒持 | | Active | 恒持 | → Paused | 恒持 | → Removed | → Complete | → Error(记码) | | Paused | 恒持 | 恒持 | → Waiting | → Removed | 恒持 | 恒持 | | Complete | 恒持 | 恒持 | 恒持 | 恒持 | 恒持 | 恒持 | | Error | 恒持 | 恒持 | 恒持 | 恒持 | 恒持 | 恒持 | | Removed | 恒持 | 恒持 | 恒持 | 恒持 | 恒持 | 恒持 | ### 3.3 状态字串状态名小写 = aria2 RPC `status` 字串——单一事实源在表,RPC 层不另立词表 (K5 落派生口)。 ### 3.4 Metalink 约束 `[定案 2026-11-02,M-1–M-6]` 1. **描述格式非传输**:Metalink(RFC 5854)解析产物 = 类型化下载描述(文件 / 镜像 / 哈希 / 分片),落 protocol(纯,全后端);引擎只收描述、不收 XML (类型墙)。 2. **解析器 = port**(M-1,定案随役落):XML 解析能力住 protocol 立的解析 port 后,`Milky2018/xml` 为首个 adapter;后备 `bitbang2/moonxml` 0.3.2 = 同 port 第二 adapter,组合根装配切换。libxml2 FFI 否决。解析安全 (XXE 引用即拒 / 实体展开有界)= 两枚负例夹具入金罐钉死(M-6),防依赖升级悄悄放宽。 3. **多源调度**:priority 升序(1 最高)+ 显式地点偏好;源失败只降级换源、不取消任务;已校验段不重下;不支持的镜像协议(ftp://)解析保留、调度跳过并记账(M-4),全部源不可用 → Fail(记专用错误码)。 **落码(M2b,`core/source_pool.mbt`)**`[M2b 已落]`:`SourcePool`——调度序构造期排定,键 = 地点档(偏好国家码在前,不分大小写)→ priority(缺省 999999)→ **文档序**(确定性兜底;aria2 同 priority 内洗牌,本仓取文档序以便复现——有意差异);scheme 过滤不分大小写,无 "://" 按不支持处置; 过滤后无源 = 构造期拒 `NoUsableSource`。租约制:`acquire` 取调度序首个「未出局且未满额」源(每源并发上限 max_per_source,缺省 1 = 满额顺延次优源,即段 → 源指派律);`succeed` 只释放额度;`fail` 释放 + 失败计数 (断流 / 取数失败 / 分片校验不符一律计入),累计达 max_failures(缺省 3) 出调度,**降级不回升**;全源出局 = `exhausted()`。错误码映射已随 M2c 落地(见律 4 末)。首个真消费者 = sim 多源对打(§3.8 第 6 条)。 **地点提升语义(M2d 实录对拍)**`[M2d 已落]`:aria2 1.36.0 `--metalink-location` = 偏好源 priority 加性提升 999999,结构上即**单档整体前置**——偏好列表序无关(实录 L4 "us,jp" 与 L4b "jp,us" 皆按 priority)、偏好源缺 priority 仍压非偏好 priority=1(L5)、选项值不分大小写(L2);本仓地点档二值即与之同构(core 罐逐案钉 L0–L6)。RPC 选项 `metalink-location` 逗号分隔(实录同效)。**有意差异**:aria2 文档侧 location 大小写敏感(文档 "JP" 永不匹配,L3),本仓两侧不分大小写 (ISO 3166-1 码大小写不具语义)。 4. **校验律**:哈希不符的片永不置位(同段账落盘时序);整文件终验不过 → Fail(记 error_code)。 **落码(M2c,引擎真缝)**`[M2c 已落]`:分片 = 边写边哈希(落盘的同一批字节逐窗喂 `PieceVerifier`,段满判片——相符才 sync / 置位;不符 = 源失败让位重下);整文件 = 收敛后经 `StoragePort::read_at` 读回全量逐块喂摘要流, 不符报 32,**控制文件留证**(终验先于销账)。**失败码 = aria2 语义**: aria2 1.36.0 本机实录——全镜像拒连 1 / 全镜像 404 3 / 206 区间错位 8 / 分片校验耗尽 1(Invalid checksum index=N)/ 整文件哈希不符 32;aria2 **无「全源不可用」专码**,全源出局报末次源失败的码——本仓同语义(「专用错误码」落实为「码随失败原因」,与 aria2 客户端码表兼容)。**混合失败补录**(K7 役):同质两例无从区分「末次 / 首次 / 多数」,补 aria2 实录两镜像一 404 一拒连——404 优先、拒连垫后报 1,对调报 3,并发与 `-s1` 两档同判,即**报最后一个失败源的码**;engine 混合失败罐两序钉之。码表 = 表源 `core/error_code_vocab.toml`(名 = aria2 src/error_code.h 原名,码 = 实录钉值;只收实录钉过且在用的码)。**25/26 补录(A 档,随行役;A 顺手役真源核定案)**:手册 EXIT STATUS 全表勘定补两枚 BT 面在用码——25 (bencode 解析败)/ 26(.torrent 损坏缺信息);**src/error_code.h 真源核定案(2026-11-05)**:原名 = `BENCODE_PARSE_ERROR` / `BITTORRENT_PARSE_ERROR`——手册文案 ≠ 源码枚举名,初版文案直译 (PARSE_ERROR / TORRENT_INVALID)被真源推翻(值域勘定律姊妹案), **消费面 B1 兑现(2026-11-06)**:addTorrent 判读路径双码在用—— bencode 词法碎 → 25(BencodeParseError 面)/ 结构不成 torrent 与 base64 载荷碎 → 26(BittorrentParseError 面);BT 会话败不冒用 25/26(code 1 + 会话收尾词), 词表 aria2_name 与变体名(`BencodeParseError` / `BittorrentParseError`)对位修正;消费面随 BT 接 RPC 码面役;词表再生产物 `error_code_vocab_gen.mbt` 同笔再生,黄金门 5/5(勘定案附:airgen 再生动全部四表,只 fmt 一张 = 另两张 fmt 差假红——再生后全表 fmt 再跑门)。 **择强律(M2d)**`[M2d 已落]`:file 级多 hash / 多 pieces 时各取「词表认得且摘要 adapter 能开」者中强度最高的一枚(`core.strongest_supported`; 强度 = 表源 `digest_vocab.toml` 的 strength 列,数据非代码)——aria2 1.36.0 实录相邻对逐对钉 md5 < sha-1 < sha-224 < sha-256 < sha-384 < sha-512,与文档序无关,pieces 同律;表外名丢弃(大写 `SHA-256` 两侧皆丢; 非 IANA 别名 `sha256` aria2 认、本仓严名丢——**有意差异**);择强无果 = 不校验该类。装配 = `engine.plan_metalink_file`(段长随所选 pieces 的 length)。 5. **范围**(M-5):只做 v4;v3 明确报版本不支持;PGP 签名暂不验证、元素保留并记账。 ### 3.5 摘要 port `[定案 2026-11-02,M-3:选 A + 预留 trait;M2a 已落]` - **能力 = port,实现 = adapter**:core 立摘要 port(trait),mooncry 为主 adapter;将来 OpenSSL EVP = 同 port 第二 adapter(差分对照包形引入), 装配切换,禁 flag 分叉——校验逻辑纯 MoonBit、全后端不因实现切换而破。 - **预设计形状**(签名随首用役微调;落码随首个消费者役——M2 分片校验): ``` pub(open) trait Digest { algorithm(Self) -> String // IANA 散列名,对位 Metalink hash@type("sha-1" …) digest(Self, Bytes) -> Bytes // 一次形 open(Self) -> &DigestStream // 流式:大分片 / 分块让出时用 } pub(open) trait DigestStream { update(Self, Bytes) -> Unit finish(Self) -> Bytes } ``` `Digest` 本身无状态,流式状态只住 `DigestStream`;adapter 按算法名出实现——`digest_for(name) -> &Digest?`,未知算法名 = `None`(缺席即语义, 由调用方按校验律处置);算法名 ↔ 摘要长度住摘要算法名表(TOML,大 gen 落点)。adapter 无 IO 零 async(纯包可依赖)。 - **触发线**(读数定,不是死线):目标线速 ≥ 2.5 Gbps 或实测哈希占主循环 > 50% → 引入 OpenSSL adapter(千兆下 mooncry SHA-1 中位 205 MiB/s,单核可跟);届时两 adapter 并存,正确性对拍可作门,性能对照仅留证不作门。 **[已落 2026-11-06,D1 性能役刀一]**:digest_ossl 包(sha1 硬流 EVP 直链,其余算法与非 native 腿 = fallback 组合;装配切换禁 flag 分叉; 坑账:moonbit_make_bytes 签名 = (size, value),stub 无罐之痛后立对拍罐 3 件双腿);probe E7 实测聚合管线 ~190MB/s 对位软 ~22MB/s。 - **落码形(M2a,随首个消费者落——sim 分片校验)**:预设计形状三处微调: ① 算法名由 String 改为**生成枚举** `DigestAlgorithm`(表源 `core/digest_vocab.toml` → airgen 词表发射器 → `core/digest_vocab_gen.mbt`: `iana_name` / `digest_length` 逐列投影 + `digest_algorithm_of_name` 反查 (表外名 = None,大小写严格)+ `digest_algorithms` 全集)——类型墙,未知名在词表层即挡;② 能力面收成 **`DigestProvider::open(algorithm) -> &DigestStream?`** (组合根注入 `&DigestProvider`,换 adapter 换装配一行;None = 本 adapter 不支持,能力差异实现面自拒);③ 一次形 `digest(Bytes)` 不立(零消费者, 最小骨架律——一次形 = open + update + finish)。分片校验律 = core `PieceCheck`(构造期两拒:算法不支持 / 期望片数 ≠ 段数;期望十六进制构造期归一小写;verify 不符 / 越界 = false → 调用方不得置位)+ `hex_lower`(比对一律走小写十六进制文本)。主 adapter = `core/digest_mooncry`(mooncry 0.95.0 纯包全后端;hasher 态枚举派发, sha224 / sha384 复用 Sha256 / Sha512 hasher 型但各走各的 update / finalize)。合规罐期望值 = coreutils 实算(与 FIPS 180 / RFC 1321 公布向量互证),禁由被测 adapter 自产回填。M2c 补流式面 `PieceCheck::begin` → `PieceVerifier`(update 逐窗 / finish 判片恰一次;随首个消费者——引擎边写边哈希——立),`verify` 一次形改走同一路径(单径)。 ### 3.6 段账律(SegmentMan;守恒罐逐条钉)`[K1 已落]` 1. **拆段守恒**:段区间相接无缝覆盖 `[0, total_length)`(半开),单段长 ≤ piece_length,末段收尾;空文件 = 0 段(恒完成)。 2. **排他律**:在途段不再出手——allocate 只出未定段(流式序,低索引优先);无未定段 → None。 3. **置位单径**(落盘时序,裁决 2):位图置位唯一入口 `mark_persisted`, 且仅限在途段——未定(含已回收)与已置位一律拒。置位先于落盘在类型面不可表达;engine 合同 = `write_at` → `sync` 成功后才调。**物理验证已落 K3**(§3.8:kill -9 两点注入,置位集 ⊆ 已落盘集);K4 真缝复验亦落 (§3.9:真进程 kill -9 × 8 轮随机注入,续传后全部字节守恒)。 4. **回收律**:失败让位 = 在途 → 未定,可再分配;已落盘不回收;未分配不回收。 5. **单调律**:置位集只增不减(无"取消已落盘"操作)。 6. **字节守恒**:persisted_bytes = 已置位段长度和;= total_length ⟺ is_complete。 7. **续传等价**:`restore(位图)` 重建账面——索引越界即拒,重复索引幂等; 续传后分配跳过已置位段,补齐即完成。 ### 3.7 持久化文法(protocol;金罐逐条钉)`[K2 已落]` 1. **控制文件 v1**(行格式):首非空行 = 魔数 `moonair-control-v1` (逐字节相等;版本演进 = 换魔数,不做静默兼容);域 = `total_length` / `piece_length` / `persisted`(逗号分隔段索引);未知键宽容忽略(转发兼容),缺域 / 重复域 / 坏数字即拒。**写侧镜像置位单径**:encode 只读 `persisted_indices`——未定 / 在途段结构性进不了文件(K1 律的持久化面)。形合法归 `decode`(ControlFileError),意合法归 `restore`(SegmentError) ——两层各自的负例各自读数。 2. **session v1**:每行一 URI;`#` 注释与空白行跳过;行律 = 无空白、无控制符(< 0x20 / 0x7F);编码与解析同径对称——入档非法 URI 即拒。 3. **HTTP 范围语义**(RFC 9110 §14.2):Range 三形(Closed / OpenEnded / Suffix)化归半开区间(不可满足 = None——416 语义归引擎);Content-Range 满足形 `bytes first-last/complete`(总长可 `*`;不满足形 `bytes */N` 不在本层)。 4. **Content-Disposition**(RFC 6266):分号分词引号语境保真;`filename*` (RFC 5987 扩展形)优先,字符集非 UTF-8 静默回退 `filename`;坏 pct / 坏 UTF-8 即拒;未知参数宽容忽略。 5. **aria2 控制文件导入词面**`[AC 已落]`(裁决 2「控制文件 = 自有格式 v1 (aria2 兼容导入候 oracle)」收口):v1 行格式仍是 moonair 自家持久账唯一写侧形;aria2 `.aria2` 二进制卷 = **只读导入面**(互操作:aria2 半程 → moonair `-c` 接续)。卷布局 = aria2 technical-notes 权威真源 (VER u16 = 1 全 BE / EXT u32 / INFO HASH LENGTH(非 0 = BT 卷域外拒)/ INFO HASH / PIECE LENGTH u32(< 16384 拒)/ TOTAL LENGTH **u64**/ UPLOAD LENGTH u64 / BITFIELD LENGTH + BITFIELD(piece 级完成位)/ NUM IN-FLIGHT + 条目{INDEX, LENGTH, PIECE BITFIELD LEN, PIECE BITFIELD(chunk 级 = 16384 字节/位,MSB = chunk 0)})。**进度两层并集投影**:BITFIELD piece i 置位 → 其 chunk 窗全置;IN-FLIGHT chunk → 全局 16384 粒度段对位——moonair 段账取同粒度即一一对位;多算风险由 K8b 片校验网兜,少算只多下无害(导入是加速不是义务:坏卷 / 版本不符 / total 与远端不符 / 越界一律走新建全重下,不 raise 不虚装)。 **真机勘定案(oracle 咬出)**:kill -9 卷的位图可超前盘面(auto-save 快照与盘刷的时序窗;位已置而字节未落)——导入防线 = 位图位 ∩ 盘面前缀(read_target_size,「整段字节都在盘上」才可证;裸 HTTP 无校验网兜场景的中段洞由此封死)。黑盒双样反推的域表(total u32@18、位图 @[50..])被真源全面推翻——「位 4 恒置」实为 PBFL 域 LSB(= 8 结构常数)的误读;金罐防漂移、真源防盲区,双保险律正名案例。 ### 3.8 sim 对打床(四形 × 参照驱动;判读单三面)`[K3 已落]` **安放**:sim/ 纯包(只依 core 与 protocol,全后端);参照驱动住 sim 不改 core(K1 拍:段落盘 port 随首消费者 K4 立)——本驱动是**协议层参照实现**, K4 真缝引擎另立后与它互为协议层参照(双实现安放律:同协议、异宿主)。 1. **四形假源**(SourceShape,敌手)+ Good 基线:不认 Range(200 全量,体恒从 0 起——驱动弃读到段起点)/ 断流(Drop,瞬时故障预算制:开连即掷, 预算耗尽后同 Good——对打必收敛且断流路径真实走过)/ 重定向(Redirect, 驱动递归跟进,深度帽截停环)/ 慢源(Slow,每拍至多 per_pull 字节)。 2. **页 / 持久双层假存储**(FakeStore):write_at 落页(易失),sync 刷穿 (fsync 全文件语义),控制文件写 = 原子持久模型(真缝的 write/fsync/ rename 拆分归 K4);字节洞 = `Byte?`,「置位而缺数据」因此可判。 **kill -9 模型 = crash 只留持久层**(页层全灭,账面自持久控制文件重建; 无账 = 全新账)。 3. **段协议参照驱动**(drive):置位单径协议循环——allocate → 取数 → write_at →〔注入 A:写后 fsync 前〕→ sync →〔注入 B:fsync 后置位前〕→ mark_persisted → 控制文件落账(每置位一笔即落,裁决 2 时序);断流 = release 让位重下。防御帽(重定向深度 / 单段拍数)把任何形状意外收敛为 Aborted,不死旋。 4. **判读单三面**:收敛(全段置位)/ 续传字节守恒(持久层逐字节 ≡ 金内容)/ 置位集 ⊆ 已落盘集(persisted_covered,恢复后与收尾各验一次)。两点注入的语义读数:A = 数据未持久账未落(全新账续传);B = 数据已持久账未置位 ——「数据而无置位」= 浪费不有害,有害面(置位而缺数据)结构性不存在。 5. **分片校验对打**(M2a,摘要 port 首个真消费者)`[M2a 已落]`:第五形坏片 (Corrupt(at_byte),预算制——只对**覆盖坏位**的连接掷预算并翻转该字节, 不覆盖的连接不扣,坏片路径必被真实走过)+ 源侧开连日志(open_log,服务器访问账)。驱动可选 `piece_check`(缺省 None = K3 流程逐字节不变): write_at →〔注入 A〕→ **校验** → 不符 = release 让位重下(不 sync 不置位; 盘上坏字节 = 有数据无位,判读面 4 已证无害,重下覆盖)→ sync → … 坏片帽 (max_piece_mismatches)截停永久坏源。罐面判读:**坏块只重传该块**(开连日志:坏片开连 = 1 + 预算,余片各一次)+ **负对照**(无校验时坏字节照样置位、收敛而金样不符——校验律是唯一防线)。夹具金内容须片间互异(周期图样会让片 0 与片 1 哈希相同,片号错配类 bug 漏网)。 6. **多源对打**(M2b,源池首个真消费者)`[M2b 已落]`:驱动可选 `pool` (缺省 None = 单源 0 号,K3 流程不变);源 URL 形 `sim://<号>` 映射假源下标。每段向池取源;断流 / 取数失败 / 校验不符一律 `fail` 计入该源降级账并 release 让位重下(多源下取数失败不再 Aborted——源失败只降级换源);全源出局 = Aborted("sources exhausted")。罐面判读走各源开连日志: 死镜像三断出局次优接班 / 坏片源三回不符出局且**已校验片不重下** / 全源不可用时已置位段保留 / 地点偏好生效(非偏好源零开连)/ ftp 镜像跳过记账。 ### 3.9 真缝执行面(engine + io;段协议 K4 落地)`[K4 已落;M2c 多源 + 校验已落]` **分层**:core 立 `StoragePort`(段落盘 port,K1 缓的 port 随首消费者落地; io/FileStore 参考实现,engine 消费,组合根装配);io = 落盘缝(@fs 定位写 / 刷穿 / 控制账原子持久 v2),engine = 传输缝(async http 流式拉取 + 任务组并拉)。缝整包 native;文法串(Range / Content-Range / 控制文件)一律走 protocol 口,禁散拼。 1. **StoragePort 合同**(七法;M2c 扩 `read_at`):`write_at` / `sync` / `read_control` (None = 无账)/ `write_control` / `clear_control`(完成销账)/ `close`。时序在驱动侧:write_at → sync → mark_persisted → 控制文件每置位一笔即落。 2. **io/FileStore**:开库 = `OpenOrCreate`(在则不截断——续传语义; `create` 的 allow_existing 是 CreateOrTruncate,禁用);控制文件 `.moonair`,原子持久 v1 = write_file + sync=Full 融合(rename 原子交换候 v2)。 3. **engine**:探长(Range `bytes=0-0` 定总长,206 走 Content-Range 文法对账 / 200 退 Content-Length)→ 建账或续账(续账须远端总长一致)→ connections 个工人并拉(协作式单线程,allocate / mark 都在 await 点外 ——账面无竞争)→ 单段流式逐拍定位写(206 定位 / 200 弃读,K3 同律; Content-Range 错位拒)→ 段满 sync → mark → 落账;短读 / 传输断让位重下 (每段三笔预算);收敛销账。空文件 0 段恒即成。 4. **跑卷读数**(回环 testsrv,8 MiB 随机金样,sha256 总判):全程基线 0.28s ≡ 金样;**真进程 kill -9 × 8 轮随机注入**(每轮杀至收敛,最多三杀)全部 MATCH——续传后无「置位而缺数据」,与 K3 两点注入互证; **aria2 1.36.0 差分对拍**:同 URL 多连(split=4)与 no-range 两形, aria2 / moonair 终局 sha256 逐字节一致(oracle 侧崩续窗未命中—— 8 MiB @135MiB/s 杀时已完成,如实记;崩续判据由 moonair 侧承担)。 5. **性能役三律(D1/修 A/Range 感知,2026-11-06)**`[已落]`: **读循环聚合律**——fetch_once 读块攒 Buffer(256KB)满批 write_at + verifier.update、段末 flush 尾块;落盘与校验喂入的字节序/量与旧形逐块等价(engine 罐守恒)。**连接复用律**——每工人持连对 (Client, 基形 URL),同源段间 keep-alive 复用(strace 实证 connect 14→5);206 成功(body 恰尽)交回复用,fault / 200 全量形 close—— 异常服务器残渣径由下轮 fault 自愈,数据完整性由段校验+终验守恒; 退场两出口(账枯 break / 全源出局 raise)close 收摊。**Range 感知律**——探长带回 Range 能力(206 认 / 200 不认,能力是源的属性随中标源带回);无 Range 源新账 = 单段全量(piece_length 取 total, aria2 对位:禁多连退单流;工人环按段账自然退化单流,strace connect 14→2);续传账不动;分片校验多片期望对无 Range 源 = 构造期拒。摘要硬化:digest_ossl 第二 adapter(sha1 硬流 EVP, 其余算法 fallback 组合,装配切换禁 flag 分叉)见 §3.5 位。 6. **多源 + 校验真缝(M2c)**`[M2c 已落]`:`download` 新增可选参数 (sources / preferred_locations / digests / pieces / file_hash,缺省 = K4 单 URL 形不变,老调用点零改动)。单源 = 单条目源池,单源多源同一路径;每源并发上限 = connections(单源时全工人同源,K4 同形),探长亦经源池轮转。网络错**就地归码**为源失败(只包网络操作),存储错照常上抛(盘错不是源的错)。**K4 潜伏缺陷修复**:原工人环短读后 `release` 再**原地重试**——重试成功时 `mark_persisted` 面对已退回的 Pending 段即 `NotInFlight` 整单失败(K4 罐未走到短读路径)。M2c 改为段退回待分配、任一工人重领;证伪罐(段 1 应答区间错位一次)先在 K4 引擎上跑红(NotInFlight,与推演一致)再随重写转绿。StoragePort 扩七法 `read_at`(终验读回口;FileStore = fs `read_exactly_at`,越尾即抛)。 ### 3.10 RPC 形(JSON-RPC;aria2 词表)`[K5 已落;M2d addMetalink 已落;B1 addTorrent 已落;词表入表 rpc_methods.toml → airgen vocab 投影;BT-RL 暂存重载已落(律 13)]` **类型墙**:JSON 进不了引擎——`Command` 指令枚举(AddUri / AddMetalink / TellStatus / Pause / Remove)即墙;rpc 层解 JSON 成指令,引擎只见指令。令牌槽在解码面剥出上交(`token:` 首参可缺席),核对面归 K6 安全三件;`id` 保 Json 形(数值 id 亦可回显,envelope 内不进引擎)。 1. **请求形**:jsonrpc 必 "2.0";method ∈ aria2 五词;addUri = URI 数组 (非空)+ 可缺席选项对象(键值皆串);addMetalink = base64 文档串 + 可缺席选项对象(位置参不收)——base64 严解、空白容忍(76 列折行), 解出须 UTF-8,本层剥成文档文本(XML 解析归组合根);tellStatus / pause / remove = GID 串。负例全闸。 2. **GID 形律**:16 位小写十六进制(aria2 实录恒此形)。 3. **响应形**:成功 = `{"id","jsonrpc","result"}` 键序同 aria2 实录, id 缺席发 null;addMetalink 结果 = GID 数组(序 = 文档 file 序)。错误应答 = `encode_rpc_error`,**文案逐字承 aria2 1.36.0 实录且回显请求 id**(M2d 勘正 K5/K6 的 id:null 与自拟文案):缺参 "The parameter at N is required but missing." / 错型 "The parameter at N has wrong type." (N 计于令牌剥离后)/ 空 URI 表 "URI is not provided." / 未知方法 "No such method: " / 坏 base64 · 非 UTF-8 · 坏 XML 同答 "Could not parse Metalink XML document.";协议级坏 JSON → -32700 + id:null。 **有意差异**:aria2 不判 jsonrpc 版本,本仓严判 "2.0";v3 文档 aria2 收、本仓答版本不支持(M-5,文案自定)。 4. **数字串律**:TellStatus 视图数值字段一律串形(oracle: "totalLength":"8388608");status 字串由表派生——core `state_name_of` 投影(codegen `state_names` 档,表名小写即词,禁散译),组装在引擎。 **终局码面**(M2d):`errorCode` / `errorMessage` 二键**只现于终局** ——complete 报 "0" 与空串,error 报失败码(引擎 DownloadError,aria2 码)与文案;active / waiting / paused 缺席(实录 E2b);键序 = 实录字母序。errorMessage 文案不逐字对 aria2(aria2 自身亦不一:404 "Resource not found"、整文件不符 ""),码是契约。 5. **金罐**:aria2 1.36.0 RPC 实录抓包(addUri / tellStatus / pause / unpause / remove / 错误三形 + 协议级 -32700;M2d 补 addMetalink 请求与 GID 数组应答 / 参数错四形 / 未知方法 / 坏 base64 / tellStatus 三态投影) ——请求原文进、应答原文出逐字节对拍,base64 夹具由 coreutils 编出, 非自产回填(异构 oracle 律)。 ### 3.11 RPC 服务(HTTP 缝;安全三件)`[K6 已落;M2d addMetalink 已落]` **形状**:rpc/server 整包 native;`serve(config)` 自建监听(配置 host:port), POST /jsonrpc;任务表(GID 键)驱动五词,工人住任务组(组收束自动取消)。 GID = 会话内单调计数零填 16 位(形过 gid_form_ok;熵面不出仓,跨会话唯一性归持久层)。组合根:摘要 = `core/digest_mooncry`、XML 解析 = `protocol/xml_milky`,`serve` 内一行装配。 1. **令牌判据**(裁决 5 之一):核对面 = rpc.decode_request 的 `secret` 档,**序承 oracle 实录——令牌先于 method**(未知方法 + 缺令牌答 Unauthorized);缺或不符答 `{"code":1,"message":"Unauthorized"}`(id 回显),指令不入引擎(负例罐:错 / 缺令牌后根内无文件产生)。 2. **绑定判据**(之二):ServiceConfig 构造期判——缺省 127.0.0.1;非回环 host 必须带令牌,无令牌对外即构造拒(启动期拦截,负例罐)。 3. **越界判据**(之三):`contain_path` 词法归一(归一域 = dir/out 相对段,root 是边界不参与段扫)+ realpath 逃逸核查——`..` 穿越 / 绝对路径 / 符号链接逃逸一律拒(负例罐三拒各一读)。 4. **任务面**:addUri → GID + 派真下载(engine progress 钩上报进度, await 点外写无竞争);tellStatus → 视图(status 由 core.state_name_of 表派生,数字串形);pause / remove → 取消任务(控制文件留半程 = K4 续传语义;oracle 词面:"GID#X cannot be paused now" / "Active Download not found for GID#X" / "GID X is not found")。 **addMetalink(M2d)**:文档经 `xml_milky.parse_metalink` 解析(坏文档 / v3 见 §3.10 律 3)→ **全部 file 先过越界判**(dir + file@name 经 `contain_path`,任一逃逸则整单拒、零任务登记)→ 逐 file 装配计划 (`engine.plan_metalink_file`:源表原样 / 择强校验料 / 地点偏好取选项 `metalink-location`)→ 每 file 一 GID 派工,应答 GID 数组。终局码面: 成 = 0;败 = DownloadError 码与文案(全源出局报末次码,§3.4 律 4), 他错归 1;暂停 / 移除触发的取消不落终局。存储在成败两路皆关(close 同步不挂起——顺手收掉 K6 失败路径的句柄泄漏)。 5. **端到端读数**(回环):addUri 真下载 → tellStatus 轮询至 `complete`(totalLength / completedLength 数字体面正确)→ 真文件字节守恒 + 控制文件销账;N=3 定稳。M2d:双文件 addMetalink(GID 数组逐字节)双任务收敛终局码 "0"——**择强真生效**(sha-1 错 + sha-256 对必须选 sha-256;变异试验把比较取反即红:a 报 32、b 片 1 校验耗尽报 1)、 **地点提升真生效**(`metalink-location=jp` ⇒ us 镜像零请求);整文件不符终局 32 控制文件留证;坏文档实录逐字 / 名穿越 / v3 / 符号链接逃逸整单拒零登记;进行中与暂停态无 errorCode 二键。N=3 定稳。 7. **saveSession 方法(RS;aria2 实录三锤)**:RPC 全任务面收口(W1 分账)。**实录三锤**(aria2 1.36.0 本机 RPC 实捕):①配置缺 → `code 1 "Filename is not given."`(逐字);②配置在场 → result `"OK"`;③落盘 = aria2 session 行(`\t\n` + ` gid=\n` + ` dir=\n`——URI 行尾 tab 0x09、选项行首空格 0x20,hexdump 锚) 且 **error 态任务落**(未完成可重载重试)、完成态不落。**词面** (protocol/aria2_session.mbt 纯面全后端):`encode_aria2_session` 行界律(URI/选项值禁 tab/换行——破行组界即拒;空表 = 空串覆盖写, 重载即无待办)+ 与 session v1 纯 URI 行(wget 面)两形不同源各按 oracle(RPC 面 = aria2,wget 面 = GNU wget)。**服务面**: ServiceConfig 升 `save_session?`(缺省 None 零改;None 即实录错文), TaskRecord 补 url/dir 域(AddUri 首参 + 任务目录;Metalink 任务 url 空 = 不落——会话行候选 oracle 补录),过滤律 = 非 Complete 落。金罐:protocol 实录逐字节 + 行界负例;rpc saveSession 双形解析 (params 空 / 仅 secret);服务罐(18613/18614/18615 三台)配置缺实录错文 + 一好一烂落卷过滤铁证(好行落 = 突变读数双行对照)。 **突变牙**:Complete 过滤短路 → 好任务行现身 → 逐字节不等当场红 (读数把两世界差异整行印出),复原绿 + N=3 定稳。rpc/server 9 罐; protocol 77;全仓 247。 8. **session 重载面(RS2;aria2 -i 对位)**:`decode_aria2_session` (词面补全,往返律 encode→decode ≡ 原表)——行组 = URI 行(尾 tab)+ 选项行(空格首,gid/dir 忽略——重载只需行身份;**aria2 保持原 GID 实录**(-i 恢复任务 tellStatus 原 gid),moonair GID = 会话内序号重载即新身份,gid 保持律候服务演化役);空文件 = 空表; 负例(URI 无尾 tab = session v1 形混入拒 / 孤选项行拒)。**serve 重载点**(group 挂后 run_forever 前):save_session 卷在场即逐 URI 走 add_uri 内核(同判据同 GID 序,应答弃);**坏卷不炸服**(读卷 /解码/单笔拒连全收口,就绪优先 A88)。**自愈闭环罐**(18616/ 18617):预置卷起服零调用 → 任务自动恢复直至 complete → saveSession = 空卷(完成不落;R3 wget 自愈形的 RPC 对位);负例:坏卷起服照活 + 坏卷零恢复(突变牙咬合面)。**突变牙**:尾 tab 守卫恒抛 → 恢复死自愈罐红(负例罐照绿——两罐读数分工:正罐测恢复活,负罐测死卷隔离),复原绿。protocol 78;rpc/server 10;全仓 249。 9. **Metalink 任务会话行(oracle 补录,勘定案收口)**:aria2 1.36.0 实捕——metalink 任务 saveSession 落 = **本地 .meta4 暂存路径行** (无尾 tab,与 URI 行尾 tab 两形分立)+ **file 子任务 gid**(非 addMetalink 父任务回执 gid)+ 构造选项行(` allow-overwrite=true`—— 构造选项入卷)。moonair 裁决:RPC addMetalink 文档内存直传无本地件可重读,**不落为正确语义**(非缺口);decode 对位修形——无尾 tab 首行 = 本地输入文件行,重载无源跳过行组(混形卷不炸:混形只收 URI 行组,纯 metalink 卷 = 空表重载无源);本地文件行重载候暂存面演化役。突变牙(跳过守卫翻位收路径行 → 混形罐 `2 != 1` 红,复原 grep=0);protocol 78 N=3 定稳。**分账**:GID 保持律候服务演化役; 暂存面已由 **RM2 收口**(律 10)。 10. **Metalink 暂存面(RM2;RS 役缺口收口)**:addMetalink 时文档落暂存件 = `<任务 dir 选项归一径>/.meta4`(aria2 addMetalink 实录名公式:sha1sum(文档) ≡ 暂存名前缀,2026-11-05 实录对拍;父目录自建 = aria2 `--dir` 不存在即建语义)——RS 役「文档内存直传无本地件可重读」缺口由此收口。**saveSession 行组落卷**(保登记序混排):URI 任务落 URI 行组(RS 形),metalink 任务落本地文件行组(path 无尾 tab + gid + dir + 构造选项排 dir 后原样——对位 aria2 实录 `allow-overwrite` 行);完成不落(RS 过滤律续)。**重载恢复**:decode_aria2_session_groups(行组统一形:staged 标 + line + gid/dir 抽出 + options 键值保序;旧 decode_aria2_session = 薄包装,URI 身份面契约不破)——URI 行组裸行走 add_uri(RS2 契约:卷 dir 行是绝对落盘形,add_uri 的 dir 选项是相对 root 子径,两形不同域不互喂);暂存行组读回文档走 add_metalink(dir 行相对化:同 root = 无子径,root/ 前缀 = 剩余子径,他形宽容弃 dir;构造选项原样随组;文档缺 = 跳过行组,RS2 宽容律续)。自愈闭环罐:预置暂存件 + 行组卷起服零调用 → metalink 任务恢复直至 complete(真下载字节守恒)→ saveSession 空卷;负例: 暂存件缺 = 零恢复服照活。protocol 86(+3:实录 staged 行组金罐 / 混形 decode 与旧面契约 / 负例四牙:路径破界·选项无 '='·空 key· 孤选项行);rpc/server 12(+2);全仓 261;N=3 定稳。 11. **GID 保持律(GD;服务演化役)**:重载恢复保持卷面原 GID(aria2 -i 实录律的对位兑现——律 8/9 分账收口):URI 行组 gid 选项在场即随组直register(表外收;空 gid 弃走新序号),metalink 行组聚 gids 数组按 file 序对位(add_metalink `keep_gids` 径;文件数不齐宽容缺省新序号)。**序号跳表共存**:next_gid 升序号循环避让——撞 GID(卷面与新任务同缘)宽容落新序号,保持律不排斥单调律。**共存罐** (18633/18634):恢复任务占 0001 → addUri 跳 0002(两律并证)。 rpc/server 13;N=3 定稳。 12. **WS 通知面(WS 役;aria2 告知面对位)**:`/jsonrpc` 同口 Upgrade 分流(`Upgrade: websocket` 头判)→ `@websocket.Conn::from_http_server` 升级 + subscribers 表登记(独立 `ws_seq` 键——**计数器撞车坑**: 与 GID 计数共用 counter 会吃掉任务序号,WS 罐实证 addUri 回 0002 非 0001,独立 ws_seq 修)→ 读环保活;任务事件广播 `notify` = `{"jsonrpc":"2.0","method":"","params":[""]}`—— onDownloadStart(Active 起跑)/ onDownloadComplete / onDownloadError (spawn 闭包打点;run_task 改返 StoppedReport 供终局面),发送败就地摘除(dead 表)。**订阅先行串行化**:connect 返回 ≠ 服务端 subscribers.set 已执行(101 响应后置),罐内 connect→addUri 之间 sleep 200ms——否则 Start 通知发进空表丢失(首帧收 Complete 的假象)。通知罐(18635/18636):订阅连收 Start + Complete,gid 对拍,真下载字节守恒。rpc/server 14;N=3 定稳。 13. **BT 暂存与重载面(BT-RL;B 档缺口收口,2026-11-06)**:addTorrent 任务入会话卷 + 重启恢复(B 档「url/staged 皆空不入卷」的候役兑现)。 **实录五发**(aria2 1.36.0 本机探针台;源码 SessionSerializer.cc :194-273 互证):①**裸 addTorrent(RPC 纯字节)不入卷**——BT 组落卷走 metadataInfo(`mi`)分支(落 `mi->getUri()`),无 `mi` 且 fileEntries 无 uris = 跳(active/paused/退出三态均验;saveSession 机制本身在话由 addUri 对照组钉);②带 uris 才落暂存件 `.torrent`(sha1sum 原件 ≡ 暂存名,字节 ≡ 原始——与 metalink `.meta4` 同构,非 info_hash);③落卷行形 = 暂存路径行(无尾 tab)+ gid + dir + 构造选项行(metalink 文件行组同形);④web-seed uris 不落卷(消费后弃);⑤重载 --input-file **保持原 GID** 实录。**moonair 裁决**:凡 addTorrent 一律暂存入卷 (裸 BT 不落系 aria2 实现怪癖——uris 只是触发暂存的副通道;自洽性优先,有意差异记此);暂存件随任务 dir(contain_path 同 metalink 先例,无 dir 选项 = root 直下);暂存位置 = announce/peers 判之后 (失败早退**零孤儿暂存件**);写败 = code 1(落不了暂存即无重载源,metalink 同律)。**重载判读**:reload_group 文件行组按后缀 `.torrent` 分走 add_torrent 内核(binary 无损读回——metainfo 判读吃字节,码 25/26 / assembly / announce 全链复用;`.text()` 文本径归 metalink);gid 走 GD 保持通道(每组一任务取首位);宽容律 = RS2 续(暂存件缺 / 解析败 / announce 败皆跳过行组不炸服)。罐: rpc/server 18(+2 BT 重载面罐——罐一暂存落盘 sha1 名公式 + saveSession 卷含 BT 行组(peer 指死口 = 任务悬挂非 Complete,落卷律不受完成竞态搅);罐二预置卷起服零调用原 GID 复活直至 complete 字节守恒 + 负例暂存件碎(码 26 早退)与暂存件缺两形皆跳过行组起服照活);门档行随行勘陈旧(rpc 实数 13 非 14,rpc/server 基线 16 非 15);全仓 276;oracle 台双口径(裸 276 五 SKIP 诚实印 + K9 PASS 零 SKIP)。 ### 3.12 XML 解析 port(M0;六边形 §9.1 落码)`[M0 已落]` **形状**:port 住 protocol(`XmlPull` trait + `XmlEvent` 中性事件—— Start / Empty / End 带 ns + local_name + qname + attrs,CData 并入 Text, 注释 / PI / Decl / DocType 在 adapter 滤除);adapter 住 protocol/xml_milky (Milky2018/xml 0.6.1,M-1 主;moonxml 0.3.2 后备同形装配切换)。纯包全后端(Milky 零依赖)。 1. **文档大小上限**(M0 定值:**4 MiB**,`METALINK_DOC_MAX_BYTES`)—— adapter 构造期前检,超限不发半截解析;负例金罐钉死(防依赖升级悄悄放宽)。 2. **Metalink 文档门**(`metalink_doc_gate`,RFC 5854 结构律):根元素须 `urn:ietf:params:xml:ns:metalink` 下 metalink(**缺命名空间在此拒**); 文档须含 ≥1 file 元素(RFC 5854:MUST contain one or more file elements——**缺 file 在此拒**)。门验毕原流回吐,M1 机器自此消费 (priority 词面值域等语义判读归机器——M0 分账)。 3. **解析安全**(Milky 安全默认,负例金罐钉死):XXE 外部实体引用即拒; 内部实体展开有界(billion laughs 形拒);坏文法统一 Malformed。 4. **正例金罐**:RFC 5854 §1.1 示例文档原文(标准向量)→ 中性事件流逐段钉死(命名空间识别 / 属性取值 / 文本节点边界含换行并节点)。 ### 3.13 Metalink 抽取机(M1;表源 metalink_fsm.toml)`[M1 已落]` **形状**:大 gen 四件——表源 `protocol/metalink_fsm.toml`(airgen 方言户第二表 `regen_metalink`,再生链与 download 表同:cmd → fmt → 黄金门)→ 投影 `protocol/metalink_gen.mbt`(禁手编);律法手写 `metalink_law.mbt` (表声明"哪格走它",本件定义"怎么算");类型墙 `metalink_doc.mbt` (MetalinkDoc / File / Url / Hash / Metaurl / Signature / Pieces);泛型驱动 `metalink_driver.mbt`(只认 `&XmlPull`;装配入口住 adapter 侧 `xml_milky.parse_metalink`——port↔adapter 依赖不回环,M2 换 adapter 换装配一行)。 1. **事件词表 = 语义元素事件**(N3 解析机同律:token→事件分类住驱动层, 机表管语境纪律):RootElem / FileElem / SizeElem / UrlElem / HashElem / MetaurlElem / PiecesElem / SignatureElem / MetaLeafElem / OtherElem + TextData / ElemEnd(载荷统一 `XmlEvent` 直通——同型载荷 ⇒ action 参数形态恒 Payload)+ Eof(无载荷)。分类器白名单 = 根 + RFC 5854 核心词表 + 元数据叶白名单(identity / version / description / os / language); 外名 = OtherElem 走 InUnknown 吸收态(深度账 + assign 行侧写 `unknown_return=Some(state:<来源态>)` 记回路,归零律法 stomp 回来源态 ——N3 pop_bnode_prop 弹帧家法;金罐含"内嵌已知名不误吸"面)。 2. **状态词表 = 抽取语境**(12 态):Top / DocBody / FileBody / 六叶文本态 / PiecesBody / PieceHashText / MetaLeafText / InUnknown。**非满表 = 兜底臂即拒**(N3 389 行同律)——与 download_fsm.toml 满表吸收律对照: 生命周期机 hold 是语义,抽取机拒是语义,两域各守各律(表头为凭)。 3. **校验错误通道 = `BusinessFailed`**(生成契约 `Result[Effect, ActionError]`),每条引条款位:file name 必填 + 跨文件唯一(§4.1.2.1)+ **路径安全**(M2d 补律,§4.1.2.1 Security Note:须相对,不得以 "/" "./" "../" 起首、含 "/../"、以 "/.." 收尾, 裸 ".." 同拒——aria2 实录对 "../evil.bin" 亦整单拒);文档 ≥1 file (§4.1.1)+ 每 file ≥1 url 或 ≥1 metaurl(§4.1.2);size 非负整数且每 file 至多一个(§4.2.14);priority 正整数 1..999999(§4.2.16.1); metaurl / signature mediatype 必填(§4.2.8.2 / §4.2.13);pieces type+length 必填 + length 正整数 + **同 file 内 type 唯一**(§4.1.3, M2d 补律)。Empty 元素 = 开即合成闭(空桶收口律自然拒);叶内嵌套元素拒(语境纪律)。 4. **ns 三态门**(驱动层,RFC 5854 §4 命名空间即版本面):v4 过 / v3 命名空间报 `UnsupportedVersion`(M-5 裁决专码)/ 其余 `Malformed`。 M0 门(metalink_doc_gate)保留管前检,M1 机器管语义——M0 示例跨验罐钉两门同判。 5. **hex 面缓账**:hash 值保真存文本(大小写归一与比对归 M2 摘要 port); M-4 未支持 scheme 跳过记账归 M2 引擎面。 6. **多 pieces 保真**(M2d 勘误):RFC 5854 §4.1.2 为 `metalinkPieces*` (零或多,§4.1.3 允多容器只要 type 互异),M1 原形 `pieces : MetalinkPieces?` 后者覆盖前者 = 静默丢料——改 `Array[MetalinkPieces]` 文档序全入账(表源上下文字段 `cur_pieces` 改型 + 再生,产物差三行), 择强归组合根(§3.4 律 4 末)。 ### 3.14 bencode + BT 元信息(K7;BEP 3)`[K7 已落]` **形状**:两件住 protocol(文法簇,纯包全后端):`bencode.mbt`(编解码)+ `metainfo.mbt`(.torrent 类型墙 + info_hash)。字符串 = 字节串(二进制安全, pieces 含任意字节);SHA-1 经摘要 port 注入(`&@core.DigestProvider`,K8 片校验同径),protocol 不直引摘要库。 1. **解码严格面**:BEP 3 明文非法者拒——前导零整数(`i03e`)、`i-0e`、非串字典键;本仓另拒:重复键(语义歧义)、尾随字节、截断、超 Int64、串长前导零、容器嵌套 > 64 层(`BENCODE_MAX_DEPTH`,防深递归——tracker 回包等网络入料同径)。错误面 `InvalidBencode(offset~, reason~)` 带字节偏移,报最内层先咬之处。**键序不判**:BEP 3 要求按原始字节串排序,乱序文档照收、字典保文档序——非正典输入的处置见律 3。 2. **正典编码**:整数十进制无前导零;字典键按**原始字节序**(逐字节无符号、前缀在先——不借 String 内建 (长度, 内容) 序);往返律:正典输入 `encode(decode(s)) ≡ s` 逐字节。 3. **info_hash 禁重编码**:BEP 3「info-hash 须是 info 值在 .torrent 中原样编码形之哈希」,对非正典输入「must either reject invalid metainfo files or extract the substring directly……must not perform a decode-encode roundtrip」——本仓取**原始字节子串**直接哈希(第二支,与 libtorrent 系同;拒收支会把乱序但可下的种子挡在门外)。**有意差异**: aria2 1.36.0 对键未排序文档做了往返(实录 `-S` 报重编码哈希 `862fc17b…`,原始区间为 `060362ed…`),即 BEP 3 所禁之举——同一种子 aria2 与本仓 info_hash 不同时,以 BEP 3 为准。 4. **结构律**(`parse_metainfo`,逐条带条款位):顶层字典 + info 字典; name 必填;piece length 正整数;pieces 长为 20 倍数;length 与 files **恰一**;files 项 = length 非负 + path 非空段序列;**片数 = ⌈总长 / 片长⌉**(aria2 实录同律,「Too few/many piece hash」);private = BEP 27 (=1 为真);announce 可缺,announce-list = BEP 12 分层表。**路径段安全律** (本仓律,与 aria2 实录同向——「Detected directory traversal directive」):name 与 path 段非空、非 "." / "..",不含 "/"。**文本面严格 UTF-8**(BEP 3);aria2 对非 UTF-8 name 照收并百分号转义——有意差异。 aria2 照收而本仓拒的非法形(前导零 / `i-0e` / 重复键 / 尾随垃圾)皆 BEP 3 明文非法或语义歧义。 5. **金罐双 oracle**:夹具 = python3 参考实现产出的 .torrent 原字节(参考实现自核 BEP 3 原文向量 `d3:bar4:spam3:fooi42ee`),罐内 base64 原样嵌入,与 aria2 `-S` 实际解析的文件逐字节同一;info_hash 期望值 = python hashlib 原始区间哈希 ≡ aria2 `-S` 自算 Info Hash(正典夹具两者一致)。乱序夹具上本仓正典编码器重编码再哈希恰得 aria2 读数——编码器与 aria2 往返形逐字节同形(异构互证)。变异试验:info_hash 改走重编码, 只有乱序罐转红且读数恰为 aria2 值。 6. **分账**:aria2 码 25 / 26(bencode / BT 元信息解析错,实录钉 26)入码表待首个消费者(addTorrent 或 K8 引擎面);BEP 52(v2 元信息)不收;前缀解码口(BEP 9 / 10 扩展消息 = 字典后接原始字节)随阶段 4 立;网络入料总长帽随 K8 / K9 定值。 ### 3.15 BT 线协议(K8a;BEP 3 peer wire)`[K8a 已落]` **形状**:`protocol/peer_wire.mbt`(纯包全后端;握手 + 消息编解码 + 分帧缓冲 + 位图)+ 消息词表大 gen 第五表 `protocol/peer_message_vocab.toml` (整数键列——airgen 词表发射器 K8a 补此能力:键列型 String 或 Int,反查形参随键型;串键旧表产物逐字节不变,黄金门 5/5)。 1. **握手律**:68 字节定长(pstrlen 19 + 协议串原文 + 保留 8 + info_hash 20 + peer_id 20);reserved 保真不解、本仓不置任何扩展位——对端据此不发 BEP 10 扩展握手与 have_all(aria2 实录:对端见全零保留位走 bitfield)。 2. **消息词表 = BEP 3 九种**(message_id 0–8,表源即词表):无负载四种 (choke / unchoke / interested / not interested)统收 `StateChange` (词表派生——增无负载消息 = 表加一行);have / request / cancel 定长核长(词表 payload_length 列);bitfield / piece 变长,piece 负载 ≥ 8; 字段 = 4 字节大端无符号,超 Int32 域即拒;表外 ID(0..255)保真上交 `UnknownMessage`(BEP 3 未定处置,本仓不断链、会话层忽略;BEP 5 port / BEP 10 extended 属阶段 4)。keep-alive = 零长帧。 3. **分帧**:4 字节大端长度前缀;帧长帽按会话定 = max(1 + ⌈片数/8⌉, 9 + 块上限),超即拒(`FrameTooLarge`);流可任意切碎, 残帧留待续推(`PeerFrameBuffer`,可选先收 68 字节握手)。 4. **位图两律**(BEP 3):尺寸恰 ⌈片数/8⌉ 字节、尾部备用位清零——违者断连(断连归会话层,K8c);片 0 = 首字节最高位。 5. **块上限 16 KiB**(`PEER_BLOCK_LENGTH_MAX`,BEP 3 现行值):请求超者断连——aria2 1.36.0 实录:32768 字节请求零回应直接断。请求 / 应答两侧共用常量。 6. **金罐双 oracle**:解码侧 = aria2 1.36.0 本机做种实录线字节 217 字节 (python 对端直连录得:握手回复保留位 `0000000000100004` = BEP 10 + BEP 6、做种方 bitfield `f0`、interested 后 0.6s unchoke、两块 piece 内容逐字节 ≡ 原文件;超限请求实录即断);编码侧 = python `struct.pack` 独立构字节逐字节。每条实录消息重编码 ≡ aria2 原帧(编码器线形互证)。变异试验:位图备用位律失效 → 位图罐红。**分账**:choke / unchoke / interested 状态面与 request 调度面随 K8b(片管线)接语义;have_all / have_none / suggest / reject 等随阶段 4;加密(MSE)不收(路线卷)。 ### 3.16 BT 片管线与可外发律(K8b;裁决 4)`[K8b 已落]` **形状**:core `PieceLedger`(分片账,纯包全后端)+ protocol `PeerSessionFace`(choke / interested 会话面)+ sim `bt_drive_pipeline` (参照驱动,首消费者);判片哈希走 M2a 摘要 port(`PieceCheck`,期望值 = 元信息 pieces,SHA-1 经 mooncry adapter)。 1. **分片账**:片内按块记覆盖位(块粒度构造期入参——线上块上限 16 KiB 属 protocol,账面粒度无关);乱序齐覆盖转待判(Completed),重复块幂等, 稀疏缺口不齐;构造期规格律(片数 / 片长 / 块长 / 总长域,总长 ∈ ((片数−1)×片长, 片数×片长]——parse_metainfo 的 ⌈总长/片长⌉ 防御性重钉); 末片跨截短。 2. **判片律**:判片恰一次且须待判——相符 → Verified;不符 → **回收** (块账清零回 Pending + 失败计数,重下)。 3. **可外发律(裁决 4 核心)**:片 i 可外发 ⇔ 判过相符(Verified)—— 未校验(Pending / Completed)与判败回收片**永不外发**;块外发核 = 可外发 + 块界落片跨内。变异试验:律短路(`exportable` 恒真)→ core / protocol / sim 三面罐齐红,复原转绿。 4. **会话面(BEP 3 choking)**:连接起于**双方互 choke、互不 interested**; 入站四词(choke / unchoke / interested / not interested)翻旗,他类消息不动面;**请求只发自未被抓**(BEP 3:对端对被掐请求可径直断连); **服务门 = 我方未掐对端 + 对端 interested + 块落可外发片**,三条件缺一即拒(合成门 `may_serve`,账面经 core PieceLedger)。 5. **参照驱动**(sim,与 K3 段协议驱动互为协议层参照):做种方持全档 (敌形可留未校验片列)/ 吸血方装配判片;坏块预算毒第 n 投一字节 (一次性,判败 → 回收 → 重下);**无进展停轮**(本轮判数零即停 + 轮帽 4 双保险——部分种敌形终止);choked 敌形请求照发、服务门全拒。 request 调度 = 文档序顺序片、块长 16 KiB 对位(调度策略是驱动内政策, K8c 引擎侧按同律自选)。 6. **金罐 12 枚**(core 5:建账规格律含 ⌈总长/片长⌉ 两拒一放 / 装配乱序幂等稀疏 / 判片恰一次与回收再判 / 可外发与块界四拒 / 完成律;protocol 2: BEP 3 初态翻旗与非状态消息不动面 / may_serve 三条件逐条件缺一拒;sim 5: 干净链每片恰一块 / 毒首投回收重下载序 [1,0] / 部分种拒发不收敛 / choked 全拒 / 细块粒四块边界);期望片哈希 = python hashlib 实算(公式档 30000 字节,离线 oracle 非自产)。**分账**:have 消息扩散 / 端到端 (真 socket 会话)与 aria2 做种对拍随 K8c;BEP 11(PieceHashAlg 双宽校验)不收。 ### 3.17 BT 会话真缝(K8c;aria2 双向对拍)`[K8c 已落]` **形状**:bt 新缝包(native;async socket 真会话)——`bt_download` (拨连下载)/ `bt_serve`(听连服务)/ `bt_serve_to`(拨连服务);线协议、分帧、账面、服务门全走 protocol / core 既有律件(K8a × K8b),本包只做接缝。网络错就地收 report(`complete=false` / `handshook=false` + detail),存储错上抛;账面补 `block_received` 覆盖位读数面(请求后等该块翻真再下一块)。 1. **下载会话**(`bt_download`):拨对端 → 发握手 → 收对端握手并核 info_hash → **interested 握手核过后立即发**(aria2 只 unchoke 已 interested 的对端——先等 unchoke 再表意向 = 死等,实录)→ 文档序顺序片逐块「请求 → 等该块覆盖位翻真再下一块」(沿途消息全量分派: choke 面翻旗、他片数据照常入账)→ 块落 StoragePort 边写边装配,片齐读回真校验,判败自动回收重下;choked 时阻塞读等 unchoke(消息照常分派);完成发 not interested;本轮零请求零判 = 对端无料,预防空转停轮。 2. **服务内核**(`bt_serve_conn`,听连 / 拨连共一体):握手相位**两形都开**(响应方收对端首握手,发起方收对端应答握手——漏相位 = 68 字节应答被当帧长前缀误读成超大帧长)→ 应握手(响应方)+ 本方 bitfield (有可外发片才发,备用位律在编码面)→ 对端 interested 即 unchoke (一次)→ 服务门放行的 request 读盘回块(可外发律 + 块界;拒者记账不回块)→ 收全档且对端 not interested 即体面收尾。 3. **两形**:`bt_serve`(听连:accept 循环轮帽 8——aria2 出站 MSE / 错种子连接拒绝即续接)/ `bt_serve_to`(拨连:直拨对端监听口,我方先发握手,K8c 上传 e2e 的确定性径)。 4. **aria2 双向不对称实录(方向反转的勘定依据)**:入站响应恒 plain (bt_download 10+ 连全绿);**出站先发 MSE 混淆握手**(高熵块,首字节 ≠ 0x13),legacy 降级策略随机——立即关闭换新连接 2/4、悬置不回永不降(ss 采样:单连接永持)、延迟关闭随机。上传侧 e2e 因此用**方向反转**: `bt_serve_to` 拨 aria2 监听口,aria2 当入站响应方,MSE 整条不进径; tracker 夹具与信号竞态整个退场。MSE 入阶段 4 清单不收。 5. **oracle 台与 oracle 罐纪律**:bt 双罐是 **oracle 罐**(aria2 1.36.0 本机做种 18901 / 吸血 18902,DHT / LPD / PEX 关,plain)——moon test 起跑前由驱动脚本先起双侧,**整模门亦须带 oracle 台**(驱动 `full` 模式);做种侧 `--check-integrity`(哈希核现成档 → 判齐 → SEED)+ `--seed-ratio=0.0`(缺省 1.0,上传量喂满即收种退场——seeder 中途消失根因)+ `--seed-time` 役程常驻;吸血侧每轮新起(下完即收)。罐判读 = 服务字节计(带早夭快败印);**罐外证** = aria2 落盘字节守恒(python 公式档对拍,oracle 非自产)。台件复建(K9c 随后役):驱动 = `sh driver/oracle_k9.sh`(判行 `ORACLE-K9: PASS`)——六只专享 aria2 会话编排(信号闸 tracker_up/tracker13_up 在场才 add 双侧 = 首注必达 A83;做种就绪门 tellActive seeder=true 才开考;RPC 探活窗 30s + 跑间排残 sleep——裸 10s 窗 N=3 第二跑 19802 绑口假死实证),台件入仓 (driver/mktorrent.py + oracle_k9.sh;上役落 /tmp 裸奔失传,重建时 K8c info_hash 锚 65ce77ee 的 name 域 = k8c-golden.bin 变体矩阵爆破复原——造件自证 A100 同律)。**seed 勘定案补笔**:`--seed-ratio=0.0 --seed-time=0` 组合 = 立即满足退出条件(status=complete、SEED 不立) ——0.0 配正时限(86400)才是常驻种。 6. **门与变异**:native 整模 176(174 + bt 2);整模 full 驱动 N=3 连绿 (双罐 + 落盘对拍全过);fmt / .mbti 漂移 = core 补 `block_received` 一行 + bt 新接口件。变异试验:握手 info_hash 产品位翻一位 → 双罐同形红(aria2 两向都验我方握手字节:「closed before handshake」+ 吸血档 0 字节),复原转绿——罐骑真线证成。**分账**:K9 = HTTP tracker(compact)+ sim 群 + have 扩散;MSE / DHT / PEX 阶段 4; >16 KiB 断连律(K8a 预录)已由服务门块界钉面。 ### 3.18 tracker 词面(K9a/K9c;BEP 3 announce + BEP 23 compact + BEP 48 scrape)`[K9a/K9c 已落]` **形状**:protocol `tracker.mbt`(纯面全后端,零新依赖,bencode K7 现货) ——双肩:client(announce query 构造 + 回包解码)/ server 夹具(announce 解析 + compact 回包编码);类型墙 TrackerAnnounce / TrackerAnnounceReply / TrackerPeer(octets = 网络序四字节 wire 原样 + port;点分形只作日志 / 拨面参考,protocol 不依 socket,拨面由缝包换装)。 1. **百分号字母表**:RFC 3986 unreserved(字母数字 + `-._~`)直通, 其余逐字节 %XX 大写——aria2 1.36.0 实录同款(记录式 tracker 台捕真请求行原样入罐);`+` 不作空格(tracker query 惯 %XX)。 2. **query 构造**(client):参数序按 aria2 实录(info_hash / peer_id / uploaded / downloaded / left / compact=1 / numwant / port / event); event 空串 = 周期重注不带 event。 3. **announce 解析**(server 夹具面):未知键忽略;info_hash / peer_id 强制且恰 20 字节律;compact / numwant(-1 = 未带)按值收;无 `=` 参数 / 坏 hex / 残缺转义全拒(负例是闸门不是数据)。 4. **回包解码**(client):bencode 强制;interval / peers 强制键;failure reason 在场即原文案上抛(FailureReason);peers 只收紧凑形(BEP 23; 步长 6 律;字典模型与整数载荷 Malformed——臂序病罐钉:BencodeInt 臂同样守 peers 键);warning reason 忽略。 5. **回包编码**(server 夹具面):正典键序 complete < incomplete < interval < peers;端口 16 位域律;octets 恰 4 字节律。 6. **oracle 与变异**:解析金罐 = aria2 真 announce 实录(started / 周期两形逐字段);编码金罐 = python 参照逐字节;query ↔ parse round-trip 同形罐。回包验收旁证:interval=1 下 aria2 二十轮重注并真拨了回包给的端点(CN:1)。变异试验:端口字节序翻 LE → python 金罐逐字节咬中, 复原绿。罐 +10;protocol 44(四后端同数)。 7. **scrape 词面(K9c;BEP 48;tracker_scrape.mbt 纯面全后端)**: announce 的只读对。query 构造 = `info_hash=` × N 以 & 连接(K9a 百分号族现货),每枚恰 20 字节、零枚拒(UDP scrape 同律); 请求解析 `parse_tracker_scrape`(服务面,与 parse_tracker_announce 同族形,未知键忽略);回包解码 `decode_tracker_scrape_reply`—— 顶层 `files` dict 强制(**legacy 无键平面形 = Malformed 负例闸**, 本仓现代形唯一),键 = 20 字节原始 info_hash,值 dict 三域 (complete / downloaded / incomplete)强制,未知键忽略;**缺席律**: BEP 48 「tracker may omit」——回执按请求序对位 `TrackerScrapeEntry?`, 缺席 None(与 UDP scrape 全零域两律不同源,各按协议真义);failure reason 在场即原文上抛(K9a 同律)。型 `TrackerScrapeEntry` 与 `UdpScrapeEntry` 三域同构但各自成词面(协议域不同,演化互不牵)。金料五罐(python bencode 参照 oracle 逐字节 + roundtrip 自证—— **金料生成教训 A100**:手拼 bencode 串多打一字节 / 裸 bytes 值漏长度前缀,两错全靠「python 侧 roundtrip 解析断言」当场咬出,金料生成必须带自证才入库)+ query↔parse round-trip 罐 + 负例七形全闸 (legacy 平面形 / 键短 19B / complete 缺 / complete 型错 / files 与值非 dict / 顶层非 dict)+ failure 上抛罐。**变异牙**:files 键 20 字节律短路(`&& false`)→ 键短负例罐当场红(`false is not true`), 复原绿 + 突变串 grep = 0。**scrape URL 推导**(`tracker_scrape_url`: BEP 48 replace 律——尾段恰 "/announce" 换 "/scrape",磁力 tr 只给 announce 位的推导源;查询串尾 / 已 scrape / 非 tracker URL 一律 None 推导不可即缺省不猜;裸路径形照 replace 律推;守卫短路突变牙 → 推导罐红复原 grep=0)+ 推导罐五形金罐。protocol 70→76(四后端同数)。 8. **分账**:K9b = HTTP client 缝(bt/)+ sim 群 + 本机 seeder 回环 (aria2×aria2 经本仓 tracker 相认对传);UDP tracker / DHT 阶段 4。 ### 3.19 tracker 真缝与回环(K9b;本机 seeder 回环)`[K9b 已落]` **形状**:protocol `TrackerSwarm`(群册律,纯面全后端——per(info_hash hex, peer_id hex)一记录;announce 刷新 / stopped 摘除 / 自身异排(按 peer_id——compact 回包无 peer_id 位,异排是 tracker 侧义务)/ counts 随 left 翻转)+ bt `tracker_http.mbt`(双缝:TrackerFixture 服务面—— @http.Server 三参回调 → 词面解析 → 群册 → compact 回包;`bt_announce` client 面——GET tracker → 词面解码)。 1. **夹具律**:对任何请求都回话(解析错走 failure reason 回包,不掷); 回环政策 ip 恒 127.0.0.1(@http Request 无对端 IP,0.22.x 勘定;真网侧由协议律收 ip 参数)、interval 定 1(秒级重注,罐快收敛);观测面 = announces / scrapes 计数(K9c 起)+ 群册读(罐轮询);K9c 起 scrape 路径分流(announce 与 scrape 两词面各自解析不互吃)——在册 hash 回 files 三域(complete/incomplete = 群册计数,downloaded = completed_events 完成事件历史账 = U2 落面的 BEP 48 首个消费链), 未在册或非 20 字节 = 省略键(缺席律的服务面真实消费)。 2. **回环罐**(进程内,零外协):client 两 peer 先后 announce——首注独行(peers 空、complete 含自身),次注得首注端点(点分 + 口); HTTP 状态非 200 = Malformed,网络错原色上抛(client 不吞)。 **scrape 回环罐(K9c,罐口 18914)**:announce 双侧入册(peer A completed 事件入完成账 + left=0 计 complete;peer B 吸血)→ scrape 两 hash——在册三域相认(complete=1 / incomplete=1 / downloaded=1)、未知 hash 缺席 None、scrapes 计数对账。 3. **aria2×aria2 回环**(oracle 台):双侧 announce 均指罐内夹具,经本仓 tracker 相认对传——群册双侧 left=0 = tracker 侧传输收敛信号(罐判读),落盘字节守恒由驱动对拍(罐外证)。K8c 直拨对同场复绿:K8c 吸血 torrent 钉死 announce(死端口)——tracker 活了 leecher 会从 seeder 直拉,破 bt_serve_to 独供罐语义(勘定案;驱动分 torrent 双对)。 4. **门与变异**:bt 四罐 oracle 驱动 N=3 连绿(双对传字节守恒);变异 (群册异排翻面)进程内罐当场红(`1 != 0`),复原绿;protocol 46 四后端同数(群律罐 +2)。坑账:A80(run_forever 同名两世界—— @socket.TcpServer = 裸接受环、@http.Server = 三参回调,拨错主 [4031]/[4013])/ A81(夹具 peer_id 字面量 19 字节自咬,20 字节律当场拒)。 5. **分账**:真网 tracker(公网可达)与 UDP tracker / DHT / 磁力(BEP 9 元数据交换)阶段 4;have 扩散 / 端策略(优化 unchoke)随引擎演化; K9 全讫。 ### 3.20 磁力与 metaurl torrent 词面(M3a;混合源 → BT 子集入口)`[M3a 已落]` **形状**:protocol `magnet.mbt`(纯面全后端,零新依赖——百分号解码复用 tracker 词面,RFC 4648 base32 手滚:core 无现货,不引三方)。 1. **磁力 URI 解析**(`parse_magnet` → `MagnetInfo` 类型墙:info_hash / name? / trackers):scheme 大小写不敏感;xt 恰一且 `urn:btih:` 前缀显式核(urn 大小写不敏感,错 urn = unsupported urn 拒);btih 载荷 = 40 hex(大小写不敏感)或 32 base32(RFC 4648,大小写不敏感,无填充) 收 20 字节;dn 百分号解码(重复 dn 后到者赢);tr 按序累计(不解码 ——URL 保真);未知键忽略(磁力可扩展),无 `=` 参数静默跳过;重复 xt / 坏转义 / 长度越形全拒(负例是闸门)。 2. **metaurl torrent 选拿**(`MetalinkFile::torrent_metaurl`): mediatype = "torrent" 是 §4.2.8 唯一保留值;文档序首个(Priority 排序属引擎政策不在此);无则 None——接 M1 类型墙既有 MetalinkMetaurl。 3. **oracle 与变异**:python 参照独立构造(`base64.b32encode` / 手滚 unreserved 百分号 / hex);btih 取 K9 夹具 info_hash(与真缝回环同源)。变异:base32 小写折算翻位 → 小写罐当场红(hash 漂移),复原绿。罐 +5;protocol 51(四后端同数)。 4. **分账**:M3b = 混合源真缝——metaurl torrent e2e(HTTP 取 torrent → K7 元信息 → K8c 会话下载;aria2 做种 oracle)+ 磁力引导回环(magnet → K9 announce client → 相认 → 下载)。 ### 3.21 混合源真缝(M3b;metaurl torrent e2e + 磁力引导回环)`[M3b 已落;M3 全讫]` **形状**:bt `metasource.mbt`(native)——`bt_split_url`(全 URL 拆 base/ 路径,@http Client 构造只收 base;http/https scheme 大小写不敏感)+ `bt_fetch_metainfo`(HTTP GET → K7 词面解形)/ `BtAssembly` 装配料 (info_hash 取原始 info 值跨度禁重编码(K7 律)+ PieceLedger 账面 + PieceCheck 判面(pieces 逐段 hex 下探);磁力互证与 metaurl 装配共用)+ `bt_download_metaurl`(取 torrent → 装配 → K8c 会话下载)。 `bt_announce` 升全 URL 形(`announce~`,磁力 tr 直入)。 1. **metaurl torrent e2e**:`MetalinkFile::torrent_metaurl`(M3a 选拿)→ HTTP 取 torrent → 元信息 → 装配 → 会话下载(aria2 做种口)。罐内 bencode 正典构造 torrent 字节(info dict 与 python mktorrent 逐字节同源)——**info_hash 互证先于下载**(assert ≡ aria2 夹具值)。 2. **磁力引导回环(三源互证)**:磁力 btih ≡ torrent info_hash(罐内 assert)≡ tracker 相认端点——magnet(tr 保真直入 announce)→ announce 重注环(轮到 aria2 入场,peers 非空)→ 端点回执(点分 + 口)→ 会话下载。BEP 9 元数据交换(纯磁力无元信息面)随阶段 4,本回环以「磁力引导 + metaurl 供元信息」收口。 3. **oracle 台律(勘定案三笔)**:①announce 驱动侧必须等各自夹具就绪信号——aria2 首注打在编译窗会吃长退避,罐窗等不起(v4 拆闸教训); ②每会话专享一只 aria2(单 interested 对端 = K8c 确定性 unchoke 形; 同 seeder 双罐争 unchoke 槽 → 第二对端「closed while choked」;同目录双实例亦忌);③metaurl 种用死 announce——不入任何 swarm,保磁力罐 tracker 回执恰一端点。 4. **门与变异**:bt 六罐 oracle 驱动 N=3 连绿(双对传字节守恒);变异 (URL 拆分偏移翻位)metaurl 罐在取 torrent 位当场折(InvalidFormat), 复原绿。 5. **分账**:M3 全讫——BT / 磁力混合源接 BT 子集成链(磁力解析 M3a → 选拿 → 取 torrent → 元信息 → 会话);BEP 9 元数据交换 / 真网 tracker / UDP tracker / DHT 阶段 4;多文件 torrent(files 布局)随引擎演化。 ### 3.22 wget 风格面(W1;断电传续可跑面)`[W1 已落]` **形状**:style 包(纯零依赖词面,四后端)——`wget_parse`(旗词汇表 `-c/-O/-q/-h/-V` 与长形 `--continue/--output-document[=value]/--quiet/ --help/--version`;短旗聚簇 `-qc`;`-O` 簇内连写;`--` 分界;重复 -O 后到者赢;`-h/-V` 单独给即成约——无 URL 亦过(wget 同款,初版罐后勘正);余者无 URL 即拒)+ 退出码律(0 成功 / 2 用语误 / 1 一般错;引擎码保守映射 aria2 3→8 余者→1)+ 渲染面(进度行含百分位 / total 未定字节形 / `'path' saved [done/total]` 收尾行 / URL 尾段剥 query 缺省输出名, 空段 index.html)。`style/run`(native 装配面)= wget 词面与 moonair 引擎的桥(`wget_main` 在库调用形直接喂 argv;`wget_exit_code` 人读行在此印、退出码回执)——moonwget 与 moonair --w 共用同径。可跑面两件: style/cmd = moonwget(薄启动器,extern "c" exit 留进程边界);engine/cmd 升双形路由——`moonair [connections] [piece_length]`(原形不变)与 `moonair --w [-c] [-O file] [-q] url...`(wget 词面,缺 -c = fresh 清盘,给 -c 才续)。examples/wget_demo = 单进程示例(进程内 200 全量台 + 装配面库调用 + 逐字节对拍,判行 `DEMO: PASS`——bind 先行 / spawn no_wait / server.close 收的三件套生命周期)。io `FileStore::open` 升 `fresh?`(真 = 目标 + 控制账两件移除后重建;缺省假 = 原续传语义不变,既有调用点零改)。testsrv 增 slow 模式(Range 认 + 64KiB 分块细流 + 20ms 睡——kill -9 可打断窗口)。 1. **kill -9 真进程续传 e2e(oracle 驱动,N=3 定稳)**:8MB 金料 slow 服务 → 无 -c 起 → 控制账现 + 部分字节落 → kill -9(账存活,数据先于账的排序律扛住硬杀)→ `-c` 续传 exit 0 → 逐字节对拍一致。 2. **清盘律**:无 -c 重下(垃圾 + 旧账先置)→ 字节一致 + 完成销账; `-q` 静默(无收尾行)+ query 剥缺省名。 3. **突变验证**:退出码律翻转(3→1)style 罐当场红,复原绿——罐骑真径非橡皮章。 4. **--w 路由与示例(W1.5)**:moonair 主令 `--w` 首位路由进装配面 (与 moonwget 同径,kill -9 + `-c` 续传 oracle 驱动 N=3 全 PASS, 字节对拍一致;默认形零改烟测同绿);examples/wget_demo 两轮 `DEMO: PASS`(进程内台,装配面库调用形,200 回退径)。 5. **会话两面(R3;session v1 词面首个消费链)**:style 词面扩 `-i file` / `--input-file=file`(会话入档,单独给即成约——aria2 同款旁路 MissingUrl)/ `--save-session=file`(失败名单出档); 装配面消费:入档文件读回 → K2 session 词面解析(注释/空行跳)→ **尾接在位置 URL 之后**(命令行位先);逐 URL 独立任务语义—— 失败记名不中断(aria2 同款),末次失败码出档律(全成 = 0,有败 = 末次码经保守映射);出档 = `encode_session` 覆盖写(空名单 = 空档, 重载即无待办)。e2e 罐(进程内台,烂路 404→翻轴转好):一轮记名出档恰烂路(末次码 3→8)→ 重载烂路转好 → 再出档 = 空档,自愈闭环; 突变(失败记名短路)当场红(退出码链 `0 != 8` 连断),复原绿。 6. **分账**:断电传续评审四缺口收其二(HTTP 续传 K4 早已在,本役补「真 -c 语义 + 可跑面 + kill -9 实证」;R3 会话级 save/reload 出档半收——按 URL 重试清单在;RPC 全任务面已落 RS(spec §3.11 律 7)); 控制文件 v2 rename 原子交换已落(R1);BT recheck 续传已落(R2);多连接并发数 wget 面不外露(引擎缺省 4);aria2 差分对拍(W1 无——wget 词汇面以 GNU wget 行为语义为金,非 aria2)。 ### 3.23 BT 断电续传(R2;片账复核)`[R2 已落]` **形状**:bt `recheck.mbt`——`bt_recheck(store, ledger~, piece_check~) -> BtRecheckReport { reverified, absent, mismatched }`:逐片(已置位跳过,幂等重入)读回落盘字节 → `PieceCheck::verify` 真校验 → 相符整片覆盖入账(`receive_block` 幂等覆盖 + `record_judged` 置位);越尾 / IO 错 = absent、在盘不符 = mismatched,两类保持 Pending 让位会话重取。 **数据即账律**:BT 侧不立控制文件——落盘字节本身就是账,复核在会话起步时重建账面(aria2 `--check-integrity` 同语义;自愈,无账可腐)。 offset 走逐片跨累加(末片截短律对位)。`bt_download_metaurl` 升 `recheck?`(缺省假;会话起步前复核)。会话驱动零改——`pending_pieces` 天然跳过复核置位片。**拨连收尾律(挂死勘定案)**:`bt_download` / `bt_serve_to` 会话毕(含中止径)关拨连——对端以读 None 收尾;悬空不关 = 服务侧 `read_some` 永等(进程内回环罐 join 挂死现形),中止会话还漏 fd。 1. **部分数据只补缺(双侧铁证)**:前 3 片在盘 → 复核恰 reverified 3 / absent 1;下载侧待装配恰 `[3]`;做种侧服务标记全为 `p3`(复核置位片零请求);回环收敛后字节守恒。 2. **坏片让位重取**:第 2 片翻字节 → 复核 mismatched 1(不记账不置位) → 会话重取自愈,终字节守恒(做种侧被问过 p1 铁证)。 3. **fresh 空盘等价**:空盘复核 = 全 absent 零置位,下载如常——复核对全新下载是诚实 no-op,不偷工。 4. **门与变异**:三罐 N=3 连绿(进程内回环,不依赖 aria2 台——bt 罐首次全进程内);突变(复核真校验短路)坏片罐当场红(`2 != 1`,烂片被误置位),复原绿。 5. **分账**:BT 断电续传评审缺口收讫(HTTP K4 + BT R2 两径齐);会话级 save/reload(R3)与控制文件 v2 rename(R1)后续役;bt_serve (听连)对连接本体不主动关(对端先关径,听连生命周期归 server 面) ——若将来立长驻 seeder,须补连接超时面。 ### 3.24 UDP tracker(U1/U2/U3;BEP 15)`[U1/U2/U3 已落]` **形状**:protocol `udp_tracker.mbt`(纯面全后端,零新依赖)——BEP 15 UDP tracker 词面全族,数据域序全大端:connect(请求 16B = 魔数 `0x41727101980` + action 0 + tid;回包 12B = action 0 + tid + connection_id 8B)/ announce(请求恰 98B:connection_id / action 1 / tid / info_hash 20 / peer_id 20 / downloaded·left·uploaded 各 8B / event 4B(0-3)/ ip 4B / key 4B / num_want 4B / port 2B;回包 = action 1 + tid + interval + leechers + seeders + peers 6 字节跨)/ 错回包 (action 3 + tid + ASCII 文,解码侧咬成 `UdpTrackerError::Malformed(reason~)` 上抛)/ scrape(U2:请求 16 + 20N = connection_id + action 2 + tid + info_hash × N,至少一枚;回包 8 + 12N = action 2 + tid + (complete / downloaded / incomplete)× N 三 32 位域——回包无计数字头,count 由调用方持,恰长律 8 + 12 × count)。 peers 6 字节跨(IP 4 + port 2)复用 K9a BEP 23 家族律(`TrackerPeer` + 点分形);event 词面 `UdpAnnounceEvent`(None 0 / Completed 1 / Started 2 / Stopped 3)+ `.word()` 投影接 K9b 群册事件词。 **事务核显式入参律**:transaction_id 不藏状态——解码侧逐包核对(不符即拒),client 用 connect tid、后续事务 tid+1。恰长律:UDP 无帧界, 恰长就是帧界(announce 98B / peers 余量 %6 == 0 / scrape 16 + 20N 与 8 + 12N)。**守卫先于读位律(A90 家族)**:解码器长度门须盖住最大读跨——门松于读位 = 越界 abort 非 raise(announce 请求门 `< 8` 咬 offset 8..12,U2 修为 `< 12` 并把 action-3 透传支路同盖)。 **缝**:bt `udp_tracker.mbt`(native)——`TrackerUdpFixture` 服务面 (`UdpServer` recvfrom 长驻循环:16B 包走 connect 发号(cid 自增)+ 回包;scrape 形(>16 且 16 余 20 倍,与 announce 98 形互斥不撞)走 scrape 核号按群册读数回三域;否则 announce 过 K9b `TrackerSwarm` 记账(ip 恒 127.0.0.1、port 取记录值),回包 peers 自除外——K9b 异排律的对位形,UDP 回包无 peer_id 位故以记录 port 区分;U3 起 serve 增 `drop_first?` 丢包敌手形,开局弃 N 包 = 丢包环境的进程内还原)+ client 面 `bt_announce_udp` / `bt_scrape_udp`(`UdpClient` 构造即连:connect 事务 → 后续事务 → `close()`;U3 起两段事务各经 `udp_roundtrip` 限时重试,可选参 `timeout_ms?=500` / `attempts?=3` 缺省零改)。 1. **金料六罐**(protocol;python struct 参照 oracle 非自产):connect 编码 ≡ 参照 16B / 回包解出 connection_id / 错回包文上抛;announce 请求 98B 金料逐域 + 对称律逐字段 + 负例四(connection_id 不符 / 恰长律 97 / event 表外字节 / info_hash 短);reply 金料 + peers 相认(dotted:port)+ 负例三(跨残 / 异 action 2 / tid 不符); scrape 请求 36B 金料(>QII20s)+ 对称律 + 双枚形 56B + 负例五 (零枚 / 短 hash / cid 不符 / 跨残 37 / 异 action 位);scrape reply 金料 20B(>IIIII)+ 对称律 + 双枚形 32B + 负例四(异 action = announce 回包混喂 / 恰长律截短 / tid 不符 / 错回包原文上抛); 残包守卫罐(8-11 字节拒收不越界 + 12-15 字节 action-3 位同盖—— 守卫先于读位律的钉面)。 2. **回环两罐**(bt;进程内 UdpServer,罐口 18935 / 18936,零外协 N=2):connect 发号 announce 相认 stopped 摘除(peer B 铁证 peers == [(127.0.0.1, 6881)];夹具 connects / announces 计数对账); scrape 三域相认(complete / downloaded / incomplete 对群册读数—— peer B Completed 一笔入历史账,downloaded = 1;未知 torrent 全零域;scrapes 计数对账)。 3. **突变验证牙**:事务核短路(解码恒认)→ connect 回包罐当场红 (`false is not true`),复原绿;scrape reply 异 action 门短路 → 混喂负例当场红,复原绿。 4. **纯包四后端同数**(protocol 57);域门子集 196(protocol +3,bt 罐不入子集)。 5. **分账**:aria2 UDP tracker 实录**不可达**(负结论入库,2026-11-05 勘定——aria2 1.36.0 实录 `udp is not supported yet`,UDP tracker 客户端官方从未实装;UDP 词面 oracle 仍由 python struct 参照承担, 异构 oracle 候第三方 BT 客户端/transmission 族);HTTP tracker scrape(BEP 48)已落 §3.18 律 7;退避参数按真网 RTT 勘定候真网役。 6. **限时重试面(U3;bt/udp_retry.mbt)**:`udp_roundtrip(client~, request~, timeout_ms?=500, attempts?=3)`——单轮 send→recv 包 `@async.with_timeout`(超时抛 `TimeoutError`),外层 `@async.retry(ExponentialDelay(initial=20, factor=2.0, maximum=200), max_retry = attempts - 1, fatal_error = 非 TimeoutError 即致命)`: 协议错当场折(重试无益),网络慢/丢包才重试。**async 根包现货勘正案**:U1 时「无超时面」的勘定只勘了 socket 层(socket 无超时 API 属实),根包 `with_timeout` / `retry` 组合面现货即收口——勘定以编译器实测为准,负结论同样要勘到根(性能役总纲铁律 1)。**事务语义**:重试 = 整事务重发(request 字节不变、tid 不变,服务端幂等面);六 client(tracker announce/scrape + DHT ping/find_node/ get_peers/announce_peer)统一接缝,可选参缺省零改(既有 17 罐零改动实证)。**回环两罐**(udp_retry_test.mbt,进程内,罐口 18944/18945,aria2-free):丢包敌手收敛(serve `drop_first=1` 弃首包 → announce 缺省策略退避重试收敛 + `elapsed >= 400ms` = 重试必经铁证——首试即成时墙钟毫秒级,下界证伪之);黑洞弃账(bind 不 serve → 三试尽 1500ms + 退避 60ms ≈ 1560ms 耗尽抛 `TimeoutError`, catch 哨兵形接(interval:0 = 夹具永不发的值域),墙钟守恒界 1400–6000ms,下界盖全窗上界帽抖动)。**供面牙兑现(M4.5 挂账收口)**:真缝罐 fetch 包罐侧 `@async.with_timeout(2000, …)` 壳 ——供面故障 = 卡 `read_some` 时壳折 `TimeoutError` 净红而非进程挂死;突变验证:自报 `metadata_size` 短 1 → 真缝罐 `failed: TimeoutError`(exit 2 非挂死),复原绿 + 突变串 grep = 0(原「三震报停」轮的突变在无壳时悬挂,本役以壳兑现净红)。 ### 3.25 DHT 地基:KRPC 词面、ping 回环、路由表与 peer 记账(D1/D2/D3;BEP 5)`[D1/D2/D3 已落]` **形状**:protocol `krpc.mbt`(纯面全后端,零新依赖——bencode K7 现货) ——KRPC 消息型墙三形:`KrpcQuery`(t 事务号 + q 方法名 + a 参数 dict)/ `KrpcReply`(t + r 回包 dict)/ `KrpcErrorReply`(t + e [code, text] 双元列表)。encode_krpc 三形正典(K7 encode_bencode 键原始字节序重排); decode_krpc 三键强制、y 表外拒、query 的 a 须 dict、error 的 e 须双元列表(code 整型 text 字节串);bencode 层错折算 Malformed 带 offset。事务号 = 任意短字节串原样往返(BEP 15 的 Int32 tid 是 UDP tracker 特化 ——KRPC 的 t 是 bencoded 串,两族不混)。恰长律 = bencode 收口(UDP 每报一数据报,残包在解码收口位拒)。ping 助手 = DHT 词表首个消费 (encode_krpc_ping_query / encode_krpc_ping_reply / krpc_dict_bytes—— 参数 id 域共用法)。 **缝**:bt `dht.mbt`(native)——`DhtFixture`(UdpServer recvfrom 长驻: ping 查询回本方 node_id,pings 计数控;非 ping 静默弃)+ `dht_ping_udp` client(查询 → 回包核事务号(不符即拒)→ 回对端 node id;错误回包折算 Malformed 带码与文)。 1. **金料三罐**(protocol;python 正典 bencode 参照 oracle 非自产): ping 查询 56B 逐字节 + 对称律逐域 + 负例六(顶层非 dict / 缺 t / y 表外 / 缺 a / a 非 dict / node_id 短);回包 47B + 错误 42B (203 "Method Unknown")逐字节 + 对称律 + 负例四(e 元数 / e 码非整 / e 文非字节 / 缺 r);事务号 1 / 4 字节三形往返恒等 + 截尾残包收口拒。 2. **回环两罐**(bt;进程内 UdpServer,罐口 18937 / 18938,零外协 N=2):ping 相认(回包 node id == 夹具 node id 铁证,pings 计数对账);错误回包径(假服务直回 203——client 折算 Malformed 带 203 文, 事务号相符不吞错)。 3. **突变验证牙**:y 分派短路 → 查询罐当场红(KrpcError.Malformed, 查询落「y 表外」拒),复原绿。 4. **纯包四后端同数**(protocol 60);域门子集 199(protocol +3)。 5. **分账**:路由表(Kademlia 160 位桶)与 find_node / get_peers / announce_peer + token 律随路由表役;BEP 42(节点 id 校正)候阶段清单;UDP client 重试退避律与 tracker 同账。 **路由表(D2;Kademlia)**:protocol `dht.mbt`(纯面全后端,零新依赖) ——`DhtRoutingTable`(160 桶 XOR 距离 / `DHT_BUCKET_K` = 8,数组尾 = 最近见)/ `DhtNodeInfo`(node_id 20B + octets 4B + port;`dotted()` 点分形)。**距离律**:逐字节 XOR 的大端 160 位序——逐字节比即全值比 (XOR 按位独立,高位字节定序先于低位,无需 160 位减法);**桶位律**: 最高异位的全局位号(`dht_bucket_index`,首字节 0x80 = 159、末字节 0x01 = 0;同 id = None);**LRU 律**:入册桶内去重刷新移尾、超 K 剔头 (最久未见让位);**closest-K 律**:全表聚拢按距离升序取前 K(选择排序——n 小且方向由 xor_less 显式持,避 sort_by 比较子方向陷阱)。 compact node info(BEP 5 "nodes" 值形态):26 字节跨 = 20B node id + 4B IPv4 + 2B 端口大端(`encode_dht_nodes` / `decode_dht_nodes`,恰长律 26N,空表合法)。find_node 词表查询(query a={id, target} / reply r={id, nodes})两形编码助手(`DhtError` 结构错误面独立于 `KrpcError`)。 **缝(D2)**:bt `dht.mbt` 扩——夹具 ping 问方入册(ip 恒回环、port 取数据报源口,K9b 夹具政策同款;self id 表侧拒)+ find_node 支路 (closest-K 回 compact)+ `dht_find_node_udp` client(核事务号 → 解 compact 跨;错误回包折算 Malformed)。 6. **金料五罐**(protocol):桶位律(159 / 152 / 7 / 0 四落点 + 同 id None);路由表 LRU(桶 159 家族首字节 ≥ 0x80 满 K=8 → 第 9 枚剔头 → 刷新移尾;self id 拒;低桶天然稀疏——桶 0 只容距离恰 1 的唯一 id,满桶演示须选高位桶);closest-K(乱序入册 + target 择距离序与桶序反向位——gather 序 ≠ 期望序,序断言有牙);compact 26B 金料 (python 参照逐字节 + 双枚 + 空表合法 + 负例:跨残 / 端口越 16 位 / octets 短);find_node 两形金料(query 92B / reply 109B)+ 对称律 + 负例(target / node_id 短)。 7. **回环罐**(bt;罐口 18939,零外协 N=2):双 ping 入册 → 异问方 find_node(target = 先问者)→ closest 序相认(target 距零者居首 = 铁证)+ pings / finds 计数对账。 8. **突变验证牙**:XOR 序比较短路 → closest 罐当场红(gather 序漏头 `7001 != 7032`),复原绿——先修罐咬合力(乱序入册 + 反向 target, 初版罐 gather 序 ≡ 期望序,变异不可区分)再验牙(A73 同族)。 9. **纯包四后端同数**(protocol 65);域门子集 204(protocol +5)。 10. **分账**:get_peers / announce_peer + token 律随下一役;BEP 42 (节点 id 校正)候阶段清单;过期摘除(ping 失活)与表持久化候引擎演化;UDP client 重试退避律与 tracker 同账。 **get_peers / announce_peer 与 token 律(D3;BEP 5 收官)**:protocol `dht.mbt` 扩——词表后两查询:`get_peers`(query a={id, info_hash}; 回包两形:**values 形** r={id, token, values}(bencode 列表,每元 6 字节 peer 跨 = IPv4 + 端口,BEP 23 同族形态)/ **nodes 形** r={id, token, nodes}(26 字节跨)——应答方有记账位回 values、无则回 nodes,**恰一键律**(双在场或双缺席即拒))+ `announce_peer`(query a={id, implied_port, info_hash, port, token};回包 r={id} 仅此一键;implied_port = 1 时 port 位被应答方忽略改取数据报源口)。**token 律**:token = 应答方先前发号的隐含串——问方 announce 原样回呈,应答方对发号账核(不在册 = 错误回包;夹具政策 203 "Bad token";真义轮换密钥派生候摘要役,夹具以 2 字节轮转计数代表)。`DhtPeerStore`(应答方 peer 记账:per info_hash hex 一桶,端点键去重重发幂等)+ `krpc_dict_int`(整数域取用)+ `decode_krpc_get_peers_returns`(两形合一解码域 `DhtGetPeersReply`: token + peers + nodes 恰一空)。跨错误域边界:`decode_dht_nodes` 的 DhtError 在 KrpcError 域面处折算翻译(错误域单一律)。 **缝(D3)**:bt `dht.mbt` 扩——夹具 get_peers 支路(token 2 字节轮转发号入 issued 账,记账位选形回包)+ announce_peer 支路(token 对发号账核,不在册 = 203 "Bad token" 错回包计数;implied_port = 1 取数据报源口落账)+ client `dht_get_peers_udp`(回执两形合一)/ `dht_announce_peer_udp`(token 回呈,implied_port 缺省 1)+ 错回包折算收口 `dht_reply_or_raise`(核事务号 + 码文案上抛,四 client 共用)。 11. **金料两罐**(protocol):peer 记账(store 新落真 / 重发幂等假 / 异端口新落 / 坏 octets 假 / 未知 info_hash 空);get_peers 与 announce 词面金料(query 95B / values 回包 76B / nodes 回包 94B / announce query 141B / announce 回包 47B ≡ python 正典参照逐字节)+ 对称律逐域 + 负例(values/nodes 双在场 / chunk 非 6 字节 / implied_port 表外 / port 越 16 位)。 12. **回环罐**(bt;罐口 18940,零外协 N=2):ping 入册 → get_peers (空记账 = nodes 形 + token 首号)→ announce_peer(token 原样回呈, implied_port = 1 落源口)→ 异问方 get_peers(**values 形相认铁证** :记账端点回执)→ 坏 token announce = 203 文上抛;tokens / announces / bad_tokens 计数对账。 13. **突变验证牙**:token 核发短路(未发号也认)→ 坏 token 罐当场红 (`"" != "krpc error 203 Bad token"`),复原绿。 14. **纯包四后端同数**(protocol 67);域门子集 206(protocol +2)。 15. **分账**:DHT 四查询全讫(BEP 5 词表面);token 轮换密钥派生已由 **DT 收口**(律 16);BEP 42 候阶段清单;过期摘除与表持久化候引擎演化;DHT 真网(BEP 5 公网 bootstrap)候 oracle 台清单。 16. **token 轮换密钥派生(DT;D3 分账收口)**:BEP 5 token 真义—— token = sha1(ip_bytes ‖ secret) 前 4 字节,绑定问方 IP;secret 定期轮换,**双窗核验**(当前 + 上一把都验真:轮换边界问方持旧 token 不抖;第三窗弃)——发号即派生,**无账本**(D3 夹具的 2 字节轮转计数代表形与 issued 账退役)。`DhtTokenVault`(protocol 纯核全后端): 摘要能力经装配根注入(DigestProvider;构造期 preflight 无 sha-1 即拒)+ `mint`(当前窗派生)+ `rotate`(当前挪上一把)+ `verify` (双窗对账);bt 夹具 `DhtFixture::new(token_vault?~)`——缺省内置 mooncry 装配 + 定值 secret,真部署注入。client 零改(token 原样回呈)。金料罐四向量 ≡ python 参照(sha1(7f000001‖s1)=f163a13e / c0a80102‖s1=35425433 / s2=3ea38735 / s3=b5007be0)+ 双窗轮换律罐 (窗二旧窗真新窗异 / 窗三旧窗弃)+ IP 绑定与确定性 + **轮换回环罐** (18946,零外协:vault 注入 → 发 A → rotate → 发 B 异值 → 旧窗 A announce 收 → 新窗 B 收 → 垃圾 203;tokens/bad_tokens 对账)+ **突变验证牙**:verify 退化为只查当前窗 → 轮换回环罐当场红 (KrpcError.Malformed,产物清后咬合——bt exe 挂陈货 protocol 产物一次假绿,坑账⑦再证),复原绿。D3 回环罐断言升级(token 派生形 79cd1dab = 内置 secret 回环派生实算;同 ip 同 secret 两问同 token = 派生确定性活证据)。protocol 89(+2 DT 罐)四后端同数;bt 22 (+1 轮换回环;5 oracle 罐候台);全仓 265;双 oracle 台 PASS。 ### 3.26 元数据交换(M4;BEP 10 + BEP 9)`[M4 已落]` **形状**:protocol `metadata.mbt`(纯面全后端)——磁力无种子链的元数据面:**扩展握手**(BEP 10,线 ID 20;payload = bencode dict:m dict 协商应用 ID + metadata_size 自报总长;`ExtHandshake` 域墙,两域皆可缺—— m 缺席 = 对端未表态 BEP 9,合法形)+ **ut_metadata**(BEP 9 三形: request {"msg_type":0,"piece":N} / data {"msg_type":1,"piece":N, "total_size":M} 尾续原始分片 / reject {"msg_type":2,"piece":N}; `MetadataMsg` 型墙)+ **分片律**(恒 16 KiB,`metadata_piece_count` 上取整 / `metadata_piece_of` 末片截短越尾即拒)。**协商 ID 下界 21 律 (勘定案)**:基础词表 0-19 与扩展握手 20 保留——更小协商 ID 会被 K8a 词表先吃(= unchoke 1 相撞的结构性风险),本面编码位钉 21..255。线位 = K8a `UnknownMessage` 保真上交(帧 = 长前缀 + ID + payload,恰长律 = 前缀 ≡ 余长);payload 级解码双供面(整帧面给线径,payload 面给分帧器径);K7 补 `decode_bencode_prefix` 前缀解码(data 形 dict 尾续原始字节)。元数据本体 = torrent info dict 原始子串(K7 禁重编码律同源),SHA-1 互证归缝面。 **缝**:bt `metadata.mbt`(native)——`BtMetadataFixture`(TCP accept 轮帽 8:握手核 info_hash → 应握手 + 扩展握手自报总长 → ut_metadata 请求读盘回分片,越界拒发;requests / rejects 计数)+ `bt_fetch_metadata` client(拨连 → 握手双向核 → 扩展握手换对端协商 ID 与自报总长(缺一即拒)→ 逐片请求(拒发即折)→ 拼装恰长核 → **SHA-1 互证 == info_hash** (mooncry)→ 回原始字节)。元数据面与 choke 解耦(BEP 9 与分块数据面平行,无意向/放行前置)。夹具 = 词面第二实现(服务面),回环罐同罐对打;本仓协商 ID 钉 21。 **真缝供面(M4.5)**:bt_serve / bt_serve_to 升 `metadata~ : Bytes? = None`(缺省 None = 不亮 BEP 9,aria2 oracle 罐与既有调用零改)—— 在场即握手后自报总长、派环接 UnknownMessage(20/21) 两臂(扩展握手再报 / ut_metadata 读盘回分片越界拒发),`BtServeReport` 补 `metadata_served` / `metadata_rejected` 计数。生产做种器与元数据面同场:一块一元数据两份字节,握手 hash = SHA-1(info 元数据)(磁力 btih 真义)。**回环两端 hash 同源律(勘定案)**:首版罐把种子数据 SHA-1 与元数据 SHA-1 分塞两端——serve 核握手失败弃连回 accept 等下一连、client 对等死等 = 对等悬挂(18942 双向 ESTAB 零流动;双文件印 C1/S1 后零音钉死),修 = 两端同一 `SHA-1(info)`。**突变牙分账 (勘定案)**:serve 面突变(自报总长短一 / 错片)产**悬挂而非净红** (牙形三震报停)——供面牙候带限时壳的 client(单程超时面,与 UDP 重试退避同账);protocol 分片律牙(恰倍 16384 现形)已足证词面。 1. **金料三罐**(protocol;python struct + 正典 bencode 参照 oracle 非自产):扩展握手带 size 52B / 裸形 29B 逐字节 + 对称律逐域 + 负例 (异线 ID / payload 非 dict / metadata_size 非正);ut_metadata 三形 request 30B / data 57B / reject 30B(协商 ID 21 帧)+ 对称律逐域 + 负例四(协商 ID 不符 / 下界 < 21 / msg_type 表外 / total_size 缺); 分片律(16384 → 1 / 16385 → 2 / 0 → 0 / 40000 → 3 + 末片截短 + 越尾拒)。 2. **回环罐**(bt;进程内 TCP,罐口 18941,零外协):40000 字节图样 (16KiB × 2 + 7232 末片截短径真实走过)→ client 拨连 → 字节守恒铁证 + requests 恰 3 零拒发;SHA-1 互证在 fetch 内置(失配即折, 罐侧另有夹具 info_hash 读数旁证)。**真缝罐(M4.5,罐口 18942, N=2)**:生产 bt_serve(metadata~ 在场)同场供块与元数据 → bt_fetch_metadata 三片拉齐 + SHA-1 互证 → 字节守恒 + 报告 metadata_served 恰 3 零拒发(报告候窗轮询——serve 侧察觉对端关连略后于 client 收毕;U3 起 fetch 包罐侧 `@async.with_timeout(2000)` 限时壳——供面故障折 `TimeoutError` 净红而非挂死,见 §3.24 律 6)。 3. **突变验证牙**:分片上取整短数 → 分片律罐当场红(`2 != 1`,恰倍 16384 处现形),复原绿;供面突变(自报 `metadata_size` 短 1)→ 真缝罐限时壳下 `TimeoutError` 净红(U3 兑现,原 M4.5 三震报停轮无壳悬挂——壳即牙),复原绿 + 突变串 grep = 0。 4. **纯包四后端同数**(protocol 70);域门子集 209(protocol +3);bt 17 罐(+1 真缝罐)。 5. **磁力无种子全链(M4.6,进程内收口)**:`bt_download_magnet`( bt/magnet.mbt)——**单连接共线**:拨连握手亮 BEP 10 扩展位 (reserved[5]=0x10)→ BEP 9 段(等对端自报 → 协商 ID 逐片拉齐 → SHA-1 互证 btih 磁力真义)→ info 原始子串手拼 torrent(**禁重编码律**;手拼长度前缀 A100 同族三犯:27 抄 17 当场 MetainfoSyntax) → 装配 → **同连接同分帧缓冲**交 `bt_download_session` 内核 (K8c 抽核:握手核后段;合同不变,罐全绿为证——外层握手核败关连分支与内核委托的 close 归位勘定案:close 后连接即死,委托必须在关连之前)。两次拨连不可行:bt_serve 握手成功即收摊(单连语义), 元数据与块必须同线(协议真义,BEP 9 的存在意义)。**全链罐** (进程内零外协,罐口 18950/18951):magnet btih → DhtFixture get_peers(空 → nodes+token)→ announce_peer 自报供口(implied_ port=0 走 a.port,自报语义)→ values 形相认(端点 == 供口铁证) → bt_download_magnet 全档 → 字节守恒 + verified 恰 3 + 供端报告 served >= 1 / metadata_served >= 1。**突变牙**:SHA-1 互证不等式翻位(== 恒 raise)→ 全链罐当场红,复原绿 + 突变串 grep=0。 bt 21 罐 N=3 定稳;全仓 245。**分账**:磁力无种子全链真网台 = 同链异源(DHT 真网 bootstrap 候清单);BEP 46 端口侧行候 DHT 演化役;分帧帽 20000 的真网 bitfield 上界候真网役。 ### 3.27 MSE/PE 协议加密(A 档 ME;Vuze MSE spec v1.0 真源直读)`[ME 已落]` **形状**:纯核住 `protocol/mse.mbt`(DH / ARC4 / 密钥派生 / req 同步件; 纯包全后端——`core/bigint` 现货 pow 带模,无需自实现 mod_pow);握手状态机住 bt/session.mbt(`mse_accept` + `bt_serve_conn` 判向),整包 native。aria2 出站 MSE-first 且降级随机(实录);moonair **入站接待缺省启用**(secret 缺省按 torrent 派生 `mse_secret_default` = sha1("moonair-mse-dh" ‖ info_hash),注入面 `mse_secret~` 留罐固定向量),出站不做(bt_serve_to 恒 plain——对位 aria2 入站响应恒 plain)。 1. **真源勘定案(初版四处词面被真源推翻,2026-11-05;erl_dist 坑账「金罐→真源双保险」同族)**:① DH 素数 = **RFC 2409 OAKLEY group 1** (768 位,尾段 `10000000000090563`)——初版误植 RFC 3526 group 14 (2048 位)全 F 尾;群不同则与真客户端 S 永不相遇。② **VC = 8 字节全 0x00**(spec v1.0 冻结原文)——初版杜撰 `e6e3770b48f99ad1`; 自回环罐对任意常量双端自洽都绿,金料 python 用同源错素数算的,罐全绿——金罐值域盲区律教科书案。③ keyA/keyB = `sha1("keyA/B" ‖ S ‖ SKEY)`(SKEY 对 BT = info_hash)——初版杜撰 `"keyA"+S+X+Y` 形。④ **RC4-drop1024**(首 1024 字节输出弃)。同步机制 = **明文** req1(`sha1("req1" ‖ S)`)滑窗定位(PadA ≤ 512, spec 终止界 628)+ 明文 req2xor3(`sha1("req2" ‖ SKEY) xor sha1("req3" ‖ S)`)验 SKEY 猜测;B 回复 = ENCRYPT(keyB)(VC ‖ crypto_select ‖ len(padD))——**不含 SKEY/PEER**(A 靠解出 VC 零自证猜测;初版「回 SKEY+PEER」为杜撰形,混入了别的协议)。教训: 协议常量与公式必须真源直读,自回环罐对双端同错的词面恒盲。 2. **接待状态机**(responder):读满 X(96)→ 发 Y(PadB = 0)→ 派生 → req1 明文滑窗 → req2xor3 验 → RC4(keyA) 解密域(VC 核 → crypto_provide:0x02 RC4 优先 / 0x01 明文次之,皆收 → len(PadC) 跳 → len(IA) 收 IA)→ 回程 → **payload 域密钥流续推律**(RC4 选定则双方继续同一密钥流,spec ENCRYPT2;明文选定双 None——ENCRYPT 域已终)。bt_serve_conn 首读判向(`0x13` = 明 BT 协议串首字节;他值 = MSE 候选),读经 `bt_conn_pull` / 写经 `bt_conn_send` 封装(明径 None 直通,既有罐行为不变)。拒 = detail 记因连接弃——aria2 降级策略以 plain 重连,accept 轮帽 8 内走通。 3. **报告旗**:BtServeReport `mse_accepted`(接待事实;bt_serve / bt_serve_to 全构造点补齐)。 4. **回环罐**(bt,罐口 18952,零外协;**口避雷**:§3.26 M4.6 已用 18950/18951,新罐新口——顺序执行不炸、并行是雷,hang 罐同口复用前科姊妹):手搓 initiator(纯核件拼 wire)→ bt_serve(secret 注入) 真缝全链:X/Y 对拍(secret 注入对)→ PadA 7 字节垫测滑窗 → RC4 全链 BT 会话(interested → bitfield + unchoke → request ×2 → BlockData ×2)→ 全档 30000 字节守恒 + 服务侧 mse_accepted 旗。 **罐五坑账**:① enc_block 多写一零 → len(IA) 读成 0 → 空 IA → 服务端帧缓冲等握手 / initiator 等握手应答互等死锁;② **TCP 余量律**——read_some 一次可能收多帧(68+6+5),攒读 helper 只物化前 n 扔余量 → 等 unchoke 挂死(carry 余量缓冲正修);③ decode_peer_message 语义 = **去 len 前缀 body**(传全帧 → decode 败);④ 收尾门 = 发 NotInterested(aria2 真客户端同款)→ `served ≥ total && !peer_wants_ours()` 体面收尾——read 不返 None 且对端 interested 未撤则主环不退,bt_serve 不返回;⑤ 服务收尾轮询必须在 with_task_group **块内**(块尾收束取消未完任务,块外轮询永远赶不上)。⑥ **印系统病理再证**:`@fs.write_file` append=true 不生效(每笔覆盖,文件只剩最后一印)——挂死取证用独立文件印(一步一文件,ls 即全流程序列)。 5. **纯核金料**(protocol 91 四后端同数;python 机器生成写回三证律): DH 模幂(X/Y/S ≡ 实算)+ 对称律;派生四件(keyA/keyB/req1/req2xor3, skey = "moonair-mse");ARC4 drop1024 位对拍(RFC "Key" 裸流 1024-1048 位)+ 流续推 + 互逆律(同 key 新流复原;同流二过 = 流推进)。bt 23(裸跑 18/23,五罐候台;带台 23/23 = ORACLE-K9: PASS, 含 MSE 罐同轮)。**拒径降级罐(A 顺手役收口,罐口 18953)**:第一连 MSE 候选带**异 info_hash**(req2xor3 以异 skey 构造)→ 服务端拒 (detail = "mse skey mismatch")且沉默不关连 → initiator 限时壳 (`with_timeout(2000)` 包回程读)超时关连 → 第二连 `bt_download` plain 重连 → 全链下载守恒;断言服务侧 mse_accepted == false(第一连拒、第二连明 BT)+ handshook + 体面收尾。**突变牙定谳(skey 错配形)**:mse_accept 内 skey 位换定值(服务端身份错配 → 全链自洽于 bogus)→ 第一连**误受** → 回程到达(限时壳不超时 stalled = false)→ 拒径罐 `assert_true(stalled)` 红——牙咬实(文件印 D2-stalled=false 铁证)。**牙验三坑账**:① 拒径的纵深闸系列 (req2xor3 → VC 核 → provide 位)——拆单闸/双闸都被下一道兜住仍拒,牙面必须是「身份错配」级(全链自洽)才漏得到「误受」;② 断言必须后置到第二连完成之后——前置则失败径不拨第二连,bt_serve accept 永挂吞报告(全局表现 = 挂死非红);③ 突变态全局跑被**回环罐挂死遮蔽**(回环罐无降级径,拒后 accept 永挂)+ 失败报告缓冲不刷——牙验读数以探针印/断言变量为准,不信全局读数。**分账**: aria2 真机 MSE 接待台(aria2 --bt-require-crypto 拨 moonair)候真网演化役;出站 MSE(bt_download 侧)候演化役。 ### 3.28 moonx 命令面前置:缝包 native+wasm(X 役 AX0)`[AX0 已落]` **来历**:用户勘问「moonx cli/wget 能做 wget,能否 cli/air 跑 moonair」;勘定茗篇 `.mingspace/air_ming.md`(X-1~X-5,2026-11-05 拍)。**事实链**:moonx = 注册表预编译 wasm 启动器(只认 wasm,`moonrun -- 参数`);moonrun 把 moonbitlang/async 的 C 桩整套做成 wasm 宿主导入(cli/wget 导入 105 个 async 宿主函数;moonrun 另有 bind / listen / accept 与 UDP 收发)——async 栈在 wasm 上不是降级形,是同一套 API 换宿主。moonair 零自有 C 桩,native 只是钉子。 1. **双钉律**(X-4 拍 A):9 包 `supported_targets = "native+wasm"` 显式双目标(engine / engine/cmd / io / rpc/server / bt / style/run / style/cmd / examples ×2);不留空——async 不支持 js / wasm-gc。模块 `preferred_target` 保 native,接口件口径不动(零漂移经核)。 2. **可移植出口**:两 cmd 入口退出桩 `extern "c" fn … = "exit"`([4156] wasm 不收)→ `moonbitlang/x/sys` 的 `exit`(按 target 分件 ffi,cli/wget 同源);模块加 `moonbitlang/x@0.5.6`。 3. **门**:全模块 wasm check --deny-warn 61 任务 0 错(清 `_build/wasm` 全量——增量「2 tasks」不作覆盖读数);native deny-warn 64 任务 0 错; native 全仓 271 不变;wasm 腿五包同数(红 5 ≡ native 台形);双 oracle 台 PASS(native 退出码面无回归)。 4. **命令面住别仓**(X-2 拍 A):薄模块 `thy1016/air`(bitbang2 独立仓, `preferred_target = "wasm"`,根包可执行);两用法(X-3):`air ` (moonwget 引擎)/ `air --enable-rpc`(本仓 rpc/server,旗名按 aria2c 1.36.0 原文)。air 的 e2e 台(native + moonrun 直跑 wasm × 下载 / 404 退出码 / RPC addUri → complete,`AIR-E2E: PASS` N=3)住 air 仓。 5. **分账**:发布(X-5:moonair 首发 → air,dry-run 过目后明令真发)+ moonx 本机实跑(预编译件出处 / 默认 policy 下服务端监听两项未验面)候 AX2;wasm 腿性能读数未测(性能役口径)。 ### 3.29 传输界面渲染件(progress;air/progress 评审收编形)`[已落 2026-11-06]` **来历**:air 侧 progress 包(air 0.0.2,rich_review R-1 后续役)评审 → moonair 侧收编落位(库模块自持渲染件;组合根装配)。**形**:零依赖纯件 (`native+wasm` 双钉,零 import)——格式三件(`format_size` 1024 进位一位小数满档上移 / `format_rate` / `format_eta` 向上取整进位:秒内 `8s` / 时内 `1m12s` / 以上 `2h05m`)+ 棒件(`progress_bar` `=` 填充 `>` 引头,低幅不显标记,越界钳 0..100)+ 进度表 `ProgressMeter`(frame 喂样取帧:EMA α=0.7 区间采样平滑 / 0.5s 节流 / 终帧强印 / ANSI 覆写协议 `ESC[1A\r` 光标上一行回列首 + 短帧按上一帧可见宽补空抹残影 / reset 换任务清账;总量未知走 size + rate 两段形)。**时钟注入律**:本件无钟无 IO,frame 的 now 参由调用方喂单调秒——native/wasm 双脸同码, 罐直接钉时间轴。 **采样落帧径**(对 air 0.0.2 喂样径的评审改进):采样与基点推进只在 **落帧**发生——节流吞帧区间不丢账,速率跨吞帧区间累积(air 形吞帧区间丢弃 = 速率略低估;专罐钉:连吞两帧后落帧 inst = 跨区间全量, 零区间丢弃)。air 侧 0.0.2 在册不动,升版收编候 air 侧役。 **接线位**:`engine.download(progress~ : ((Int64, Int64) -> Unit)?)` 已备(worker_loop 每片完成打点 persisted/total)——**已接(2026-11-06 接线役)**:style/run 装配面换 ProgressMeter(装配收口律原意:进度印住 run 面;非 quiet 即 meter 印,节流单行活刷,每 URL 新账;钟 `now~` 注入 wget_main 可选参,缺省 `@env.now()` 毫秒归秒;WgetCell 记账面保留供 saved_line——meter 账位 priv 外包不可读,cell 与 meter 并行喂)。 **实跑铁证**:moonwget 真下载首帧裸印 + 终帧强印(`[1A` 覆写协议在场) + saved_line 收口,字节守恒(200000/200000)。air 侧零改(升依赖钉即得,候 moonair 发版);wget 词面行 `@style.wget_progress_line` API 保留(style 罐钉,装配面换印不退 API)。**可见宽律**:帧内容全 ASCII (格式件恒出),`length()` 即终端列宽——将来引入非 ASCII 须换列宽计算 (头注钉)。罐:progress 10/10(native + wasm 双腿;格式边界 / 帧序列 / 终帧豁免 / ANSI 补空 / 累积径专罐;坑账:手描尺寸串三错以首跑 diff 为准——air 侧同坑复现同药愈);全仓 286/286(门档行 276 → 286)。 ## 四、验收门 | 面 | 门 | |---|---| | 生命周期律 | 守恒罐 8 枚(全链 / 暂停恢复排队 / 终态吸收 / 唯 Active 完成失败 / 调度唯 Waiting / 失败记码 / 移除自非终态 / 全格无错路 36 格) | | 段账律 | 守恒罐 8 枚(拆段守恒 / 分配序+排他 / 置位单径 / 回收律 / 字节守恒+完成判 / 续传等价 / 越界与构造负例 / 空文件) | | 持久化文法 | 金罐 12 枚(Range 标准向量 + 化归律 / Content-Range / Disposition RFC 6266 向量与回退律 / 控制文件手写字节夹具 + 全文往返 / session 往返与对称律;负例全闸) | | sim 对打床 | 罐 22 枚(Good 基线 + 四形各一枚 + 重定向入敌形组合 + 重定向环负例;kill -9 点 A/B 各首崩与第 3 机会四枚 + A/B 连环 × 不认 Range;判读单三面逐枚:收敛 / 字节守恒 / 置位集 ⊆ 已落盘集;M2a 分片校验五枚:坏块只重传该块 / 坏片预算 3 / 末短片 / 负对照无校验坏字节落盘 / 永久坏源截停坏片永不置位;M2b 多源五枚:死镜像切换 / 坏片源降级且已校验片不重下 / 全源不可用已置位段保留 / 地点偏好生效 / ftp 跳过记账) | | 真缝执行面 | io 罐 6 枚(定位写守恒 / 控制文件三态 / 重开不截断 / read_at 恰读 ≡ 写入越尾即抛 / fresh 清盘两件移除缺省续传不变 / 控制账 v2 原子交换换名件收编双换无残销账双净)+ engine 回环罐 12 枚(K4 四枚:单连 / 多连 16 段 / 200 回退 / 续传跳段计数;M2c 七枚:证伪·段 1 区间错位一次让位重下收敛 / 坏片镜像三回不符出局且已校验片不重下 / 死镜像拒连三回出局 / 整文件终验相符 / 不符报 32 控制文件留证 / 全 404 报 3 / 全拒连报 1;K7 役补混合失败一枚:404 与拒连互换优先级两序报末次码 1 / 3;真 @http 栈,N=3 定稳)+ engine 计划器罐 3 枚(M2d 同步纯面:file 级 hash 择强 + 源表原样入池 + 地点偏好随计划 / pieces 择强段长随选中元素表外类型丢弃 / 全不认不校验 + 无 url 空源表空 url);跑卷 = kill -9 × 8 轮全 MATCH + aria2 差分两形一致(§3.9);R1 = 控制账持久 v2 上真缝(kill -9 驱动 PASS,域门 190/190) | | RPC 形 | 金罐 12 枚(K5 七枚:aria2 1.36.0 实录逐字节对拍成功 / 错误 / -32700;GID 形律;数字串律;解码负例全闸——空 URI 表改判 NoUri;M2d 五枚:addMetalink 实录请求串 base64 → 文档原文逐字节 / 折行 base64 同解 + 选项入指令 / 错误应答全管线九例请求原文进 oracle 应答原文出 / GID 数组应答逐字节 / tellStatus 三态 ≡ 实录投影逐字节) | | RPC 服务 | 罐 10 枚(K6 四枚:绑定判据构造期拒 / 越界判据三拒 + realpath 逃逸 / 令牌判据错缺双拒 + 指令不入引擎 / 端到端真下载轮询收敛字节守恒;M2d 四枚:双文件 addMetalink 择强与地点提升真生效终局码 0 / 整文件不符终局 32 控制文件留证 / 坏文档实录逐字 + 名穿越 + v3 + 符号链接逃逸整单拒零登记 / 进行中与暂停无 errorCode 二键;N=3 定稳 + 择强变异试验证牙;RS:saveSession 配置缺实录错文 + 未完成入卷完成不落过滤铁证(aria2 session 行逐字节金料)+ 突变牙(Complete 过滤短路红)+ aria2 session 词面金罐(protocol +1;RS2:decode 往返律 + 重载自愈闭环罐——预置卷起服零调用恢复直至空卷 + 坏卷不炸服零恢复 + 尾 tab 守卫恒抛突变红;RM2:暂存件罐——addMetalink 落 `.meta4` 名公式 + 原文逐字节 + saveSession staged 行组(gid/dir/构造选项)逐字节;重载恢复闭环罐——预置暂存件 + 行组卷起服零调用恢复直至 complete 字节守恒空卷 + 暂存件缺零恢复;GD:共存罐——恢复任务占 0001 → addUri 跳 0002(保持律与序号跳表并证,§3.11 律 11);WS:通知罐——订阅连收 Start + Complete gid 对拍真下载守恒(§3.11 律 12;独立 ws_seq 计数器撞车坑与订阅先行串行化勘定案入卷)) | | XML port(M0) | 罐 7 枚(RFC 5854 §1.1 原文事件流金罐 + 属性面 + 文档门放行;XXE / 实体炸弹 / 超上限 / 缺命名空间 / 缺 file / 坏文法六负例;滤除与 CData 并入面) | | Metalink 抽取机(M1) | 金罐 25 枚(RFC 5854 全语义面正例:类型化全字段 / 未知子树吸收含内嵌已知名不误吸 / M0 示例跨验 / 多文件账面隔离 + metaurl-only;负例 18:priority 三拒 / size 四拒 / name 两拒 / url-metaurl 收口拒 / mediatype 两拒 / pieces 两拒 / v3 专码 / 错 ns / 叶内嵌套拒;M2d 三枚:多 pieces 文档序全入账元素间与文件间不串账 / pieces type 重复拒 / 名穿越六形拒 + RFC 子目录例放行)+ 黄金门 metalink 罐(regen + fmt ≡ metalink_gen.mbt 逐字节) | | 摘要 port(M2a) | core 罐 9 枚(词表投影往返 + 表外名 None 大小写严格 / hex_lower / PieceCheck 构造期两拒 / 校验三态 + 大写期望归一 / 流式面分块 ≡ 一次形(M2c)/ 择强三枚(M2d:aria2 实录强度链相邻对逐对 + 两序同判 / 表外名丢弃同强先现全不认 none / provider 不支持之最强让位次强);port 由测试件 fake 实现——形可被异实现装配)+ adapter 合规罐 3 枚(六算法空串 + abc 标准向量 / 1000 字节图样六切法分块 ≡ 整块跨 64·128 字节块界 / 摘要长度 ≡ 词表;期望值全取 coreutils 实算) | | 多源调度(M2b) | core 罐 8 枚(排序律 priority 升序缺省垫底 + 文档序兜底 / 地点偏好整档前置不分大小写 / scheme 跳过记账含大写 scheme 与无 scheme / 全无可调度源构造期拒 / 降级律达帽出局次优接班成功不回升 / 段 → 源指派满额顺延全满 None 未出局 / 全源出局 / 地点提升单档 aria2 实录 L0–L6 首连逐案 + L3 有意差异) | | gen 链 | 黄金门(skelgen/airgen)一表一罐,五表:regen 原始形 + fmt ≡ 入库产物逐字节——download(满表省兜底臂;状态名投影 §3.10 律 4)/ metalink(非满表照发兜底臂)/ digest_vocab 与 error_code_vocab 与 peer_message_vocab(词表发射器:枚举 + 逐列投影 + 键列反查 + 全集;M2d digest_vocab 增 strength 列 = 纯数据改动;K8a 发射器补整数键列——串键旧表产物逐字节不变) | | BT 片管线与可外发律(K8b) | 金罐 12 枚(core 5 + protocol 2 + sim 5,见 §3.16 律 6;全真校验:判符必真 SHA-1);纯包三后端同数;变异试验证牙(可外发律短路三面齐红) | | bencode + 元信息(K7) | 金罐 12 枚(bencode 六:BEP 3 原文向量 / 二进制安全 + 乱序键保文档序 + Int64 两端 / 正典编码 ≡ 参照实现含原始字节序键 / 往返律正典逐字节复原乱序必变形 / 负例十六例偏移与理由钉死 / 嵌套帽 64 放 65 拒;元信息六:单文件结构 ≡ aria2 -S / 多文件 files·path·announce-list ≡ aria2 -S / info_hash 双 oracle / 禁重编码乱序取原始子串 + aria2 读数 = 本仓重编码哈希 / 结构律负例十五例 + 正对照 / 无 sha-1 能力拒 + info 缺席或非字典拒);纯包四后端同数;变异试验证牙 | | BT 线协议(K8a) | 金罐 7 枚(握手编码 ≡ python 构字节 + aria2 实录回复解码 / 重编码同形;消息编码九种 + keep-alive ≡ python struct.pack 构字节;aria2 实录 217 字节流分帧解出四消息,块内容 ≡ 原文件,重编码 ≡ 原帧;分帧逐字节切碎 ≡ 整块 + 残帧留待;位图编码 ≡ python 构字节 + 尺寸 / 备用位两律拒;负例:握手三拒 + 定长核长 + 字段超 Int32 + 无负载词带负载 + 编码面负字段与错种类 + 表外 ID 保真上交 + 巨帧拒;帧长帽两形);纯包四后端同数;变异试验证牙(备用位律失效 → 位图罐红) | | BT 会话真缝(K8c) | bt 罐 2 枚(oracle 罐:aria2 1.36.0 本机做种 18901 / 吸血 18902,DHT/LPD/PEX 关;下载会话 interested 即发 / 逐块等覆盖位 / 判败回收重下)+ 上传 e2e 方向反转(aria2 出站 MSE-first 降级随机实录——立即关 2/4 / 悬置永不 / 延迟随机;`bt_serve_to` 拨其监听口走入站 plain 位,MSE 不进径)+ 整模 full 驱动 N=3 连绿 + 罐外证落盘字节守恒(python 公式档对拍)+ 变异验证牙(握手 info_hash 产品位翻位 → 双罐同形红,罐骑真线) | | tracker 词面(K9a) | protocol 金罐 10 枚(aria2 实录解析两形逐字段(started / 周期)+ python 参照编码逐字节 + query↔parse round-trip 同形;负例:info_hash/peer_id 恰 20 字节律 / 无 `=` 参数 / 坏 hex / 残缺转义 / failure reason 原文上抛 / peers 字典与整数载荷两拒;RFC 3986 unreserved 字母表 ≡ aria2 实录);纯包四后端同数 + 变异验证牙(端口字节序翻 LE → 金罐逐字节咬中) | | tracker 真缝与群册(K9b/K9c) | protocol 群律罐 2 枚(TrackerSwarm:announce 刷新 / stopped 摘除 / 自身异排 / counts 随 left 翻转)+ bt 回环罐 2 枚(K9b 进程内零外协:首注独行 / 次注相认端点;HTTP 状态非 200 = Malformed。K9c scrape 回环罐口 18914:announce 双侧入册(completed 事件入完成账)→ 在册三域相认 complete=1/incomplete=1/downloaded=1 + 未知 hash 缺席 None + scrapes 计数对账)+ aria2×aria2 经本仓 tracker 相认对传 oracle 驱动 N=3(落盘字节守恒;K8c 直拨对同场复绿)+ 变异验证牙(异排翻面 → 进程内罐红) | | tracker scrape 词面(K9c) | protocol 金罐 5 枚(query 金料双 hash ≡ python urllib.parse.quote 逐字节 + 单 hash 形 + 负例二(零枚 / 19 字节);reply 正典 81B ≡ python bencode 参照(roundtrip 自证,A100 教训)+ 缺席律同序 None 对位 + 请求序翻转对位;failure reason 原文上抛;负例七形全闸:legacy 平面形 / 键短 19B / complete 缺 / complete 型错 / files 与值非 dict / 顶层非 dict;query↔parse round-trip + 裸 query 形 + 未知键忽略)+ 变异验证牙(files 键长律短路 → 键短负例红,复原 grep=0;scrape_url replace 守卫短路 → 推导罐红)+ 推导罐五形(replace 律 /announce→/scrape;查询串尾 / 已 scrape / 非 tracker URL 全 None)+ bt 缝(TrackerFixture scrape 支路:在册三域 downloaded = completed_events 首个消费链,未在册省略键;bt_scrape_http client 全 URL 律)+ 纯包四后端同数(protocol 76) | | 磁力与 metaurl 选拿(M3a) | protocol 罐 5 枚(parse_magnet:xt 恰一 urn:btih / 40 hex 与 32 base32 双形 / dn 百分号解码后到者赢 / tr 保真累计;负例:重复 xt / 坏转义 / 长度越形 / 错 urn 全拒;torrent_metaurl 文档序首个 mediatype=torrent)+ python 参照独立构造 oracle;纯包四后端同数 + 变异验证牙(base32 小写折算翻位 → 小写罐红) | | 混合源真缝(M3b) | bt 罐 2 枚(oracle 罐:metaurl torrent e2e——bencode 正典构造 torrent(info dict ≡ python mktorrent)info_hash 互证先于下载 / 磁力引导回环三源互证(btih ≡ info_hash ≡ tracker 相认端点))+ oracle 台律三笔入册(announce 等信号闸 / 每会话专享 aria2 / metaurl 种死 announce)+ 驱动 N=3 连绿(双对传字节守恒)+ 变异验证牙(URL 拆分偏移翻位 → 取 torrent 位折) | | wget 风格面(W1) | style 罐 5 枚(全旗面金罐含会话两面 / 负例闸含值旗缺值形 / 退出码律 + 错误说明行 / 渲染面 / 缺省输出名;纯包四后端同数)+ run 会话 e2e 罐 1 枚(-i 入档出档 / 末次失败码 / 重载自愈闭环;进程内台;N=2)+ kill -9 真进程续传 e2e(oracle 驱动 N=3:kill 后账存活 + `-c` 续传逐字节一致 + 清盘律 + `-q` 静默与 query 剥缺省名;W1.5 增 moonair --w 同径场景)+ 突变验证牙(退出码律翻转红;会话失败记名短路红)+ wget_demo 判行(`DEMO: PASS` 两轮) | | BT 断电续传(R2) | bt 罐 3 枚(部分数据只补缺双侧铁证 / 坏片让位重取自愈 / fresh 空盘等价;进程内回环,不依赖 aria2 台;N=3 连绿)+ 突变验证牙(复核真校验短路 → 坏片罐红)+ 拨连收尾关连律(bt_download / bt_serve_to 会话毕关 socket,挂死勘定案入 §3.23) | | UDP tracker(U1/U2/U3) | protocol 金罐 6 枚(connect ≡ python 参照 16B / 回包解 connection_id / 错回包文上抛;announce 请求恰 98B 金料逐域 + 对称律 + 负例四(cid 不符 / 97 恰长 / event 表外 / info_hash 短);reply 金料 + peers 相认 + 负例三(跨残 / 异 action / tid 不符);scrape 请求 36B 金料 + 对称律 + 双枚形 + 负例五(零枚 / 短 hash / cid 不符 / 跨残 / 异 action);scrape reply 金料 20B + 对称律 + 双枚形 + 负例四(announce 回包混喂 / 恰长律 / tid 不符 / 错回包上抛);残包守卫罐 8-11 与 12-15 字节拒收不越界)+ bt 回环罐 4 枚(U1/U2:connect 发号 announce 相认 stopped 摘除,罐口 18935;peer B 铁证 peers == [(127.0.0.1, 6881)];scrape 三域相认 + 未知 torrent 全零域,罐口 18936;进程内零外协 N=2。U3:丢包敌手收敛——serve drop_first=1 弃首包 → 缺省策略退避重试收敛 + 墙钟 ≥ 400ms 重试必经铁证,罐口 18944;黑洞弃账——bind 不 serve 三试尽抛 TimeoutError + 墙钟守恒界 1400–6000ms,罐口 18945;aria2-free)+ 突变验证牙(事务核短路 → connect 罐红;scrape reply 异 action 门短路 → 混喂负例红;供面突变 → 真缝罐限时壳 TimeoutError 净红,§3.24 律 6)+ 纯包四后端同数(protocol 57) | | DHT KRPC 地基、路由表与 peer 记账(D1/D2/D3) | protocol 金罐 8 枚(D1:ping 查询 56B / 回包 47B / 错误 42B ≡ python 正典 bencode 参照逐字节,对称律逐域,负例十,事务号 1/4 字节三形往返 + 截尾收口拒;D2:桶位律四落点 + 同 id None / 路由表 LRU 桶 159 家族满 K=8 剔头 + 刷新移尾 + self id 拒 / closest-K 乱序入册 + 反向 target 序断言 + K 截 / compact 26B 金料 + 空表合法 + 负例三 / find_node 两形金料 92B+109B + 对称律 + 负例二)+ bt 回环罐 3 枚(D1:ping 相认 node id 铁证 + 错误回包 203 文上抛,罐口 18937/18938;D2:双 ping 入册 → 异问方 find_node closest 序相认(target 距零者居首铁证),罐口 18939;进程内零外协 N=2)+ 突变验证牙(D1:y 分派短路 → 查询罐红;D2:XOR 序比较短路 → closest 罐红——罐先修咬合力再验牙)+ 金料两罐(D3:peer 记账 store 去重 / get_peers·announce 词面金料 95B+76B+94B+141B+47B ≡ python 参照 + 负例四(values/nodes 双在场 / chunk 跨 / implied_port 表外 / port 越 16 位))+ 回环罐 1 枚(D3:get_peers 空记账 nodes 形 token 发号 → announce token 回呈 implied_port=1 落源口 → 异问方 get_peers values 形相认铁证 → 坏 token 203 文上抛,罐口 18940;N=2;DT 断言升级:token 派生形 79cd1dab + 同 ip 同 secret 两问同值)+ 突变验证牙(D3:token 核发短路 → 坏 token 罐红)+ 纯包四后端同数(protocol 67) | | 元数据交换(M4/M4.5) | protocol 金罐 3 枚(扩展握手 52B/29B ≡ python 参照逐字节 + 对称律 + 负例三(异线 ID / payload 非 dict / size 非正);ut_metadata 三形 30B/57B/30B(协商 ID 21 帧)+ 对称律 + 负例四(协商 ID 不符 / 下界 < 21 / msg_type 表外 / total_size 缺);分片律上取整边界 + 末片截短 + 越尾拒)+ bt 回环罐 2 枚(夹具罐:40000 字节图样 = 16KiB×2 + 末片截短径,握手双向核 → 三片拉齐 → SHA-1 互证 → 字节守恒,罐口 18941;真缝罐 M4.5:生产 bt_serve 同场供块与元数据,metadata~ 在场亮 BEP 9,报告 metadata_served 恰 3 零拒发 + 报告候窗轮询,罐口 18942,两端 hash 同源律勘定案入卷;进程内零外协 N=2)+ 突变验证牙(分片上取整短数 → 分片律罐红;供面牙兑:罐侧 2000ms 限时壳,自报 metadata_size 短 1 → 真缝罐 TimeoutError 净红非挂死,U3)+ 磁力无种子全链罐(M4.6,罐口 18950/18951:magnet→DHT 相认→BEP 9 元数据→装配→下载,单连接共线 bt_download_magnet;突变牙互证翻位红)+ 纯包四后端同数(protocol 70) | | aria2 兼容导入(AC) | protocol 金罐 5 枚(实录 59B 双卷真源域断言:old 卷 inflight chunk 投影 [0..14) / new 卷 pbf 全空投影 [];模板形单 chunk 投影 [0](engine 同源料);BITFIELD piece 完成位 chunk 窗全置 [0,1,2,3];负例四牙:异版 / 结构过短 34 界 / 变长域截断把守 / BT 卷域外拒(INFO HASH 非 0)/ piece 过小拒)+ engine 罐 2 枚(导入罐:aria2 卷在手段 0 置位 → 位图跳段可观测(探长 1 + 段 1,2,3 = 4;fresh 全拉 = 5)字节守恒换装销账;超前位图罐:卷投影 [0,1] 盘面只证段 0 → 位图 ∩ 盘面前缀裁到 [0](不裁 = 中段洞,oracle 真机咬出现实语义))+ oracle 台 `sh driver/oracle_ac.sh`(判行 `ORACLE-AC: PASS`:testsrv 206 源台 → aria2c 限速半程 poll inflight 位非空 kill -9 → 真卷半程 → moonwget `-c` 接续 → sha256 逐字节守恒 + 换装销账 + 外来卷不动)+ 突变验证牙(负例四牙咬域表各面;超前位图裁剪短路 → 中段洞罐红形态由 oracle 台首咬后落罐固定)+ 纯包四后端同数(protocol 83) | | MSE/PE 协议加密(ME) | protocol 金罐 3 枚(DH 模幂 X/Y/S ≡ python 实算 + 对称律 + 常量面(素数全 hex 逐字节钉 / VC 全零);派生四件 keyA/keyB/req1/req2xor3 ≡ 实算(skey = "moonair-mse");ARC4 drop1024 位对拍 + 流续推 + 互逆律)+ bt 回环罐 2 枚(手搓 initiator → bt_serve 真缝全链:X/Y 对拍 / PadA 垫测滑窗 / RC4 全链 BT 会话 / 全档守恒 + mse_accepted 旗,罐口 18952,罐五坑账与印系统病理入 §3.27 律 4;拒径降级罐:异 info_hash → skey mismatch 拒 → 沉默 → 限时壳超时关连 → bt_download plain 重连全链守恒 + mse_accepted==false,罐口 18953,突变牙 skey 错配形与牙验三坑账入 §3.27 律 5)+ 真源勘定案(初版四处词面推翻:素数 group 1 尾 90563 / VC 全零 / 派生式 sha1("keyA/B"‖S‖SKEY) / drop1024;金罐值域盲区律教科书案)+ 纯包四后端同数(protocol 91) | | 门档 | `moon check --deny-warn` 零错零警 + `moon test`(native 全仓 289 罐 = core 39 + digest_mooncry 3 + digest_ossl 3 + sim 27 + protocol 91 + xml_milky 32 + rpc 13 + rpc/server 18 + style 5 + style/run 1 + io 6 + engine 17 + bt 24 + progress 10——读数一律取路径形,不含子包,逐包和 ≡ 全仓;BT-RL 役随行勘陈旧:rpc 基线实数 13 非 14、rpc/server 基线 16 非 15——getVersion 罐笔漏更;纯包 core / digest_mooncry / sim / protocol / xml_milky / rpc / style 于 wasm-gc / wasm / js 各同数(protocol 91/91/91);bt 二十四罐中五罐 oracle 罐由台驱动 `sh driver/oracle_k9.sh` 带台跑(判行 `ORACLE-K9: PASS` = bt 23/23 带台口径含 MSE 罐(拒径罐 24 号为裸罐不入台判) + 吸血侧与 T9 leecher 落盘 SHA-1 ≡ 公式档;台件 driver/mktorrent.py + oracle_k9.sh 入仓,N=3 定稳;台件失传教训:驱动脚本不得落 /tmp 裸奔),裸跑五罐 SKIP 空过(oracle 在场探针 `k9_oracle_listening`:TCP 活探 18901 连上即闭,口闭即退印 `ORACLE-K9-SKIP`;真验仍以带台判行为准,域门子集不依赖台);AC 台 `sh driver/oracle_ac.sh` 判行 `ORACLE-AC: PASS`(aria2 半程 kill → moonair 接续守恒,§3.7 律 5))+ **wasm 腿**(X 役,§3.28:全模块 `moon check --deny-warn --target wasm` 0 错;async 缝包五包 `moon test --target wasm` = rpc/server 15 / bt 24 中 24(五罐同 SKIP 注记;带台真验口径同源)/ engine 17 / io 6 / style/run 1)+ fmt / info; D1 性能役(2026-11-06)续行:native 289/289 + wasm-gc 全仓 213/213 + digest_ossl 罐 3(native/wasm-gc 双腿:provider 分流形,标准向量 + mooncry 同输入同 hex 对拍——stub moonbit_make_bytes 形参误用 bt 三罐 SEGV 后立)+ oracle K9 带台 PASS + D1 终对拍 200MB N=3 = 74-84MB/s(基线 ×17.3);修 A 连接复用续行(TCP connect 14→5 strace 实证;testsrv 源上 74-76 ≈ aria2c 16 连同源 73 同带,python 弱源退化径 ×2.1 = 61→129MB/s N=5;全门 native 289/289 + wasm 213/213 + K9/AC 双台 PASS 后复验);Range 感知续行(无 Range 源单段全量账禁多连退单流,aria2 对位;testsrv no-range 真跑守恒 + strace connect 14→2;罐 +2 = native 291/291 + wasm 213/213 + 双台 PASS 复验)| ## 五、演进承诺(0.x) 同 minor 内 API 兼容;跨 minor 可断(随 CHANGELOG 逐版声明)。迁移表 §3.2 是语义契约——扩事件 / 状态词表 = 改表源 + minor 升版(新增格必须显式给出, 满表不变量随行)。路线(roadmap_review_ming):阶段 1 最小下载核 → 阶段 2 RPC 控制面 → 阶段 2.5 Metalink-HTTP 子集(M-2)→ 阶段 3 BT 子集(含 Metalink 的 BT / 磁力混合源)→ 阶段 4 BT 扩展 → 阶段 5 FFI 边界。 ## 六、血统 aria2 思想与公开 RPC 词表致敬——代码 clean-room 零借鉴(aria2 为 GPL 系许可, 本仓 Apache-2.0,只承接口语义不承实现)。Metalink 依 IETF 公开规范 RFC 5854 实现。分层体例承 moonswim。