feat: resolve topology reference candidates

docs/continuation-status.zh-CN.md

@@ -1,6 +1,6 @@
 # Web FreeCAD 接续执行状态
 
-更新时间：2026-08-03（TSN generation 写回里程碑完成，待提交）
+更新时间：2026-08-03（TopoRef 候选替换里程碑完成，待提交）
 
 ## 1. 当前目标
 
@@ -10,9 +10,9 @@
 
 - 分支：`main`
 - 云仓库：`http://154.8.160.151:3000/wangdequan/Web_FreeCAD_Bitbybit.git`
-- 最近已推送里程碑：`501f43f feat: apply object placement during recompute`
+- 最近已推送里程碑：`ffbe2c6 feat: persist generation topology history`
 - 最近已推送里程碑的完整门禁：`./npmw run verify` 通过
-- 当前 TSN 未提交工作区验证：`./npmw run verify` 通过（Facade 63/63），diff/JSON 校验通过
+- 当前候选替换未提交工作区验证：`./npmw run verify` 通过（Facade 64/64），diff/JSON 校验与桌面/移动截图通过
 - 生产构建：通过
 - 本地开发地址：`http://127.0.0.1:5173/`
 - 兼容真值表：`config/compatibility-matrix.json`
@@ -29,6 +29,7 @@
 7. Vector、Placement、LinkList/StringList 结构化属性合同；Placement 深拷贝、校验、撤销、持久化和 UI 编辑器。
 8. 对象级 Placement 重算：基本体/特征 Shape 生成后执行平移与轴角旋转；恒等变换跳过额外 Shape；变换失败释放临时 Shape 并保留上一次有效缓存；保存后恢复的 Placement 可再次驱动重算。
 9. TSN generation 写回：重算成功后采集面/边/点签名快照与保守历史；迁移 LinkSub/草图外部几何；歧义或删除引用标脏所有者并生成可定位诊断；schema v6 保存对象拓扑快照。
+10. TopoRef 候选替换事务：属性面板/诊断页从源对象当前同 kind 拓扑候选中原子替换 LinkSub 或外部几何引用，重建 DAG、标脏重算并支持 Undo/Redo。
 
 相关提交按新到旧：
 
@@ -57,7 +58,7 @@
 
 1. 补齐 P2 浏览器实证门禁：真实 SQLite v4→v5 升级、OPFS 孤儿清扫、QuotaExceeded、大文件和崩溃注入；合同层与 fallback 测试已由 `6bfbdf5` 完成。
 2. 补齐 P3-03 浏览器 OCCT 包围盒/体积黄金测试，并验证 Placement 撤销、保存和恢复的真实 Worker 路径；Node/fallback 合同已通过。
-3. 为 ambiguous/deleted TopoRef 补 3D 候选高亮和用户替换事务，并增加真实 OCCT/SQLite 浏览器回放；当前仅有 Facade 诊断与选择所有者流程。
+3. 为 ambiguous/deleted TopoRef 补 3D 候选高亮，并增加真实 OCCT/SQLite 浏览器回放；候选替换 Facade 事务和属性/诊断 UI 已进入当前里程碑。
 4. 在获得 FreeCAD `1.1.1` 源码/构建输入后完成 `SK-03` planegcs WASM POC；此前继续补充回放夹具、约束分类和 Sketch 编辑事务。
 5. 扩展 PartDesign：Mirrored、MultiTransform、Loft/Pipe/Groove、Thickness/Draft，以及 Pattern/Hole 完整语义。
 6. 完成 FCStd 原生对象/属性/Shape 双向映射和 STEP/IGES/STL/Web CAD 包导入导出。
