# Phase 3.8 Lease Spike

日期：2026-06-26

## 用户目标

用户要求进入 Phase 3.8：document lease / App write API spike。

## 已完成事项

- 新增 Phase 3.8 spike 目录：`02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/`。
- 新增可运行脚本：`validate-document-lease.mjs`，在临时目录生成测试 `.mindraw` 包，验证 document lease / App write API 状态机。
- 新增 spike README，记录 Given / When / Then、覆盖项、发现和 verdict。
- 新增主项目契约文档：`02-P/功能任务/document-lease-app-write-api-spike.md`。
- 新增 QA 记录：`02-P/qa/mindraw-phase38-document-lease-spike-check.md`。
- 同步更新 `02-P/plan-progress.markdown` 和 `INDEX.md`。

## 关键决策

- App 打开同一 `.mindraw` 包时，外部工具直接写 package 必须继续返回 `APP_LEASE_REQUIRED`。
- Phase 3.8 的正确方向是 App-mediated write：App 作为唯一写入方，外部工具只能基于 App live context / `workingRevision` 提交受控 mutation。
- 必须区分 `diskRevision` 和 `workingRevision`；dirty 文档不能用磁盘 revision 作为写入凭证。
- dirty 文档不是天然 No-Go；如果外部工具读取的是 App live working snapshot，并且 commit 时 `workingRevision` 未变化，App 可以合并 result Frame 并保存。
- lease 必须短 TTL、独占、绑定 `writePlanId` / `expectedWorkingRevision`，并在 commit 时重新校验。

## 文件变更

- `02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/README.md`
- `02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/validate-document-lease.mjs`
- `02-P/功能任务/document-lease-app-write-api-spike.md`
- `02-P/qa/mindraw-phase38-document-lease-spike-check.md`
- `02-P/plan-progress.markdown`
- `INDEX.md`
- `.codex-sessionhistory/2026-06-26-Phase38LeaseSpike.md`

## 验证

- `node 02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/validate-document-lease.mjs`：PASS。
- `node --check 02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/validate-document-lease.mjs`：PASS。
- `git diff --check` 覆盖本轮相关文件：PASS。

覆盖项：

- `direct-file-write-open-package-rejected`：PASS / `APP_LEASE_REQUIRED`
- `app-api-dirty-live-context-commit`：PASS
- `disk-revision-cannot-write-dirty-working-copy`：PASS / `WORKING_REVISION_MISMATCH`
- `user-edit-after-lease-rejected`：PASS / `WORKING_REVISION_MISMATCH`
- `concurrent-lease-rejected`：PASS / `LEASE_ALREADY_HELD`
- `expired-lease-rejected`：PASS / `LEASE_EXPIRED`
- `closed-document-app-api-rejected`：PASS / `APP_DOCUMENT_NOT_OPEN`

## 未决问题

- 未实现生产 Tauri command。
- 未接真实 Excalidraw editor API。
- 未验证多窗口、多 tab、App 后台启动、焦点切换和 UI 错误反馈。
- 未实现正式 MCP server 或真实用户 `.mindraw` 写回。
- Phase 4 `.assets` 权威资产治理仍未完成。

## 后续建议

下一步如果继续主项目实现，应进入 Phase 3.8 production design：

1. 只读 App state / live frame context API。
2. Lease manager：acquire / release / expiry / concurrency。
3. 受控 `createAiResultFrame` mutation，并复用现有保存路径。
4. 真实 App QA：dirty、revision mismatch、expired lease、concurrent lease、save failed。