# 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` 证据齐备后再拆。