# MAT Level 5 最终读写范围与验收终点

更新：2026-10-17，v0.0.9。用于纠正 v0.0.2 申报材料将 cell、struct、char、sparse 列为范围外的问题。该旧边界不再代表项目目标。当前实现与最终验收分开记录，测试通过不代表主办方复审通过。

## 最终范围

项目以 **MAT Level 5 公开格式定义的全部基本数据类（class 1–15）均可读取、构造与写回** 为 v1.0 终点，包含混合文件和任意受资源限制的递归组合。cell、struct、char 与 sparse 都属于必交范围。写入以合法、确定性的小端 Level 5 为标准输出；读取兼容大小端和压缩/未压缩。兼容指数据类型、维度、字段顺序、嵌套关系及有效数据保持，不要求原文件逐字节复制。

| 基本类 | 最终读写范围 | v0.0.9 实现 |
| --- | --- | --- |
| 1 cell | 多维、空数组、异构递归元素 | 已实现 |
| 2 struct | 标量/多维数组、字段表、空结构、嵌套值、列优先元素与字段顺序 | 已实现 |
| 3 legacy object | 类名、形状、字段与递归值的数据级读写 | 已实现；不执行 MATLAB 类 |
| 4 char | 字符矩阵、空字符、中文、非 BMP；miINT8/UINT8/UINT16/UTF8/UTF16/UTF32 | 已实现；保留编码及原始单位，详见下文 |
| 5 sparse | 二维 CSC double、logical、complex double；索引、容量与稀疏存储 | 已实现规范 CSC；乱序/重复索引仍显式拒绝 |
| 6–15 numeric | double/single、int/uint 8/16/32/64、logical 标记、浮点复数、多维/空数组 | 已实现 |

所有基本类均需支持全局标记、小数据标签和标准标签、容器内匿名矩阵、文件级压缩，以及共享的文件/元素/深度/节点限额。原有数值互操作功能继续保留：NPY、可读 JSON、数值变换、数值/CSC 快照和精确 diff。这些接口的输入域不会自动扩大为任意混合树。

## 可检验的完成条件

1. 每个基本类都有独立工具产生的读取案例，以及独立工具成功消费 MoonBit 输出的写入案例；全部类同时出现在混合文件中，至少覆盖 cell→struct→cell 和 struct→cell→sparse 等交叉嵌套。
2. 按大小端、压缩、空数组、多维、字段顺序、UTF 编码、全局标记和资源异常建立逐项矩阵；JS、wasm-gc、native 三目标测试通过。独立验证不能只用本库自读自写。
3. 给出可下载混合文件、生成器、校验值、运行命令和真实验证报告。数值同存储类型保留原始 IEEE 字节与精确整数；字符保留编码及规范化为小端的存储单位。
4. 补充 MATLAB 或 GNU Octave 的实际生产/消费回执。对工具之间字符维度或 legacy object 行为不同的案例逐项记录，不能以 SciPy 结果替代 MATLAB 实测。
5. 处理真实标准文件暴露的问题，并更新公开兼容矩阵。任何尚未完成项都保留“未验证/未完成”，未达门槛前不宣称完整兼容终点已经实现。

## 交付计划

| 日期 | 交付与验收 |
| --- | --- |
| 10 月 16 日，v0.0.5 | 补齐递归 cell/struct/char/legacy object，发布混合案例和独立往返报告，替换旧范围说明 |
| 10 月 20 日前 | 扩大基本类×编码×空/多维×压缩组合矩阵，补充畸形字段、截断和递归预算用例 |
| 10 月 24 日前 | 补充 MATLAB/Octave 实际回执；复核 UTF16 代理项/维度、legacy object 和 CSC 标准文件差异；工具不可用时明确列为未完成项 |
| 10 月 28 日目标，v1.0 | 满足上述全部验收条件后发布兼容终点版本及可复现报告；否则公开剩余问题与修正计划，不用版本号替代验收 |
| 10 月 31 日前 | 参赛者依据实际完成情况更新报名表并申请复审，保留正式提交回执 |

各小版本的范围、性能基准与时间不足时的取舍见 [v0.0.6—v0.0.9 更新计划](NEXT_RELEASES.md)。上述完整兼容终点不因性能优化或新增工作流而缩减。

## 当前限制与格式边界

UTF8 数组以 Unicode scalar 数计维度，遵循本版独立 SciPy 案例；UINT16/UTF16 保存 16 位单位（包括代理项），UTF32 保存合法 scalar。非 BMP 字符在不同生产工具中的维度差异尚需 MATLAB 实测，当前不宣称跨工具所有 Unicode 变体已经验证。

当前 CSC 只接受每列行索引严格递增的规范表示；不会静默合并重复值或重排行。此限制及旧编码名称文件将在终点矩阵中显式跟踪；不把“拒绝输入”计为已兼容。读取只接受 UTF-8 名称，根变量名非空；容器内空名可保留。文件描述、大小端和压缩布局在写回时规范化。

MAT v4 与 HDF5 MAT v7.3 属于不同格式，不属于 Level 5 终点。MATLAB 私有运行时扩展（function handle、mxOPAQUE/MCOS、子系统 workspace）也不等同于公开基本类；当前明确返回错误。若赛事要求这些扩展，也将列为额外交付项并取得真实案例，不能声称“支持所有 MATLAB 对象”。legacy mxOBJECT 基本类的数据级支持不代表能够执行 MATLAB 对象。流式 I/O 与 NPY object/pickle 不属于此 Level 5 读写兼容目标。

首组证据：[混合文件及复现步骤](../examples/mixed/README.md)、[接口与限制](API.md)、[独立验证源码](../scripts/interop.py)、[验证报告目录](../verification/reports)。格式行为参考 [SciPy 1.15.3 Level 5 读写源码](https://github.com/scipy/scipy/tree/v1.15.3/scipy/io/matlab)。