#MoonJMAP

#给评审的功能主线

1. JMAP 邮件前缀一致性（核心）：分别追踪 Email/changes 的对象属性历史和 Email/queryChanges 的查询顺序历史；处理成员移动、属性变化、删除后的同状态补位、历史失效和旧响应；只有前缀、对象属性和两条 state 链都满足契约时才报告 Ready。
2. 邮件查询决策证书（核心扩展）：从一次接纳结果生成领域专用证书，按最终前缀位置记录旧位置引用或新进入 ID，离线验证 after 前缀、state 边界、generation 和结果分类。证书不携带实际邮件字段，不能独立复核对象载荷来源。
3. 恢复和资源边界（内部支撑）：checkpoint、generation fence、max_changes、Pending/NeedsRefresh、typed response bridge 只用于保证上面两项的安全性，不单独构成产品卖点。
4. 测试和交付工具（证据，不是产品功能）：Python wire 容器、独立 oracle、MoonBit/Python 对拍、synthetic trace、指标脚本和源代码归档用于证明核心行为；它们不应被介绍成通用 RPC、通用 replay、通用日志、通用性能平台或通用发布系统。

#相似能力如何处理

当前仓库按 v0.1 规划收敛。真实服务实现互操作和性能必须以脱敏外部证据为准，不能由本地单元测试替代；本次已补充 Stalwart v0.16.27 真实实现的本机部署记录，托管邮箱服务仍需单独授权。

#当前差异化重构

• Email/queryChanges 以服务端给出的最终排名归并旧前缀存活项和新增项，直接生成可证明的连续前缀；未知排名仍要求刷新。
• 前缀证书改用位置引用，删除通用 remove/add 编辑脚本；查询和请求绑定改用结构化字段，删除 FNV 与摘要判定。
• 邮件对象变化只接受 RFC created/updated/destroyed/has_more_changes 模型，移除早期 ChangesData 两数组兼容入口。

#代码边界

#安装与使用

moon add 001-Elsa/moonjmap@0.1.0

import {
  "001-Elsa/moonjmap/src/email" @email,
  "001-Elsa/moonjmap/src/sync" @sync,
}

test "open a bounded mail view" {
  let account : @sync.AccountScope = {
    service_identity: "https://jmap.example.test",
    account_id: "account-1",
  }
  let view = @sync.open_view(
    account,
    @email.ViewSpec::Latest("inbox"),
    @sync.default_limits(),
    Some("email-state-0"),
  )
  let next = @sync.plan(view)
  assert_eq(next.requests.length(), 1)
  assert_true(next.requests[0].kind == @sync.RequestKind::Query)
}

#快速查看

python3 examples/replay_vectors.py
python3 examples/codec_roundtrip.py
PYTHONPATH=src python3 -m unittest discover -s tests -p 'test*.py'
moon check --target native
moon check --target js
moon check --target wasm-gc
moon test --target wasm-gc

#设计承诺

• AccountScope、QueryKey、EmailProgress 和 QueryProgress 分开绑定；token 不跨账号、查询或状态类型复用。
• Ready 只在有界前缀和所需对象属性已齐备、两条状态链无待追赶工作时返回。
• 删除前缀成员后按同一个 queryState 补位；补位返回不同状态时转为重建。
• 历史失效只使对应状态链失效，不能把另一条链的进度一起推进。
• 请求代次、预算和响应结构检查在提交 checkpoint 之前生效；旧响应不能覆盖新查询。 checked_next_generation 拒绝负值和 @int.MAX_VALUE，避免 refresh/resume 的 generation 回绕；旧 API 在这个边界返回协议失败视图和空计划。
• Email/changes 分页按 Limits.max_changes 设定累计条目上限；每页请求携带剩余 maxChanges，changes_seen 随 checkpoint 持久化，预算耗尽保持 Pending 而不跳过 未消费的历史。

固定 JMAP query 视图
  + Email/changes（对象属性 frontier）
  + Email/queryChanges（有序查询 frontier）
  -> 最终排名归并与同-state 前缀补位
  -> 需要时受控重建
  -> Ready 的有序前缀 + JmapEmailPrefixCertificate

• 支持矩阵
• 状态和 checkpoint 契约
• 恢复、预算和旧响应处理
• 可追溯同步 trace 格式
• 邮件查询决策证书与纯 MoonBit 验证器
• 合成视图指标与预算基准
• 向量和演示验收报告
• 真实服务互操作与性能验证报告
• 外部事项完成度与 31 个公开赛事候选审计
• 真实服务互操作记录模板
• 本地发布检查清单

#本地源代码包

python3 scripts/build_source_archive.py --output-dir dist
python3 scripts/release_smoke_test.py dist/moonjmap-0.1.0-src.tar.gz
python3 scripts/release_smoke_test.py dist/moonjmap-0.1.0-src.zip

#证据边界