# MoonBind 1.0 使用与交付边界

1.0 将生成器、版本化配置、可审查升级和一个三库应用组成完整交付流程。原生功能需要 Python 3.10+、MoonBit、平台 C11 编译环境；Windows 使用 MSVC Build Tools 和 Windows SDK。

GitHub/CLI 版本是 **1.0.0**，Mooncakes 安装使用 `moon add icyaaaww/moonbind@0.10.0`。2026-10-23 发布校验时，注册表服务端返回只允许 `0.x.y`，因此包元数据保留主版本 0；两者为同一交付，映射记录在 `release-version.json`。

## 安装和诊断

从 GitHub 的源码 ZIP 解压，或克隆仓库后执行：

```sh
moon update
python moonbind.py install --prefix ../moonbind-install
```

将输出的 `bin` 目录加入 PATH。版本化源码复制到 `moonbind-install/moonbind-1.0.0`，启动器指向该副本；原仓库移动不影响安装。安装仍需要 Python 和 MoonBit，不是单文件原生可执行程序。已有版本目录拒绝覆盖。也可以保留 `install --bin DIR` 的开发启动器用法，它依赖原仓库路径。

```sh
python moonbind.py init ../example --recipe zstd
python moonbind.py doctor ../example
python moonbind.py validate ../example
```

doctor 的 JSON 包含工具路径、探针结果、问题定位和修复建议。完整验证报告在项目 `reports` 下。安装和验证依赖正常网络下载编译器、包和配方源。

## 0.9 迁移与升级保护

已有无版本配置继续按 schema 1 解释；新建配置含 `schema_version: 1`。编辑器结构描述见 `schemas/binding.schema.json`；契约语义由生成器继续校验。

```sh
python moonbind.py migrate ../example
python moonbind.py migrate ../example --apply
python moonbind.py upgrade ../example --against old-header.h
python moonbind.py upgrade-apply ../example
python moonbind.py upgrade-apply ../example --apply
python moonbind.py generate ../example
python moonbind.py validate ../example
```

默认只预览。应用前验证候选配置并备份原始字节到 `reports/config-backup-*.json`；报告过期、旧值不符、契约无效时拒绝。仅应用参数名称更新等受限配置建议；调用语义、内存生命周期和 ABI 变化仍需开发者审查。修改配置后主动重新生成和验证，不自动修改用户生成代码。

## 可运行应用：本地目录快照

这是一套命令行参考应用，SQLite 管理快照索引，Zstandard 压缩对象，cJSON 解析与规范化清单。三库调用通过 MoonBind 生成的 MoonBit FFI 执行。Python 负责路径遍历、SHA-256、暂存和发布目录，未用 Python sqlite/zstd 包替代三库调用。

SQLite 的 `SQLITE_TRANSIENT` 与简化 prepare/exec 接口使用仓库现有的手写 `templates/sqlite/adapter.{h,c}`；适配器上层绑定由生成器生成。该部分不是自动推断的库语义。

```sh
python tools/snapshot.py --engine ../snapshot-engine build
python tools/snapshot.py --engine ../snapshot-engine init ../snapshot-store
python tools/snapshot.py --engine ../snapshot-engine save ../snapshot-store ../my-documents --id first
python tools/snapshot.py --engine ../snapshot-engine list ../snapshot-store
# 修改 my-documents 中的文件之后：
python tools/snapshot.py --engine ../snapshot-engine save ../snapshot-store ../my-documents --id second
python tools/snapshot.py --engine ../snapshot-engine diff ../snapshot-store first second
python tools/snapshot.py --engine ../snapshot-engine export ../snapshot-store first ../first.json
python tools/snapshot.py --engine ../snapshot-engine restore ../snapshot-store first ../restored-documents
```

保存时按内容摘要去重，每个新压缩对象先解压验证；复用对象也验证。重复 ID 拒绝覆盖。恢复到新目录，全部文件摘要验证通过后才公布结果；已有目标不覆盖。export 导出清单，**不是包含内容对象的独立备份包**，迁移备份需要一起复制整个 store。

限制与恢复方式：

- 单文件最多 16 MiB，总量最多 256 MiB，文件与目录合计最多 10,000 项；整体读入单文件，不是流式备份。
- 支持普通文件和空目录，拒绝符号链接、junction、跨平台不兼容名称、大小写冲突；不保留权限、时间戳或链接。
- 源目录需保持静止；检查读取前后元数据，但不是文件系统原子快照。
- 存储位置与源、恢复目录分开。失败保存可能留下未引用对象，暂不提供自动垃圾回收。
- `.snapshot.lock` 防止本工具并发操作；崩溃后先确认没有进程在使用，再人工删除锁文件。不是面向不可信并发进程的文件系统沙箱，也不承诺断电持久性。
- 原生 helper 是内部实现；用户通过 Python 命令进入容量、路径、锁与摘要检查。

## 多库组合与兼容性

多个生成包链接同一程序时，为每个包设置不同 `c_namespace`，例如 `snapshot_sql`、`snapshot_z`、`snapshot_cj`。它隔离公共 C 辅助符号，保留 MoonBit API 名称。上游导出的 `moonbind_` 前缀被保留；同一 C 库重复编译、任意库间上游符号冲突不在支持范围内。

1.x 稳定承诺覆盖文档中的 CLI 命令、schema 1 配置语义、生成包装器的契约语义，以及 `compat/1.0` 中登记的 MoonBit 公共接口。兼容修复不得悄悄删改这些接口；有破坏性的变更进入 2.0。AST 等公开模型新增枚举项可能影响穷尽匹配，因此也按破坏性变更审查。内部实现、报告附加字段、诊断措辞、生成源码排版及参考应用的内部 helper 不承诺字节不变。

从 0.9 手工构造 `@cli.Options` 的调用者需新增 `c_namespace: ""`；通过 `parse_args` / `config_args` 的调用者无须修改。1.0 是稳定基线起点。

## 验证与发布

- `moon test`：核心语义回归；`scripts/verify-v1.py`：迁移、备份、安装、真实三库应用及失败保护。
- `scripts/verify-parser-corpus.py`：54 个有超时边界的固定异常/变异输入；不是完整模糊测试。
- 旧版本原生集成套件继续运行。已有 ASan/UBSan 检查覆盖生成的 C record bridge；不代表所有 MoonBit 包装器或全部上游库都经过 sanitizer，也不构成完整内存安全保证。
- 发布工具链在 `toolchain.json` 固定，Windows/Linux/macOS 运行验收；另设 latest 编译器兼容任务。
- `scripts/package-release.py` 从干净的 Git 提交制作固定 ZIP 元数据的源码包和逐文件 SHA-256 清单；可重复的是源码归档，不声称不同平台原生二进制逐位一致。

独立开发者试用仍待执行，记录模板在 `docs/user-trial-v1.md`。正式版本号表示此支持范围内的发布承诺，不能替代真实用户验证。