2026-06-26 MD-H1-03 租约

用户目标

从 /Users/ar/Projects/ExcalidrawX/02-P/plan-progress.markdown 的 P-20260626-m4c-handshake-coordination 领取 Mindraw 侧 MD-H1-03，完成 Phase 3.8 External Write API / Document Lease 的 lease manager 垂直切片。

边界：

• 只做 lease / revision / 并发 / 过期拒绝。
• 不做任意 JSON patch。
• 不写文件保存。
• 不覆盖 source Frame。
• 不启动 createAiResultFrame mutation。
• 不领取 PM-* 或 H*。

已完成事项

• 新增 in-memory document lease manager。
• 支持 mindrawAcquireWriteLease()、mindrawReleaseWriteLease()、mindrawPeekWriteLease()。
• 覆盖短 TTL、60 秒 TTL clamp、过期清理、单 document 并发拒绝。
• 绑定 actor、documentId、packagePath、sourceFrameId、writePlanId、expectedWorkingRevision、mutationKind。
• 只允许 createAiResultFrame mutation kind 作为 lease intent，不实现 mutation 本体。
• acquire / peek 基于 mindrawGetOpenDocumentState() 校验 live workingRevision。
• release / peek 覆盖 actor 和 writePlanId guard。
• 增加 LEASE_NOT_FOUND、LEASE_EXPIRED、LEASE_ALREADY_HELD、WORKING_REVISION_MISMATCH、MUTATION_NOT_ALLOWED 等失败态测试。
• 回写总台账 Progress Log。
• 新增 QA 证据报告。

关键决策

• lease manager 先作为前端内存模块实现，不接 Tauri command / loopback JSON-RPC transport。
• lease 不持久化；App 重启、多进程跨窗口互斥留给后续 transport / App API 设计。
• mindrawGetCapabilities() 仍保持 external lease / mutation capability unavailable，因为本轮没有暴露外部 transport。
• MD-H1-04 mutation 只能等待 PM 派发后再启动。

文件变更

• src/lib/mindrawAppReadApi.ts
• src/lib/mindrawAppWriteLease.ts
• src/lib/mindrawAppWriteLease.test.ts
• CODEGRAPH.md
• INDEX.md
• 02-P/qa/mindraw-phase38-lease-manager-check.md
• 02-P/plan-progress.markdown
• .codex-sessionhistory/2026-06-26-MDH103租约.md

验证结果

• npm run test:run -- src/lib/mindrawAppWriteLease.test.ts
• Test Files 1 passed
• Tests 11 passed
• npm run test:run -- src/lib/mindrawAppWriteLease.test.ts src/lib/mindrawAppReadApi.test.ts src/store/useStore.test.ts src/lib/excalidrawFile.test.ts
• Test Files 4 passed
• Tests 58 passed
• npm run build
• PASS
• 仅有既有 Vite font resolve / chunk size warning
• git diff --check -- ...
• 无输出，行尾检查通过

未决问题

• 尚无 loopback JSON-RPC / Tauri command transport。
• 尚无真实 App external write API discovery。
• 尚未实现 commit_write_result / createAiResultFrame mutation。
• 尚未接保存路径。
• 尚未做 H5 联合 smoke。
• 多窗口跨进程 lease 互斥仍未实现。

后续建议

• 等 PM 派发 MD-H1-04 后，再实现受控 createAiResultFrame mutation。
• MD-H1-04 应复用 mindrawPeekWriteLease() 做 commit 前 guard。
• PM-H5-GATE 继续等待 Mindraw mutation 证据和 m4c M4C-H5-02 证据齐备后再拆。