# moonnat spec —— 结构事实与契约

版本:**v0.1**(2026-10-28 立卷,骨架期)
定位:NAT 画像与打洞编排纯核的**结构事实与契约**卷。纪律底卷 =
[const.md](const.md)(必须/禁止句式);本卷记协议事实、形状与验收门。

## 一、范围

### 做

- **STUN 报文编解码**:RFC 8489 报文头(20B:类型‖长度‖magic
  0x2112A442‖事务 id 96b)+ 属性 TLV(类型 u16‖长度 u16‖值‖4B 对齐
  垫),XOR-MAPPED-ADDRESS 编解码;已知答案向量对拍即门。`[骨架]`
- **画像机**:双服务器对照 + 端口变化探测 → nat 画像
  (Endpoint-Independent/Dependent,端口预测基料);决策面纯函数。`[骨架]`
- **地址观测**:观测源优先序接口(home relay 回执 > STUN > 对端
  observedAddr > UPnP/PCP 后置);观测以带外回执/应答/dial-back 实测
  为据,自报不作决策输入。`[骨架]`
- **打洞编排**:纯函数 reducer(state × event → action),nonce 防混淆
  + dial-back 防谎报;重试节奏与端口预测策略可配。`[已落]`
- **探针口 port**:`pub(open) trait ProbeSocket`(send_to / recv_from
  async、now_ms sync,形随 vox1000 SeamNet;单真变点,宪法律 1.4)。
  `[骨架]`
- **STUN Binding 事务**:发 Binding Request → 截止窗内收应答 → 事务
  id 核对 → XOR-MAPPED 出 BindingView;异事务/非 STUN 报文静默弃续等。
  `[骨架]`
- **NatPump 驱动器(adapter 方言)**:moongard 管道对位——拥有探针口
  + 策略 + 熵接线,驱动 reducer 环;三回调槽(on_picture 可 no-go /
  on_established / on_abandoned)全 `?` 沉没(None = 吞流,D-G11 形);
  wire 约定 = 打洞/回连包载荷为 nonce 裸载荷(对端回声即原样重发)。
  `[骨架]`

### 暂不做

- UPnP/PCP(v1 外,后置)。
- TURN(RFC 5766 中继——relay 归 moonrelay 件,不在此卷)。
- 任何默认 STUN/relay 服务器名单(剥离纪律,配置注入)。
- ICE/SDP 全家桶——只取探测与打洞编排,不背信令框架。

## 二、形状锚

- **探针口**:核心自备最小缝口(send / recv / now_ms),消费方
  (vox1000 T4.1)以 adapter 桥接其 SeamNet——本件不反向知晓消费方
  词汇(律 3.3)。
- **错误面**:`ProbeError = pub(all) suberror`,型随役扩。
- **时间/熵**:一律注入口(`now : Int64` 毫秒;nonce 种子注入)——
  核心零钟零随机,全决策可 sim 回放。

## 三、API 面(两层,各有主顾)

- **核心层**:纯函数库 + reducer(stun_encode/decode、nat_picture_of、
  punch_next)——vox1000 T5 桥接在此层接入(punch_next + ProbeSocket)。
- **adapter 层**:NatPump 驱动器回调方言——独立用户/示例用,全程不触
  reducer。核心永不拥有事件环(纯核律 1.1)。

## 四、验收门

| 面 | 门 |
|---|---|
| STUN 编解码 | RFC 8489 已知答案向量逐字节对拍 |
| 画像/打洞决策 | 纯函数全分支单测 + sim 回放罐 |
| 真网络 | 真机黄金门(候部署环境,挂账) |

## 五、演进承诺(0.x)

同 minor 内 API 兼容(核心纯函数签名 + ProbeSocket port 面);跨
minor 可断(随 CHANGELOG 逐版声明)。STUN 线型属 RFC 8489 标准遵循
层,不随本仓版本演进;打洞 wire(nonce 裸载荷回声)0.x 内不动,
1.0 起再议长期承诺。

## 六、血统

Tailscale netcheck 思想 / iroh autonat v2 纪律 / RustDesk punch 编排
思想——思想与编排参考,实现与线全自研(clean-room,Apache-2.0)。