@@ -112,8 +113,17 @@ Placement 里程碑涉及实现、测试、兼容矩阵和三份状态/方案文
 - 每个对象快照记录 generation、文档版本、迁移 matches 和 `signature-fallback` 历史；拓扑采集失败释放本轮 Shape，最近有效缓存不被覆盖。
 - 重算提交遍历 `App::PropertyLinkSub` 与 Sketch 外部几何：稳定引用写回新 generation；歧义/删除引用不强绑，所有者保持 dirty/warning 并产生 `TOPOLOGY_REFERENCE_AMBIGUOUS/DELETED` 诊断。
 - schema v6 新增 `objects.topology_json`，fallback 保存/加载已验证快照深克隆；真实 SQLite/OPFS v5→v6 升级尚未进行浏览器实证。
-- 完整 `./npmw run verify`、diff/JSON 校验均通过；提交与推送仍待执行。
+- 完整 `./npmw run verify`、diff/JSON 校验均通过；里程碑已由 `ffbe2c6` 推送。
 
-这仍不是 OCCT/FreeCAD 原生历史：签名来自三角网格，缺少曲面/曲线参数、邻接图和 Boolean 的逐输入原生历史。诊断能定位引用所有者，但 3D 候选高亮与原子替换 UI 尚未实现，因此 F3/TSN-03/07/09 不能标记完成。
+这仍不是 OCCT/FreeCAD 原生历史：签名来自三角网格，缺少曲面/曲线参数、邻接图和 Boolean 的逐输入原生历史。候选替换事务/UI 已在下一里程碑补齐，但 3D 候选预选与高亮尚未实现，因此 F3/TSN-03/07/09 不能标记完成。
+
+## 10. 2026-08-03 TopoRef 候选替换快照
+
+- 新增 Facade `resolveTopologyReference()` 事务，按所有者、PropertyLinkSub/ExternalGeometry 名称和候选 persistentId 定位引用；候选必须存在于源对象最新拓扑快照且 kind 一致。
+- 用户明确选择后写入 stable TopoRef 和最新 generation，重建 `topo-ref` DAG 边，标脏依赖闭包，更新文档版本并进入 Undo/Redo 与自动保存。
+- 属性面板对 ambiguous/deleted LinkSub 显示候选菜单；诊断页对 LinkSub 和草图外部几何显示候选替换控件。非法候选拒绝，不修改文档。
+- 完整 `./npmw run verify`、diff/JSON 校验通过；Chrome 桌面/移动布局无重叠，SwiftShader 延时截图确认 OCCT canvas 非空；提交和推送仍待执行。
+
+尚未完成 3D 面/边/点候选预选与高亮，也没有真实 OCCT 浏览器黄金回放，因此 TSN-09/F3 仍保持进行中。
 
 本里程碑不得声称 P3-03、F3 或完整 FreeCAD 兼容已经通过。当前对象 Placement 是 Shape 生成后的对象级变换，尚未证明 FreeCAD 对 Body/Tip、Support、AttachmentOffset 和局部坐标链的完整等价语义。

docs/freecad-full-parity-plan.zh-CN.md

@@ -310,7 +310,7 @@
 
 属性领域合同现覆盖标量、枚举、颜色、Vector、Placement、ObjectLink、ObjectLinkList/StringList 和版本化 SubshapeLink。Placement/Vector 使用结构化值并做有限数、角度范围及非零旋转轴校验，复合值深拷贝进入 Undo/Redo 与持久化。Facade 的对象级几何重算已在 Shape 生成后执行 Placement，并对恒等变换、畸形结构、变换失败释放和最近有效缓存保留给出测试证据；这不是 FreeCAD Body/Tip、Support、AttachmentOffset 或特征局部坐标链的等价实现，File/Shape 摘要和多选 mixed 编辑也仍未完成。
 
