# moonsbe 的 SBE 1.0 兼容范围

## 最终交付目标

本次拟完整支持 FIX Trading Community 发布的 **SBE 1.0 Final（2020 年 11 月勘误版）**。验收范围涵盖规范第 4–7 章适用于 SBE 消息库的要求，以及 1.0 XSD 所定义的消息 Schema。调用者可用既有标准 XML 编译消息布局并生成 MoonBit 类型，和对端交换相同字段及字节。传输层使用调用方给定的消息边界，字符集以 Schema 声明为准。

| 验收范围 | 判定方法 |
| --- | --- |
| 第 4 章的字段编码 | 对每种标准类型、常量和缺失值提供正反例。用参考实现对照零长度、最小值、最大值和越界值。 |
| 第 5–6 章的报文和 Schema | 原始 XML 经官方 1.0 XSD 验证后直接导入。覆盖头部、偏移与填充、重复组、变长区、复合类型及字节序，同时编译生成的 MoonBit 接口。 |
| 第 7 章的兼容演进 | 用同一业务 Schema 的不同版本对照读写。对规范允许的新增字段和安全跳过条件逐项测试，完整核对已知字段和读取边界。 |

当前 0.2.1 的实测结果与待完成项见下文。测试固定使用 FIX 一致性套件和 `sbe-all 1.35.0`。项目版本、工具版本和 Schema 内的业务版本分别管理。

## 支持矩阵

| 范围 | 0.2.1 行为 |
| --- | --- |
| 消息头 | 按 `headerType` 解析四个必填无符号成员的宽度和偏移，支持显式填充及 `numGroups`、`numVarDataFields` 扩展计数。保留常用的 8 字节布局 |
| 字节序 | littleEndian 与 bigEndian，同时用于头部和消息体 |
| 整数 | `int8/16/32/64`、`uint8/16/32/64`，保留完整 64 位精度 |
| 浮点 | float32 与 float64，按 IEEE 位表示读写，有限数值与可选空值 |
| 字符 | 单字节可打印 ASCII char、定长字符数组、ASCII、UTF-8、UTF-16、UTF-16BE、UTF-16LE 文本。UTF-16 的 BOM 和字符串内部字节序独立于消息字节序 |
| 数组 | 定长基础类型数组，检查元素数与数值范围 |
| 常量 | constant 基础类型、复合类型内常量、枚举 `valueRef` |
| 枚举和集合 | 枚举名与值映射、位选择集合、已知值和 `sinceVersion` 校验 |
| 复合类型 | 内联类型、`ref`、显式 offset 和成员 `sinceVersion`。按消息版本访问有效成员，保留已声明偏移 |
| 必填和可选 | 标量支持标准或自定义 `nullValue`。可选复合字段以首个固定标量的空值表示整体缺失 |
| 数值约束 | minValue、maxValue、nullValue 的物理位宽与运行时范围检查 |
| 重复组 | 按 `dimensionType` 编译 `blockLength` 与 `numInGroup` 的宽度、偏移和范围，支持嵌套组及两种扩展计数 |
| 变长数据 | 无符号 uint8/16/32 长度前缀和 char/uint8 数据，允许 `data` 与 `varData` 载荷名，检查 maxValue |
| XML 资源 | 调用方提供内容的 types-root XInclude，保留官方 Car 示例结构 |
| 版本 | 按 acting version 跳过未来字段，按 acting blockLength 跳过已知块末尾的新增固定字段 |
| 生成代码 | MoonBit 记录、枚举和编解码适配器。对根块的定长整数、浮点及数值数组生成直接访问接口，固化偏移、宽度、字节序和版本条件 |

## 本版行为及后续标准用例

- 头部与组维度支持表中的标准成员和 `UInt8/16/32/64` 线宽，解析后的长度、标识和计数受运行时整数及消息资源边界约束。扩展计数须与当前已知的消息布局一致。
- 可选数组和可选位集合返回不支持错误。可选复合字段的第一个成员须为非恒量且无版本门槛的固定标量。复合成员的版本控制保留编译时偏移，修改已有偏移或类型仍会被兼容性检查标记。
- 内置字符集见上表。其他 `characterEncoding` 声明，以及变长长度前缀的 minValue 约束，列入字段编码复核。对标准有定义的可选数组、位集合和复合缺失规则，补齐对应的 Schema 和线值测试。
- 枚举未知值和未知集合位按严格模式拒绝。旧 Schema 遇到新增可变字段可能存在无法跳过的字节，完整消息检查会返回错误。
- 定长字符数组使用末尾零填充，文本中的内嵌 NUL 会被拒绝。UTF-16 只按完整代码单元读取，字符串中字符自身的字节 `00` 不会被误作结束符。
- XML 读取器服务于此 Schema 范围，实施相关语法、布局与约束检查。完整 SBE XSD 合规验证可在宿主系统调用独立标准工具执行。
- DTD、外部实体、XPointer、XInclude 文本模式和任意网络资源加载返回不支持错误。XML 命名空间支持官方示例使用的 SBE Schema 形式。
- 生成的 `view` 校验消息身份、固定块范围、所读字段的版本与访问边界，并直接读取原始字节。整条消息的编解码、值域校验及变长区遍历由共享运行时完成。单字段读取测量见 [互通与性能记录](interoperability.md)。
- CLI 使用 Node.js 文件接口，库的二进制与 Schema 逻辑可由其他包直接调用。

## 资源边界

| 资源 | 默认上限 |
| --- | ---: |
| 一条消息字节数 | 16 MiB |
| Schema XML 长度 | 2,000,000 UTF-16 code units |
| XML 节点数 | 20,000 |
| XML 嵌套深度 | 64 |
| 类型引用深度 | 64 |
| 重复组深度 | 32 |
| 解码累计组项数 | 100,000，可通过参数在支持范围内调整 |
| XInclude 深度 | 16 |

`decode` 要求完整消息边界，先检查范围后读取，每项分配前检查共享数量预算。`compare_schemas` 提供保守的兼容性风险清单，报告描述本运行时的严格解码行为。

0.2.0 的 `Schema`、`GroupDef` 和 `CompositeMember` 记录新增布局或版本字段。使用 `parse_schema` 的调用方可继续走原有入口，手动构造记录的调用方需提供新增字段。

现有版本已验证官方原始 Schema 的三个请求用例和旧读新、标准 UTF-16 示例及空文本。进一步验收需逐项覆盖上表和官方套件的响应场景。[复现命令与结果](interoperability.md)

## 对照来源

- [SBE 1.0 with Errata November 2020](https://www.fixtrading.org/wp-content/uploads/download-manager-files/Simple_Binary_Encoding_V1.0_with_Errata_November_2020.pdf)
- [FIX SBE 1.0 XSD](https://github.com/FIXTradingCommunity/fix-simple-binary-encoding/blob/418a8f6a8b93c65b308638dab2bc6a35dddcd864/v1-0-STANDARD/resources/sbe.xsd)
- [FIX 官方一致性套件](https://github.com/FIXTradingCommunity/fix-sbe-conformance/tree/2d6ea262187acd0802adcc3060fb41a80daf1526)
- [参考实现标签 1.35.0](https://github.com/aeron-io/simple-binary-encoding/tree/1.35.0)
- [本项目固定的上游文件与 JAR 校验值](https://github.com/liyun6666/moonsbe/blob/main/interop/UPSTREAM.md)
