docs(research): 每屏 margin 路径结论与维护方案 (#56)

docs/EVIDENCE.md

@@ -68,6 +68,7 @@ R1 固定总出口的源码为 `ce9b24d`，早期 `2dc8d6d` / `9b16acc` 仍分
 | 范围 | 结果与复现入口 | 可以支持的结论与限制 |
 |---|---|---|
 | 行存储封存与结构单一发布（#169 第二片） | [固定结果](../experiments/core/results/2026-10-29-sealed-row-storage/README.md)、[验证身份](../experiments/core/results/2026-10-29-sealed-row-storage/validation.json) | `Screen::lines/history` 私有，只读口 + 23 文件/363 处迁移；Find overlay 改文档 rank；默认 Release 构建 exit 0、核心 8/8、扩展快测 20/20、candidate 源 /W4 编译 0。无新 VT/重排行为；运行中跨重排 Search、Qt 与候选运行由宿主作业复核。 |
+| 每屏 margin 的原生 gap：路径结论（#56） | [决策记录](research/conpty-margin-path-decision.md)、[合同与四阶段 oracle](research/conpty-native-margin-path.md)、[fork 构建/运行](https://github.com/JavaZeroo/termforge/pull/98) | 固定上游源码根因（共享 _scrollMargins）、hash 与 20 次同源运行（baseline red→patched 四阶段绿、412/412 adapter、17/17 回归）已固定；结论是“推荐 MIT fork，采纳需用户在 #34 确认”。不改变 ADR-0007 现状、#41 开放状态与产品后端。 |
 | 保留历史的内存与单次 Search 成本（#164 剩余项） | [固定结果](../experiments/core/results/2026-10-29-history-memory/README.md)、[验证身份](../experiments/core/results/2026-10-29-history-memory/validation.json) | 生产 `Screen`/`TextSearch` 在 H=100/1000/10000、各 3 个新进程样本：每行私有增量收敛 ~5.8–6.9 KB，H=10000 私有提交 ~59 MB；整文档 Search ~54 ms/199 步。不是 r164 fork 对照，也不是性能预算；不关闭 #164。 |
 | 结构重排下的增量 Search（#169 延期项 / #27 前置） | [固定结果](../experiments/core/results/2026-10-29-search-reorder/README.md)、[验证身份](../experiments/core/results/2026-10-29-search-reorder/validation.json) | `TextSearch` 以文档 rank 维护扫描前缀：order revision 检测、局部 `repair_order`、rank 化 `rewind`/`match`/`prune`。新 `search_reorder_core` 覆盖扫描中重排、重排后导航、淘汰与有序回归；核心 10/10。无 UI/Find 集成、无重排成本测量，不声明 #27/R2 通过。 |
 | 默认核心缩小与重绘交错（#156） | [固定四-case机制诊断](../experiments/shell/results/2026-10-29-resize-repaint-witness/README.md)、[脱敏验证](../experiments/shell/results/2026-10-29-resize-repaint-witness/validation.json) | A/C保留2499B，B/D在第五段重绘首次失效且行分配路径不同；只见证机制，原CI切点/根因未知，未修生产。witness结束后Job仍active1，发起一次终止后归零；成员身份/逐句柄退出未知，不称全树自然退出。 |

docs/research/conpty-margin-path-decision.md

@@ -0,0 +1,48 @@
+# 每屏 margin 原生合同：路径结论与后续方案（#56）
+
+本页是 [#56](https://github.com/JavaZeroo/termforge/issues/56) 的收口记录：把已完成的证据整理成**可执行的路径结论**，并明确“仍未做、需谁决定”。它不替代 [#34](https://github.com/JavaZeroo/termforge/issues/34) 的架构决定，也不声称 [#41](https://github.com/JavaZeroo/termforge/issues/41) 的原合同已验收。
+
+## 1. 合同已经固定（不再重写预期）
+
+- 逐字段判据、四阶段固定 oracle 与 175B 源：[conpty-native-margin-path.md](conpty-native-margin-path.md)、[margin_contract.py](../../experiments/conpty/margin_contract.py)、[白名单记录](../../experiments/conpty/results/2026-10-26-native-margin-path/validation.json)。
+- 分层检查点始终分开：**应用源 VT / 源控制台 CHAR_INFO / transport / 末端候选**；末端正确不能替代原生状态，原生正确也不能补回 transport 已丢失的控制序列。
+- 原失败（系统后端 native final 红、官方 80 列原 5 秒生命周期失败）保留在原记录中，未重跑覆盖。
+
+## 2. 根因已收敛到固定上游源码
+
+固定包 **Microsoft.Windows.Console.ConPTY 1.25.260930003**（源码提交 dc8ae365847d41f62d1ebca93815bb00959bc12f，MIT）：
+
+- SCREEN_INFORMATION::_CreateAltBuffer 删除新备用屏自己的 state machine，共享主屏 _stateMachine；
+- AdaptDispatch 有两个保存光标状态但只有一个 _scrollMargins，_SetAlternateScreenBufferMode 不保存/重置/恢复它，DECSTBM 却写它；
+- 原生 GetSet 负责实际 buffer 切换，原生与末端因此可能处于不同状态实现。
+
+这解释了“备用屏设置 4;5r 后，恢复的主屏 final 仍被上一区域影响”。它是固定源码 + 运行现象的共同推断，**尚无上游确认**，也未被上游版本修复。
+
+## 3. 受支持路径比较（含真实构建与运行，不再只有“可应用”）
+
+| 路径 | 现有证据 | 结论 |
+|---|---|---|
+| 上游修复后固定正式包 | 已固定根因；官方包 native 仍红 | 长期首选；需把 oracle/最小补丁送上游，接纳与发布未知 |
+| 小型 MIT fork（固定 1.25 + 单 margin 补丁） | [构建入口](https://github.com/JavaZeroo/termforge/pull/96)：baseline focused 1 fail、patched focused 1/1、full adapter 412/412 零 skip；[同源原生/末端对照](https://github.com/JavaZeroo/termforge/pull/98)：8 次 VT-on/off × 两尺寸，patched 四阶段原生全绿、transport 末端正确、自然 37/EOF109/Job0；[控制场景补充](https://github.com/JavaZeroo/termforge/pull/100)：12 次（main-only / default-alt / repeat-alt × 两尺寸 × 两版），baseline 的错误精确落在预期阶段，patched 全部阶段文字/完整格属性/光标/viewport 正确 | **唯一已有“同输入 red→green”的路径**；仍是候选，未接入产品 |
+| 关闭 ENABLE_VIRTUAL_TERMINAL_PROCESSING 当 raw 后端 | 80×24 末端表面正确，但原生格已把 ESC 当字面内容，12×7 丢 BOTTOM_FIXED | 拒绝 |
+| 旧 passthrough flag | 第一方已删除；当前头文件 0x08 是字素宽度策略 | 拒绝 |
+| 换另一 console server / 桥接层 | 无同输入原生+末端证据，维护面远大于局部状态修正 | 不采纳；如要调查需另立证据项 |
+
+## 4. 结论（供 #34 决策，需用户确认）
+
+**推荐路径：随包固定 ConPTY 采用上述 MIT fork，并把对照矩阵作为升级门禁。** 这是对 [ADR-0007](../adr/0007-bundled-microsoft-conpty.md)“随包固定官方 ConPTY”的一处依赖变更，按 [ADR-0006](../adr/0006-confirmed-project-direction.md) 必须由用户确认后才生效；本页只是提案 + 实施/维护方案。
+
+采纳前必须补齐（都已有明确入口，尚未完成）：
+
+1. fork 的独立发布身份：源清单、补丁 SHA、双文件 SHA、LICENSE/NOTICE、可复建构建记录（Draft PR #96/#98/#100 已具备大部分，需整理成正式来源清单）。
+2. 原 175B + 四阶段 + 控制场景在原矩阵上的复验（已做过 20 次运行，仍需在最终 fork 产物上重跑一次冻结批次）。
+3. 产品侧交叉：样式/非颜色属性、history、resize、查询/API、GUI 真实工作流；系统/服务器最低版本与更新策略。
+4. 维护方案：每次上游升级必须重放 adapter tests + 本页矩阵；补丁依赖的状态字段归属一旦变化即失效，需重新取证。
+
+**不采纳 fork 时的替代方案**：维持随包官方 1.25，并把原生 margin 差异保留为已知缺口，直到上游修复；这会持续阻塞 #41 的原合同，不能以“末端正确”结项。
+
+## 5. 边界
+
+- 本页不改变产品后端配置、ADR-0007 的当前实现、#41 的开放状态或 #34 的决定权。
+- 20 次 fork 运行全部来自 Draft 分支（#96 → #98 → #100 的固定源码），未合并；环境为 Windows 11 build 26200，未覆盖 Server/最低版本、真实 GUI 与长期资源。
+- 未测：显式 SGR 变更与保存恢复、非零光标起点、历史/淘汰、resize 交叉、查询/API 交叉、其他应用矩阵、性能。

docs/research/conpty-native-margin-path.md

@@ -1,5 +1,7 @@
 # 保留原生与末端 margin 合同的实现路径
 
+> 后续（2026-10-29）：本页的“候选仅可应用”状态已被真实构建与 20 次同源运行取代，路径结论与维护方案见 [conpty-margin-path-decision.md](conpty-margin-path-decision.md)。
+
 [#56](https://github.com/JavaZeroo/termforge/issues/56) 的当前交付是可执行的逐字段原生 oracle、固定上游的补丁候选及下一次构建入口。
 **原生缺口仍存在，尚无经过真实运行证明的完整修复路径。** 补丁仅检查可应用，没有编译或替换任何后端。
 这保留 [#41](https://github.com/JavaZeroo/termforge/issues/41) 的原合同与开放状态，不改变 #34 产品决定。