-TSN 已完成面/边/顶点量化签名、唯一/重复候选判定和匹配 API，并挂接到实际重算 generation。成功 Shape 会产生对象拓扑快照、迁移 matches 和 `signature-fallback` 历史；提交阶段自动写回 LinkSub 与草图外部几何，稳定引用更新 generation，歧义/删除引用保持显式状态、标脏所有者并产生修复诊断。schema v6 通过 `objects.topology_json` 保存快照。版本化 TopoRef 仍拒绝 transient index；但当前没有 OCCT 原生 `Generated/Modified/Deleted`、曲线/曲面参数签名、邻接图、跨特征 Boolean 原生映射或 3D 候选替换，因此 TSN-03、TSN-07/09 与完整 TSN-08 仍未完成。
+TSN 已完成面/边/顶点量化签名、唯一/重复候选判定和匹配 API，并挂接到实际重算 generation。成功 Shape 会产生对象拓扑快照、迁移 matches 和 `signature-fallback` 历史；提交阶段自动写回 LinkSub 与草图外部几何，稳定引用更新 generation，歧义/删除引用保持显式状态、标脏所有者并产生修复诊断。候选替换 Facade 事务验证当前拓扑和 kind 后原子写入 stable TopoRef，重建 DAG、进入 Undo/Redo；属性面板和诊断页均通过 Facade 调用。schema v6 保存快照。当前仍没有 OCCT 原生历史、曲线/曲面参数签名、邻接图、跨 Boolean 原生映射或 3D 候选高亮，因此 TSN-03、TSN-07/09 与完整 TSN-08 仍未完成。
 
 Sketcher 已有 Facade 事务模型和基础求解器适配器：Sketch 几何/约束快照进入 `DocumentObjectSnapshot`，新增几何、约束和求解会更新 `ConstraintStatus`、历史、自动保存与 SQLite schema v4；基础约束现覆盖 Diameter、Symmetric、Tangent。该适配器的职责是验证数据模型和提供可替换协议；它不宣称已经等价于 FreeCAD `planegcs`。SK-03 的 planegcs WASM、SK-07 的完整约束分类、SK-09 的交互回放和 SK-10 的 B-spline 仍是兼容门禁。
 
@@ -342,7 +342,7 @@ Geometry Facade 还接入了 Bitbybit IO 的 STEP 和 ASCII STL 导出，作为
 | P3-05 Pattern 实验切片 | `linear-pattern` 和 `polar-pattern` 通过 Part Design 选择谓词、Task 和类型化属性创建对应对象；Linear 按总 Length 等距平移，Polar 在小于 360° 时覆盖首末角、360° 时不复制重合端点；两者均由 OCCT union 合并并释放临时副本 | 线性间距/方向、圆周完整/部分角度分布、联合输入、句柄释放、非法参数诊断、Base 链接、Body.Tip、属性校验和任务提交回归测试通过 | 当前为 FreeCAD 1.0+ 的 Transform body 近似，只复制整个 Base Shape；未实现 Transform tool shapes、连接单实体过滤、稳定 TopoRef、历史映射、反向轴和引用轴，因此保持 `experimental` |
 | P3-05 Hole 基础切片 | `hole` 创建 `PartDesign::Hole`，用 32 边圆形 Profile 调用现有 OCCT Pocket；支持 Diameter、Depth 以及 Dimension/Through all，校验正尺寸并纳入 Base 链接和 Body.Tip | 圆孔 Profile、有限深度调用、非法直径诊断、Task 属性提交和 Tip 更新测试通过 | 仅为基体原点 XY 面、+Z 法向的直孔；草图圆/面定位、沉孔、锪孔、钻尖、螺纹、尺寸标准和稳定支撑面引用仍待实现，保持 `experimental` |
 | TSN-02/05/06/08 TopoRef 基础迁移 | `topologyReferences` 提供 schema v1 创建、序列化、安全解析、解析和跨版本迁移；重复几何候选 ID 唯一，一旧多新不会错误继承；匹配按 kind 隔离并用形状尺度归一化几何评分支持纯平移 | round-trip、瞬时索引拒绝、resolved/ambiguous/deleted、重复拆分和纯平移回归测试通过 | 仍是网格签名启发式；没有 OCCT Generated/Modified/Deleted、邻接/曲率签名、布尔历史和黄金模型规模验证，不得提升为 compatible |
