# 支持范围与使用约定

MoonMCAP 的核心目标是可靠读写、查询和处理 MCAP 0 消息日志。
选取入口时先看文件布局、需要的校验强度和输出大小，而不是默认启用所有适配器。

| 层次 | 实现与环境 | 交付边界 |
| --- | --- | --- |
| 容器核心 | 根包，MoonBit，Wasm/JS | MCAP 0 标准记录、CRC、索引、无压缩/LZ4/Zstd、查询和变换；[精确格式范围](compatibility.md) |
| 文件与网络宿主 | nodeio、asyncio，JS/Node.js 22.3+ | 本地文件、HTTP Range、持久任务、工作线程；Wasm 核心并不直接提供这些宿主能力 |
| 消息解释 | MoonBit 可选解码器 | JSON、FileDescriptorSet Protobuf、ROS1 与 plain XCDR1 的文档化子集；未知消息仍可保留原始字节 |
| 外部适配器 | Python；按需安装 PyArrow 或 Foxglove SDK | 列式导出、实验回归、配方、设备信封桥接；不是纯 MoonBit 原生 Arrow/Parquet 或通用设备驱动 |

## 校验承诺

快速索引查询只核对摘要及实际读取的块，**不是整份文件已验证**。
需要审核全文件时使用 `cmd/mcap validate` 或查询的 `--full`。
不同入口的完整扫描预算见 [CLI](cli.md)、[RangeReader](range-reader.md) 和
[大文件诊断](source-diagnostics.md)。部分恢复、增长文件前缀、清单封装检查
都不能冒充完整容器检查。CRC 字段为零表示未提供校验值，不声称已验证该 CRC。

输入视为不可变快照；本地宿主通过文件身份、大小和修改时间拒绝可检测的变化，
内容绑定的索引/任务另用 SHA-256 核对。它们不是带签名的来源证明，也不保证
读取正在被其他进程改写的文件时能得到一致结果。

## 大小、排序与时间

- 默认 `query`/`slice` 限量 100000 条，`offset`/`limit` 作用于查询整体；必须显式
  设置需要的数量。处理完整大输出应选择流式入口，而非把交互查询结果当作全量导出。
- 内存 `read_log`、普通 CLI slice/merge 等需要载入文件；默认编码输入预算 64 MiB。
  外部排序、流式片段和按记录诊断有各自的预算，并不承诺任意大文件或固定进程 RSS。
- 时间为 UInt64 纳秒，区间包含两端；JSON 时间以十进制字符串保留。log/publish/header
  是不同的时钟；同步和回归只按显式选择及校正规则比较，不推断真实设备时钟精度。
- 不保证变换后文件字节与原文件相同。索引与压缩布局可重建；payload 原字节保留与
  显式字段回写是不同操作。未知记录和附加字段的保留限制见格式与变换文档。

## 输出与恢复

文件输出要求新路径及已存在的父目录，通过同目录临时文件、同步和硬链接独占发布。
文件系统须支持这种操作；已有目标不覆盖。硬链接是提交点；其后的清理失败会返回 `output published`，完整目标可能已经存在，重试前须先核对；详见 [架构与所有权](architecture.md)。标准输出无法回滚，流式输出失败前
可能已写出部分行，调用方必须检查退出码；需要原子结果时使用 `--output`。

恢复只复用经校验的已提交状态。缓冲中已接受消息与持久提交消息不同，调用方
须按对应录制协议重发未提交部分。进程终止测试不能替代断电或存储硬件故障保证，
本地文件原子发布也不等于多个系统之间的事务。

## 已验证与尚未验证

合成数据覆盖精确边界、异常布局和故障注入；公开机械臂录制用于核对真实容器及
消息，驾驶数据由 ROS bag 转换，来源和转换语义分别标记，见 [公开语料](corpus-validation.md)。
百万消息与超过 2 GiB 的历史观测只证明报告中的布局与环境，见 [实测边界](performance.md)。
设备桥接已验证真实 SDK 本机订阅与 MCAP 读回，尚未联调实体设备或操作 Foxglove 桌面界面。
不提供 ROS 网络发现、硬件驱动、XCDR2、通用 schema 协商或数据库事务承诺。

## 平台验收边界

固定工具链的源码验证覆盖 Linux、Windows 和 macOS 15 Apple Silicon / ARM64，具体以目标提交的 CI 为准。Intel macOS 不在本轮已验证源码平台中：官方安装器在 2026-10-31 的 Intel runner 上报 `Unsupported platform: Darwin x86_64`，未进入项目构建。此限制不被描述成库测试已通过，也不据此推断所有其他工具链或生成 JS 在 Intel 上均不可用。