# MoonQCOW 只读兼容范围

最终目标是完整读取所选 QCOW2 v2/v3 规范内合法、离线且一致的镜像，覆盖规范允许的特性组合，输出与参考实现一致的逻辑字节。下表记录当前实现与验证范围。

| 镜像特性 | 状态 | 读取行为 |
| --- | --- | --- |
| QCOW2 v2/v3、512 字节至 2 MiB 簇 | 支持 | 校验头部和边界后读取逻辑扇区/字节。 |
| 标准 L1/L2、扩展 L2、显式零簇 | 支持 | 解析活动映射；未分配区段按 backing 规则回退，否则补零。 |
| raw / qcow2 backing 链 | 有条件支持 | 核心 API 由调用方显式提供 backing source；Node CLI 仅在 `--allow-backing` 时跟随镜像路径，并要求格式扩展明确写为 raw 或 qcow2。 |
| DEFLATE 压缩簇 | 支持 | 解压单个 raw DEFLATE 簇，并校验解压长度。 |
| Zstandard（zstd）压缩簇 | 支持 | 仅接受 v3 compression type 标志与类型字段一致的 zstd 镜像；按单簇解压、限制窗口和输出长度，并在簇帧结束处停止，以容忍规范允许的扇区尾部共享。 |
| AES / LUKS | CLI 适配 | 独立镜像由 QEMU 依据显式密钥文件解密到临时 QCOW2，再由 MoonBit 读取和导出。原始快照、位图、物理映射及加密组合仍待补齐。旧式 AES 无密钥认证。 |
| 外部数据文件 | 支持逻辑读取 | CLI 使用 `--external-data`，库使用 `open_source(..., external_data=...)`。数据与元数据分开访问。外置数据不纳入元数据文件引用计数。引用反查和精确引用计数重建暂不开放。 |
| dirty、corrupt 或未知不兼容特性位 | 不支持 | 拒绝读取，不尝试修复或忽略状态。 |
| 未知压缩类型、压缩数据损坏或解压尺寸不符 | 不支持 / 无效镜像 | 未知类型返回 `Unsupported`；损坏帧或尺寸不符返回格式错误，不输出补零替代内容。 |
| 内部快照 | 支持 | 可枚举并按快照 ID 读取客户机虚拟磁盘内容；快照保存的 VM 运行状态不作为磁盘字节读取。 |

## 场景处理

- **普通或 DEFLATE 镜像：**直接读取或使用 CLI 导出；数据与 QEMU 导出的 RAW 结果做逐字节对照。
- **zstd 镜像：**支持标准 v3 zstd 压缩簇，互操作测试使用 QEMU 生成镜像，并逐字节比较读取/导出结果。
- **含 backing 文件的差分镜像：**库调用者必须显式传入 backing source；Node CLI 需要 `--allow-backing`。缺文件、链循环、格式未声明或深度超限时返回错误；只有合法 backing 文件短于虚拟磁盘的尾部按 QCOW2 规则补零。
- **加密与外部数据镜像：**下方命令用于可信的本地离线镜像。加密适配会在临时目录写入明文副本，需要足够空间及合适的目录访问权限。
- **活动中或损坏镜像：**dirty/corrupt 标记会被拒绝；请先停止写入镜像，并由 QEMU 工具完成一致性检查或修复后再读取。

资源上限（簇大小、读取块、链深度、扫描数量等）由 `Limits` 控制。达到上限时操作失败，不会截断数据并冒充成功。该兼容声明是只读功能范围，不代表写入、修复或与所有 QCOW2 特性完全一致。

## 复审案例

先运行 `moon build --target js --release`。在安装 QEMU 和 Node.js 的环境运行下列命令。脚本生成两种外部数据模式及 AES、LUKS 镜像，读取非对齐区间，导出 RAW 并逐字节对照。

```sh
python scripts/interop.py --report reports/interop-local.json
```

已有镜像可按以下步骤复现。每次输出须使用新文件。

```sh
node _build/js/release/build/cmd/main/main.js read meta.qcow2 4093 8199 slice.raw --external-data disk.data
node _build/js/release/build/cmd/main/main.js export-raw meta.qcow2 out.raw --external-data disk.data
python scripts/encrypted.py encrypted.qcow2 --key-file key.txt read 4093 8199 enc-slice.raw
python scripts/encrypted.py encrypted.qcow2 --key-file key.txt export-raw enc-out.raw
```