-| TSN-08/09 LinkSub 文档接线 | `PropertyValue` 支持 schema v1 TopoRef；依赖图产生带 persistentId 的 `topo-ref` 边；重算 generation 自动迁移 LinkSub/草图外部几何，歧义/删除不强绑并产生定位诊断；schema v6 保存对象拓扑快照；Pocket 暴露 `UpToFace` 槽 | 非法瞬时索引/缺失对象拒绝、DAG 边、稳定/歧义/删除迁移、跨 generation 回退解析、保存加载 round-trip 和专项测试通过 | 尚未从 3D 选择创建/替换候选引用；诊断只能选择所有者，Pocket Up to face executor 仍保持结构化 unsupported，等待原生面历史/解析接线 |
+| TSN-08/09 LinkSub 文档接线 | `PropertyValue` 支持 schema v1 TopoRef；重算 generation 自动迁移 LinkSub/草图外部几何，歧义/删除不强绑；schema v6 保存对象拓扑快照；Facade 候选替换事务验证当前同 kind persistentId，重建 DAG 并支持 Undo/Redo；属性/诊断 UI 可替换；Pocket 暴露 `UpToFace` 槽 | 非法瞬时索引/候选拒绝、DAG 边、稳定/歧义/删除迁移、跨 generation 回退解析、候选替换、Undo/Redo、保存加载和 64 项全套测试通过 | 尚未从 3D 拾取、预选或高亮候选；Pocket Up to face executor 仍保持结构化 unsupported，等待原生面历史/解析接线 |
 | TSN-03/07 历史适配器回退 | Bitbybit 1.1.1 绑定仅有 `HasGenerated()`，没有逐 Shape 的 Generated/Modified/IsDeleted；`signature-fallback` 已进入真实重算 generation，对每个成功 Shape 保存快照/matches/history，采集失败释放临时 Shape并保留最近有效缓存 | 平移修改、新增/删除/重复面、跨对象竞争、generation 写回、采集失败隔离和持久化测试通过；全套 63 项测试通过 | 此 provider 不是 OCCT history；多输入 Boolean 当前仍缺逐输入原生映射，只有自构建绑定暴露逐子形状历史并通过黄金模型后，才能将 TSN-03/07 标为完成 |
 
 后续按以下顺序连续开发：

docs/web-cad-implementation-plan.zh-CN.md

@@ -1602,12 +1602,12 @@ P0 基线/治理
 | P2-05 多标签页写入协调 | `DONE (降级可观测)` | `SqliteProjectPersistence` 在保存和资源写入外包 `navigator.locks` 独占锁，成功保存通过 `BroadcastChannel` 广播文档版本，Facade 暴露 `project.subscribeExternalChanges()`；无 Web Locks 的运行时能力标记为 `local-queue`，不宣称跨标签页互斥 |
 | P5-01 Three.js 视口适配器 | `IN PROGRESS` | `src/facade/threeViewport.ts` 使用 `three@0.185.1`，已挂载 WebGL2 场景和资源释放；React 视口通过 Facade OCCT 预览链生成 Pad/Pocket Mesh |
 | P3-01 Bitbybit OCCT WASM 运行时 | `IN PROGRESS` | 精确锁定 `@bitbybit-dev/occt-worker@1.1.1`，专用 Worker 可加载 34,524,750 字节 OCCT WASM；尚未建立 FreeCAD/OCCT 自构建脚本，不能标记完成 |
