# 约束求解器与编辑 API

父任务：`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。

## 目标

把约束解析从几何生成中抽成纯函数边界，并用它同时支撑草稿预览与正式编译；对外提供预览、保存、revision 与 rebase 的服务端能力。本子任务不含任何 UI。

## 顺序依赖

前置：`direct-edit-documents`（需要 v2 文档 schema、`documentVersion`、活动副本与 area config 快照读取）。
后继：`direct-edit-map-editor` 与 `direct-edit-junction-tools` 依赖本任务的 handle manifest 与预览 API。

## 范围

- `resolveDirectEditConstraints` 纯函数：输入基线模型 + v1 覆盖 + v2 约束，输出 editable profiles、junction plans、handle manifest、diagnostics。
- 6 个约束 kind 的求解；interval 默认范围推导（避开两端 junction reserve）；junction reserve 计算。
- `junction-approach-width` 对道路 profile 的优先级，以及两域边界的连续过渡。
- 约束重放匹配：精确匹配优先，失败才按 `anchorSnapshot` 找候选，产出 5 态 `ConstraintStatus`。
- 端点：`GET /api/edit-state`、`POST /api/edit-preview`、`POST /api/edits`、`POST /api/revisions`、`POST /api/revisions/:id/rebase`。
- `previewSeq` 回显、`degraded` 标记、`expectedDocumentVersion` 前置条件与 409。
- `/api/state`、`/api/session`、`/api/import` 的增量字段。

## 不做

- 任何客户端改动、手柄渲染或拖拽交互。
- cluster 的高级求解（只保证 cluster 不被当成多个普通路口处理）。
- 多人协作的并发合并策略。

## 验收标准

- [ ] 求解是纯函数：无文件写入、无网络调用，可用单元 fixture 直接驱动。
- [ ] 无 v2 约束时编译输出与当前 main 逐字节一致（baseline fixture 比对）。
- [ ] 6 个 kind 各有重放 fixture；预览与正式编译对同一约束集给出相同几何。
- [ ] 违反最小车道宽 2.4m、左右外缘交叉、路口面自交、connector 越界时返回阻塞性诊断而非静默修复。
- [ ] `boundaryIndex` 越界转 `stale`；锚点缺失转 `stale`；候选歧义或偏差超阈值转 `conflicted`。
- [ ] 编译器几何版本不一致时约束全部标 `recheck`，不自动改值也不自动失效。
- [ ] `POST /api/edit-preview` 调用前后工作区目录内容与 mtime 不变。
- [ ] `expectedDocumentVersion` 不匹配返回 409 且不写入；原子写入中途失败不留半份文件。
- [ ] rebase 返回各 status 的计数与逐条明细。
- [ ] 既有 `/api/overrides`、`/api/compile`、`/api/state` 的字段与行为不变。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run build` 全绿。