-| P3-02 几何句柄与网格协议 | `IN PROGRESS` | Facade 已定义并实现受控 `ShapeHandle`、`MeshAsset`、`SubshapeRef` 类型；`geometry.topology()` 生成面/边/点签名条目，成功 generation 写入对象拓扑快照、迁移 matches 和保守历史；TopoRef schema v1 可序列化/解析/迁移并拒绝瞬时索引，重算提交自动迁移 LinkSub/外部几何，歧义/删除保持显式状态和诊断。OCCT 原生历史命名、邻接/曲率签名、跨 Boolean 映射和 3D 候选替换仍未实现 |
+| P3-02 几何句柄与网格协议 | `IN PROGRESS` | Facade 已定义并实现受控 `ShapeHandle`、`MeshAsset`、`SubshapeRef` 类型；成功 generation 写入对象拓扑快照、迁移 matches 和保守历史；重算自动迁移 LinkSub/外部几何，歧义/删除保持显式状态和诊断；候选替换事务只接受源对象最新同 kind persistentId，属性/诊断 UI 可提交并支持 Undo/Redo。OCCT 原生历史、邻接/曲率签名、跨 Boolean 映射和 3D 候选高亮仍未实现 |
 | P3-03 基本体和变换 | `IN PROGRESS` | 真实 OCCT Box/Cylinder/Sphere/Cone 和浏览器矩阵已验证基础 Placement；Facade 重算 executor 现在对对象 Placement 做严格结构校验，在 Shape 生成后执行平移/轴角旋转，恒等变换跳过额外句柄，失败时释放临时 Shape 并保留最近有效缓存；Node/fallback 已覆盖失败释放、畸形输入和保存恢复。0.05 mm 网格精度下曲面包围盒最大离散误差约 0.023 mm，自动化浏览器黄金/体积测试尚未进入 CI |
 | P3-04 Boolean/Pad/Pocket/Revolution | `IN PROGRESS` | 文档作用域 Union/Cut/Intersection 与 PlanarProfile 驱动的 Pad/Pocket/Revolution 已通过真实 OCCT 浏览器矩阵；重算 executor 已在 Worker ready 时执行 Pad/Pocket/Revolution，Revolution Angle/Reversed 已接入，Fillet/Chamfer 也有 Shape 缓存回写；Up to face、FCStd Shape 持久化仍待完成 |
 | P3-05 Fillet/Chamfer/Pattern/Hole | `IN PROGRESS` | Fillet/Chamfer 已接入 Shape 缓存；Linear/Polar Pattern 已贯通选择谓词、Task、Placement/union 和清理；基础 Hole 用圆形 Profile 复用 Pocket，支持 Diameter、Depth、Dimension/Through all。Pattern 当前为整 Shape，Hole 当前固定原点法向；局部特征历史、连接单实体过滤、稳定 TopoRef、草图/面定位及沉孔/锪孔/螺纹仍待实现 |
 | P5-02 网格增量接入 | `IN PROGRESS` | Three Adapter 可用 `BufferGeometry` 接收 Facade `MeshAsset`，替换时释放旧 GPU geometry；视口优先使用重计算缓存的对象 Shape，失败时保留最近有效结果，无缓存时才创建并释放 Pad/Pocket 临时预览链；对象级增量缓存与选择映射尚未实现 |
-| P8-01 第一批自动化场景 | `IN PROGRESS` | `tests/facade.test.ts` 已覆盖 63 个场景，包括 Part/PartDesign、Pattern/Hole、TopoRef/LinkSub、generation 拓扑快照/迁移、Sketch provider、几何重算、诊断修复、FCStd 安全、schema migration、1000 次写队列、检查点和资源治理；E2E/黄金几何待补齐 |
+| P8-01 第一批自动化场景 | `IN PROGRESS` | `tests/facade.test.ts` 已覆盖 64 个场景，包括 Part/PartDesign、Pattern/Hole、TopoRef/LinkSub、generation 拓扑快照/迁移/候选替换、Sketch provider、几何重算、诊断修复、FCStd 安全、schema migration、1000 次写队列、检查点和资源治理；E2E/黄金几何待补齐 |
 
 本迭代验证命令：`npm run check:facade-boundary`、`npm run test:facade`、`npm run build`。构建产物将 Three.js 拆为独立 chunk，避免把全部渲染库重复打入应用主 chunk。当前 npm registry 的 `three` 最新版本为 `0.185.1`，已在 `package.json` 和运行时基线中锁定。下一迭代继续完成 P0-01/P0-02 的精确锁定、P2-01/P2-02 的 SQLite/OPFS schema 与 Worker 单写者实验，以及 P3-01 的 FreeCAD/OCCT WASM 构建验证。