SystemSimulationApp/docs/other/求解器性能优化任务清单.md

# 求解器性能与鲁棒性优化任务清单

> 用途：记录求解器优化的现状、证据、实施顺序和验收结果，供后续开发前后对比与持续更新。
> 首次建立：2026-08-17
> 基线代码：`6bb0591d320d0c448ee8d224dd44127bfe3ce00f`（本地 `model-development`）
> 基线模型：`tests/data/test_mql-full-branches-01-04.xml`
> 模型 SHA-256：`2fb95e65f5de0c85a6a17802aef74ea004087323fd00fd8d01acf0184ff71d48`
> 当前主固化目标：`tests/data/test-mql-8.xml`
> 主目标 XML SHA-256：`0a2d9331df9eb5974daec25a61c1238ba32b1742d933ffc8b16ce316c5627b0b`
> 配套项目 JSON：`tests/data/test-mql-8.json`，SHA-256 `b44bf540ccd1c293fe2af2b9b9052b540abf83961ad955a0f6a4ab40fbe0bb18`
> AMESim 权威物理基线归档：`AmesimModels/test_mql.ame`，SHA-256 `cbc3aadd4569a49b3a63e5d66d4143ec16126c0f950df73fb637e07673c20fbb`

## 1. 使用规则

本文档不是一次性的建议列表，而是优化工作的验收账本。

- 状态统一使用：`未开始`、`进行中`、`部分实现`、`已完成`、`阻塞`、`不采用`。
- 只有同时完成代码、自动测试、基准复测和本文档更新后，任务才可标记为“已完成”。
- 每次性能对比必须记录代码提交、工作树状态、输入哈希、解释器与依赖版本、硬件和运行参数。
- 正确性门槛先于速度收益。若结果越过误差契约，即使运行更快也不能合入默认路径。
- AMESim 归档中的仿真结果是物理数值正确性的唯一基线；每次正式回归都必须按投影逐项计算并保存当前值、AMESim 基线值、绝对误差和相对误差。
- Python exact/state golden 仅用于检测确定性、实现漂移和输出契约变化，不得单独或与本地 physical golden 一起批准物理正确性。
- AMESim 基线为 0 时相对误差在数学上未定义，报告写为 `null` 并用绝对误差判定；AMESim 未保存的内部守恒量必须明确标记为不可外部比较，并继续执行独立绝对残差门。
- 容差、模型方程或输出字段发生变化时，必须单独说明；不得将其伪装成纯性能优化。
- 墙钟时间只在同一台机器、相同负载和相同环境下直接比较；跨环境以工作量计数和正确性指标为主。
- 每项优化都应保留明确的关闭开关或旧路径，直到新路径经过复杂模型和通用回归验证。

## 2. 当前结论与基线

### 2.1 关于 2.05 s 卡死

当前随附 XML 的磁盘配置是 `tStop=0.81 s`，因此原文件本身不会运行到 2.05 s。将停止时间仅在内存中改为 `2.10 s` 后，当前代码已经完整越过 2.05 s 并正常结束：

- `2.040432 s`：墙钟 `114.065 s`
- `2.046141 s`：墙钟 `120.746 s`，期间 CPU 时间持续增长
- `2.051691 s`：墙钟 `121.548 s`
- `2.100000 s`：完成积分并进入后处理
- 总运行完成，无重试、无非线性回退，也没有无进度死锁

因此，当前证据支持“此前的 2.05 s 卡死在现版本中没有复现”；该区间仍存在数秒级慢推进。`10 s` 尚未验证，不能由本次结果外推保证。

### 2.2 环境说明

首次历史复测时仓库 `.venv` 尚不完整，因此当时使用现有 `/opt/srm-trial-review/.venv`：

| 项目 | 本次值 |
| --- | --- |
| Python | 3.12.3 |
| NumPy | 2.4.6 |
| SciPy | 1.17.1 |
| 求解器 | BDF |
| 输出步长 | 0.01 s |
| 执行路径 | stream/cancel-check |

该环境满足仓库依赖范围，但并非已经锁定的正式项目环境。当前物理解哈希与历史调研文档不同，所以逐位结果基线必须在正式锁定环境中再次确认。

### 2.3 当前实测基线

| 指标 | 原始 `0.81 s` | 仅内存延长至 `2.10 s` |
| --- | ---: | ---: |
| 状态 | 完成 | 完成，越过 2.05 s |
| 墙钟时间 | 63.779 s | 126.211 s |
| 积分时间 | 62.116 s | 122.180 s |
| 后处理时间 | 1.118 s | 2.703 s |
| 最大 RSS | 165,464 KiB | 198,348 KiB |
| 输出样本数 | 82 | 213 |
| 状态数 | 74 | 74 |
| `nfev / njev / nlu` | 3763 / 253 / 761 | 6734 / 487 / 1507 |
| 接受步 | 1076 | 1857 |
| 分段启动 | 3 | 5 |
| 状态切换 | 0 | 2 |
| 重试 | 0 | 0 |
| 有限差分附加 RHS 估计 | 7843 | 15097 |
| 压力闭合次数 | 30,502 | 57,601 |
| 非线性/块/稠密回退 | 0 / 0 / 0 | 0 / 0 / 0 |
| 最大热流体外迭代 | 3 | 3 |
| Jacobian 稀疏度 | 1284 nnz / 31 色 | 1284 nnz / 31 色 |

补充观察：

- 积分占总耗时约 97%，当前首要瓶颈不是后处理。
- `2.10 s` 运行中，估计总 RHS 工作量约为 `6734 + 15097 = 21831`；有限差分扰动约占 69%。
- 压力闭合约为每次估计 RHS 2.64 次，但全部走已播种的因果路径，没有触发 `least_squares`。
- 全局因果执行已启用：快速执行 22,216 次，完整残差审计 351 次，审计失败 0 次，旧路径回退 0 次，审计间隔为 64。
- 当前结果哈希仅作为本次环境的诊断记录：`0.81 s` 为 `c6354c97...`，`2.10 s` 为 `efef49f8...`；它们暂不作为跨环境验收标准。

### 2.4 当前模型结构基线

| 项目 | 数量 |
| --- | ---: |
| XML 组件 / 编译组件 | 99 / 98 |
| 连接 | 106 |
| 连续状态 | 74 |
| 代数未知量 / 方程 | 472 / 472 |
| 原始关联矩阵非零元 / 方程块 | 919 / 58 |
| effort 未知量 / flow 未知量 | 272 / 200 |
| effort 等价组 / 可消去重复 effort | 68 / 204 |
| 显式 flow/force 赋值 | 200 |
| stream 块 / stream 未知量 | 9 / 192 |
| 结果变量 | 1,021 |

### 2.5 新主固化目标 `test-mql-8`

自 2026-08-17 起，后续通用求解器优化以 `tests/data/test-mql-8.xml` 为主固化目标；配套 `test-mql-8.json` 用于校验项目结构，但 XML 是权威执行输入。原 `test_mql-full-branches-01-04.xml` 继续保留为历史慢区、2.05 s 与首批半解析 Jacobian 的回归样例。runner 只在内存中覆盖 `tStop/sampleStep/maxStep`，不得改写权威输入。

| 项目 | 主目标值 |
| --- | ---: |
| 运行组件 / 连接 | 156 / 178 |
| 动态组件 / 连续状态 | 58 / 132 |
| 代数未知量 / 方程 | 776 / 776 |
| ODE Jacobian 结构 | 3280 nnz / 52 色 |
| 因果 effort / flow 赋值 | 440 / 336 |
| secondary 代数块 / 未知量 | 12 / 368 |
| 结果变量 | 1,784 |
| 原始 `tStop / sampleStep / maxStep` | 10 / 0.01 / 0.001 s |
| 信号断点 | 0.04、0.8 s |

本轮正式环境使用仓库 `.venv`：Python 3.12.3、NumPy 2.5.2、SciPy 1.18.0。`.python-version` 与 `constraints/python312-direct.txt` 固定跨平台开发参考；`constraints/python312-linux-x86_64.lock` 则固定 Linux x86_64 发布环境的 22 个直接/传递包、wheel SHA-256，并强制 binary-only 与 hash 校验。README、CI 与依赖契约测试使用同一安装口径。机器可读 manifest 与 runner 分别位于 `tests/baselines/simulation/test_mql_8/manifest.json` 和 `app/simulation/benchmark_regression.py`；默认顺序为 `0.01 smoke → 0.2 → 1 → 5 → 10 s`，每档均有合作取消、硬终止、资源记录与后续档延迟门，且 `sampleStep` 与 `maxStep` 可按 lane 独立覆盖。

## 3. 总体验收协议

每个优化 PR 至少执行以下分层验证；高风险改动不得只用单点输出或单个哈希判断正确性。

### 3.1 快速结构检查（CI）

- [x] 模型输入 SHA-256 与固定 fixture 一致。
- [x] 组件、连接、状态、代数方程和 stream 结构数量符合预期。
- [x] Jacobian 结构至少覆盖已知跨域依赖，并通过稠密数值扰动抽查。
- [x] 因果计划覆盖率、回退原因和审计失败数可观测。

### 3.2 数值检查点

至少覆盖以下区间和模式边界：

- [ ] `0.68–0.71 s`：历史慢区。
- [ ] `0.79–0.81 s`：原始模型终点及信号事件附近。
- [ ] `2.00–2.10 s`：此前报告卡死区间和状态切换。
- [x] `10 s`：最终通用接线后的当前工作树已完成首次长时间模式变化运行；连续 3 次和批准 golden 仍属于 OPT-09 后续。

每个检查点比较：连续状态、关键压力/流量/位移/速度、事件时刻与顺序、模式状态、有限性、最大缩放残差及守恒量。

### 3.3 性能记录

每次正式对比至少预热 1 次、测量 3 次并报告中位数，同时保存：

- 总时间、积分时间、后处理时间、CPU 利用率、峰值 RSS。
- `nfev`、`njev`、`nlu`、接受/拒绝步、分段和重试次数。
- SciPy 模式的有限差分 RHS 估计；callable 模式的真实扰动、基准和 Jv 审计 RHS 计数；Jacobian 颜色数与构建时间。
- 代数闭合次数、快速因果次数、完整审计次数和各类回退次数。
- stream/热流体迭代次数、物性缓存命中率、事件候选与定位次数。
- 输出标量数、编码字节数、传输字节数和后处理峰值内存。

### 3.4 P0 最大积分步长路径鲁棒性门

权威工程场景固定为 `test-mql-8.json` 经浏览器导出并由服务执行的同一系统语义，方法为 BDF。短基线使用
`tStop=0.2 s`、`sampleStep=0.01 s`、`maxStep=0.001 s`；长基线只将 `tStop` 延长到
`10 s`。`sampleStep` 是输出网格，`maxStep` 是积分步长上限，报告与诊断不得混用两者。

- **时域延长不变量**：固定模型、容差、方法和 `maxStep` 时，如果较短的 `tStop=T1` 能完成，则
  `T2>T1` 的运行不得因数值错误在 `T1` 之前提前结束。只比较严格位于 `T1` 之前的公共检查点；
  短任务终点的 accepted endpoint 与长任务内部插值单独标记，不作位级误判。
- **步长细化可解性不变量**：在约定工程区间内，如果较大的 `maxStep` 能完成同一时域，则更小
  `maxStep` 不得反而出现不可恢复数值失败。更小上限可以更慢；若仅因工作量增加超过预算，必须归类为
  `budget_limited` 并证明仍持续推进，不能记为 solver failure 或借此选择一个“幸运步长”。
- [ ] 首先对账 JSON、浏览器生成的 System XML、服务请求和 worker 最终生效参数；保存输入哈希，禁止用 runner 的内存覆盖掩盖浏览器路径问题。
- [ ] 浏览器当前工程验收明确为失败：`0.2 s / 0.001 s` 在 `t≈0.0489 s` 被判定计算超时；离线 production runner 的完成记录只作对照，不能写成浏览器正常完成。必须用同一 JSON 复现并分类为内部慢步、求解器真停滞、后处理/传输或服务假超时。
- [ ] 第一阶段在其余参数不变时串行运行 `tStop={0.2,1} s × maxStep={0.001,0.002,0.005,0.01,0.02} s` 的短时二维矩阵；最终签收要求所有单元到达终点，不得出现 NaN/Inf、不可恢复数值错误或无解释回退。定位阶段允许记录有持续进展证据的 `budget_limited`，但它既不算数值失败，也不算通过。
- [ ] 短时二维矩阵通过后，再按相同契约依次延长到 `2 s → 5 s → 10 s`；每一档先运行权威 `0.001 s`，再运行代表性的 `0.005/0.02 s`，最后补齐其余步长。每一档先确认同 `maxStep` 公共前缀，再进入下一档，不因较长 `tStop` 改变已覆盖区间的成败结论。
- [ ] 跨 `maxStep` 不要求逐位相同；按积分状态、派生量、关键压力/流量、守恒量、事件和离散模式分别验收，近零派生加速度不得使用统一相对误差误判真实积分状态。
- [ ] 每个 `0.01 s` 模拟区间记录墙钟、实际 `h_abs`/BDF 阶次、接受/拒绝步、重启、`nfev/njev/nlu`、Jacobian 构建、stream/热流体闭合与恢复轨迹；性能悬崖必须能定位到具体阶段和组件。
- [ ] 内部 RHS、Jacobian、stream/热流体闭合或恢复循环仍有活动时，服务持续发送活动心跳，浏览器不得因 60 s 内没有接受步而误判卡死；真正无活动必须有界终止并报告最后阶段、时刻、步长和计数。
- [ ] 将终止结果明确分类为 `numerical_failure`、`service_timeout_worker_active`、`active_slow_trial`、`true_stall` 或 `budget_limited`；浏览器超时始终属于工程路径未通过，但在证据不足时不得冒充数值失败。
- [ ] 任一会改变数值路径、事件语义、容差或默认求解策略的修复，必须先形成“复现证据 → 首个异常阶段 → 根因假设 → 最小方案 → A/B 判据 → 回退方式”，提交审阅后再实施；每轮只修改一个概念并先复跑原失败单元。
- [ ] 在 `0.2/1 s` 短时门通过后，依次取得 `2/5/10 s` 数据；在对本次长跑做任何性能调优前，先完整取得一次 `10 s / 0.001 s` 原始基线，完成后才按时间线选择最小优化并复跑完整阶梯。

该门的目标不是寻找一个“碰巧能跑”的固定 `maxStep`，也不是要求所有步长得到位级相同轨迹，而是让合理工程区间内的
`maxStep` 只影响可解释的误差与成本，不决定仿真能否完成。

## 4. 优化任务总览

优先级定义：`P0` 为基线或正确性前置，`P1` 为主要性能收益，`P2` 为第二阶段，`P3` 为战略性或条件性工作。

| ID | 优先级 | 任务 | 当前状态 | 难度 | 预期价值 | 主要依赖 |
| --- | --- | --- | --- | --- | --- | --- |
| OPT-00 | P0 | 固化复现、环境和回归基线 | 重新打开（离线基线完成；浏览器路径失败待定位） | 中 | 很高 | 无 |
| OPT-01 | P1 | 完成因果代数内核与坐标消元 | 基本完成（主要矛盾闭环） | 中高 | 中高 | OPT-00 |
| OPT-02 | P1 | 建立扁平数值 IR 和数组执行内核 | 部分实现（参考 IR） | 很高 | 很高 | OPT-01 |
| OPT-03 | P1 | 稀疏 Jacobian 数值层与解析/半解析演进 | 部分实现 | 很高 | 很高 | OPT-00；解析链可与 OPT-02 分阶段 |
| OPT-04 | P1 | stream 拓扑传播与物性成组复用 | 部分实现 | 中高 | 中高 | OPT-00 |
| OPT-05 | P0/P1 | 最大积分步长路径鲁棒性、状态缩放和步长策略 | 进行中（P0 阻断） | 中高 | 很高 | OPT-00 |
| OPT-06 | P2 | 事件检测与 dense output 按需化 | 部分实现 | 中 | 中 | OPT-00 |
| OPT-07 | P2 | 输出、后处理和传输内存优化 | 未开始 | 中 | 中高（长仿真） | OPT-00 |
| OPT-08 | P0/P2 | 进度、取消和服务并发鲁棒性 | 进行中（浏览器 `0.0489 s` 失败待定位） | 中 | 很高 | OPT-00、OPT-05 P0 门 |
| OPT-09 | P0/P2 | 建立 10 s 长时验证与模式覆盖 | 进行中（权威 `0.001 s` 基线未完成） | 中高 | 很高 | OPT-00、OPT-05 P0 门、OPT-08 服务门 |
| OPT-10 | P3 | 明确高指数 DAE/强非光滑系统边界 | 未开始 | 很高 | 条件性 | OPT-09 |

当前推荐实施顺序：`OPT-00 浏览器失败复现 → OPT-05/OPT-08 定位并解除 0.2 s 阻断 → 0.2/1 s × 五档 maxStep 短时鲁棒性门 → 2/5/10 s 逐级延长 → OPT-09 首次 10 s / 0.001 s 完整基线 → 基于时间线提案、审阅、单项优化与完整复验`。OPT-01/02/03/04 的既有成果保留，但在该 P0 工程门通过前不以单点性能收益替代鲁棒性验收。

## 5. 详细任务

### OPT-00 固化复现、环境和回归基线

**目标**：先让“是否更快、是否仍正确、是否又卡住”可以稳定复现和自动判断。

**当前状态**：重新打开工程端到端复核。2026-08-18 的离线 production runner、发布锁、golden、physical-state-v2.1、历史 `2.10 s` 三次复测和本地自动测试证据继续有效；但浏览器使用权威 JSON、BDF、`tStop=0.2 s`、`sampleStep=0.01 s`、`maxStep=0.001 s` 时当前会在 `t≈0.0489 s` 被判定计算超时，工程验收结果为失败。离线 runner 的完成记录不能替代浏览器结果；同 `maxStep` 的时域延长不变量和减小 `maxStep` 的可解性不变量也尚未验收。

**工作项**：

- [x] 将新主目标 XML/JSON 放入固定 fixture 路径，并在 manifest/测试中校验双哈希、字节数和配对配置；提交本轮工作时必须一并纳入版本控制。
- [x] 建立 Python 3.12.3 与六个直接依赖的跨平台参考约束，并建立 Linux x86_64 的 22 个直接/传递包、binary-only wheel SHA-256 发布锁；空 venv 离线安装、`pip check` 与依赖契约均通过。
- [x] 将临时探针整理为仓库内可重复运行的 benchmark，不依赖 `/tmp` 文件。
- [x] 添加 `0.81 s` 和仅改 `tStop=2.10 s` 的历史标准运行入口。
- [x] 添加模型结构快照断言；结构有意变化时显式更新原因。
- [x] 建立 `physical-state-v2` 的首批 state/checkpoint/event 投影；其 Python golden 现仅作为 production `0.2 s` 的确定性与实现回归诊断。
- [x] 将关键压力、质量流量、三类质量守恒、总储气质量和离散模式加入 `physical-state-v2.1`，绑定 AMESim 单位/符号变换，并在每次运行时以 AMESim reference values 执行物理门。
- [x] 将无数值的完整输出形状契约与物理状态 golden 分开；完整 API 序列化契约若需逐字段稳定性，后续另行定义。
- [x] 建立短 CI、夜间 `0.81/2.10 s`、定期递进至 `10 s` 的三层 workflow；远端首次执行待提交后确认。
- [x] 保存带环境、仓库、输入、运行统计和验收结果的机器可读 JSON 报告。
- [ ] 以权威 JSON 经浏览器生成 XML 并走流式 API 的真实路径完成 `0.2 s / 0.001 s`，与 production worker 对账输入哈希、生效参数、事件、物理量和最终结果；定位并消除 `t≈0.0489 s` 的计算超时或假超时。
- [ ] 通过第 3.4 节的 `0.2/1 s × 五档 maxStep` P0 短时矩阵与两条不变量；既有 `0.01/0.02/0.05/0.10 s` 历史运行不能替代缺失的 `0.001 s` 工程验收。

**验收条件**：

- [x] 干净环境可按发布锁一条安装命令复现：全新空 venv 使用 22 个锁定 wheel 与 SHA-256 完成安装，`pip check`、锁定环境契约和最终 quick workflow 同口径测试通过。
- [x] 正式 production 环境严格串行 3 次完成 `0.81/2.10 s`；两档检查点、状态、事件、输出契约和除计时外的诊断逐值一致，无非有限值或非预期回退。
- [x] 新主目标 `0.2 s` 性能报告完整记录环境、提交、工作树、输入哈希和统计口径。
- [ ] 浏览器/服务/worker 三条路径对权威 `0.2 s / 0.001 s` 均能完成且不会发生无证据的 60 s 假停滞；真实无活动仍能有界退出并提供诊断。

**前后对比**：

| 指标 | 当前 | 完成后 |
| --- | --- | --- |
| 正式锁定环境 | Python 3.12.3 + 22 包 hash lock | 空 venv 安装、`pip check`、依赖契约通过 |
| 复杂模型自动回归 | 新主目标 0.01/0.2 分层门禁 | 1/5/10 递进入口 + 历史 0.81/2.10 production 入口 |
| 物理解哈希 | 142 个状态键 × 3 检查点 | Python state golden 作确定性诊断 + output shape + AMESim 当次相对误差物理门 |
| `2.10 s` 连续成功率 | 3/3 | worker 墙钟 113.497–115.868 s，逐值一致且 0 回退 |

#### 2026-08-18 / AMESim 权威基线对齐与 OPT-00 收口

- 状态：部分实现 → 已完成（本地验收）。AME 归档固定 SHA-256 `cbc3aadd...`；XML/JSON 修正后的 SHA-256 分别为 `0a2d9331...`、`b44bf540...`，仿真配置统一为 `0→10 s / sampleStep=0.01 s / maxStep=0.001 s`。
- 权威契约：直接解析 AME 的 117 个 COMP 与 40 个建模 LINE，推导出 157 个项目节点、178 条连接、20 类组件和 1092 个参数；单位转 SI、表压转绝压、公式等价、DIRECT/接触/线模型拓扑以及 XML↔JSON 逐 ID/端口均有自动测试。
- 权威物理门：production `0.2 s` 每次都把当前 physical-state-v2.1 投影直接与 AMESim reference values 比较并保存相对误差；25 项参与判定，2 个 `t=0.04 s` 跳变流量保留误差但因左右极限语义不参与判定，另有 6 项无 AMESim 数据的内部守恒量单独执行绝对残差门。Python 142 个状态键 × 3 个检查点的 426 值 golden 仅作确定性诊断，不再批准物理正确性。
- 历史最终报告：`runs/2026-08-18-production-opt00-approved-replay-0.2.json`，SHA-256 `2e27cd54...`；worker/orchestration 墙钟 `159.607/160.473 s`。其中 Python 值零重放误差是确定性证据；物理结论以该次结果对 AMESim 的最差相对误差 `0.1393485%` 为准，最大质量守恒残差为 `1.82146e-17 kg/s`。
- 历史稳定性：production `0.81/2.10 s` 严格串行运行三次，所有 case 通过；`2.10 s` worker 墙钟分别为 `114.075/113.497/115.868 s`，机械事件时刻、检查点、1200 个状态值和除性能计时外的诊断逐值一致。
- 环境与自动化：新增 22 包 Linux x86_64 hash lock，并在全新空 venv 完成离线安装和 `pip check`；最终 quick workflow 同口径为 179 项通过（2 项预期跳过），完整后端为 849 项通过（3 项预期跳过）。
- 递进边界：由最终 `0.2 s` worker 时间按 `×5×1.5` 外推，`1 s` 为 `1197.053 s`，略低于 1200 s soft budget，因此记录为下一阶段 `eligible`；本次 OPT-00 不启动 1/5/10 s，后续长时递进仍归 OPT-09。
- 远端说明：workflow 已使用相同 hash lock 与测试命令；本轮未获授权提交/推送，因此没有声称远端 CI 已运行，提交后的首次托管运行作为运营证据补充。

#### 2026-08-17 / `test-mql-8` 固化 runner v2

- 状态：进行中 → 部分实现（P0 基础闭环）。新权威 XML/JSON、双哈希、结构快照、参考环境约束、分层 manifest、机器可读报告、批准的 production `0.2 s` golden 和仓库内 runner 已建立；发布级依赖锁、关键代数量投影以及该里程碑时尚未运行的 1/5/10 s 结果仍待后续。
- runner 行为：默认严格按 `0.01 smoke → 0.2 → 1 → 5 → 10 s` 递进；smoke 不参与耗时外推。soft deadline 先经 stdin 合作取消，hard deadline 再 terminate/kill；失败、超时、物理验收失败或下一档预测超过预算时，剩余档位统一标记 `deferred`。
- 已执行正确性门：完成并到达终点、非空且全有限的输出序列、采样时间严格递增、检查点及状态值、最大缩放残差、预期信号事件及其实际积分分段、机械切换次数/时刻、golden 来源报告与布局哈希、逐状态容差比较和独立 output-shape contract。
- 两条 lane：该 2026-08-17 里程碑的 manifest 中，`solver-only` 在内存把 `sampleStep` 改为 0.02 s，并把 `maxStep` 固定为 0.05 s，用于算法迭代；当时 SHA `170463d6...` 的 `production` 源值为 `sampleStep/maxStep=0.01/0.01 s`。当前 2026-08-18 权威 AME/XML/JSON 已统一为 `sampleStep/maxStep=0.01/0.001 s`；旧报告仅作历史证据。
- 进程鲁棒性：软取消、硬终止、子进程提前关闭 stdin 的 BrokenPipe 和 stdout/stderr 资源清理均有自动测试。
- 备份：`backup/general-solver-v1-before-20260817-16a7eb2` 精确指向进入本轮前的 `16a7eb2d6c2f01b23e3bdc7781a6cf6cc3fbe369`。
- P0 证据：`tests/baselines/simulation/test_mql_8/runs/2026-08-17-production-v2-0.2.json`、`goldens/production-0.2s-v1.json` 与 `runs/2026-08-17-production-v2-extension-decision.json`。
- 自动验证：CI 同口径快速基础套件共 149 项，OK（2 项长时测试按开关跳过）；全量后端 discover 共 792 项，OK（3 项长时/可选测试跳过）。原有 5 个失败均确认是仓库整理后的旧文档/XML/CSV 路径，并已修正为现有 fixture 路径。

递进复测命令：

```bash
PYTHONPATH=. .venv/bin/python -m app.simulation.benchmark_regression \
  --manifest tests/baselines/simulation/test_mql_8/manifest.json \
  --lane production \
  --output tests/baselines/simulation/test_mql_8/runs/latest-production.json
```

正式验收默认使用 `production`，从而对 `0.2 s` 当前结果执行 AMESim 权威物理基线比较；Python 数值 golden 同时输出确定性诊断但不作为物理通过依据。算法迭代若需降低输出成本，可显式改为 `--lane solver-only`。仅重跑首个正式基线档可加 `--case 0.2s`。
命令退出码约定：`0` 表示所有选定档完成，`2` 表示依据预算安全暂缓后续档，`1` 表示运行失败或正确性验收失败。显式选择 `1s/5s/10s` 时，runner 仍会自动补齐并先执行所有较短前置档。

### OPT-01 完成因果代数内核与坐标消元

**目标**：在已存在的因果快速路径上，真正移除运行时冗余坐标和对象访问，而不是再次实现一套同类快速路径。

**当前状态**：新主目标的主要矛盾已经在执行层闭环。原有 `760` 个 PortState 兼容代数槽由 `432` 个 effort 槽和 `328` 个 flow/force 槽组成；当前内核将其编译为 `112` 个 effort 等价组和 `328` 条显式赋值，即 `440` 个逻辑坐标，在求解执行层消去 `320` 个 effort 别名。全局与 secondary stream 块均使用预分配 workspace、按 component 批量计算 anchor 并直接 scatter，完整残差仍在初始化、事件和每 64 次求解时审计。

这里的“消去”是逻辑求解坐标消元：stream、状态导数和结果提取仍直接读取 `760` 个 PortState 兼容镜像，因此对象槽尚未物理删除；这属于 OPT-02 后续。旧 `472/204/68/200` 是历史 `test_mql-full-branches-01-04.xml` 的规模，只保留为历史基线，不再描述当前主目标。

**工作项**：

- [x] 将 112 个 effort 等价组压缩为独立逻辑坐标，在执行层消去 320 个重复 effort 别名。
- [x] 将 328 条显式 flow/force 规则预编译为稳定阶段和槽绑定。
- [x] 用预分配 workspace、批量 component anchor 和直接属性 scatter 减少热路径对象遍历、临时集合与重复缩放。
- [ ] 仅清理会被当前计划写入的槽，避免每次全量清零和复制。
- [x] 保留初始化、事件后、显式请求或固定间隔的完整残差审计。
- [x] 自定义组件、声明缺失、审计失败、非有限外部 effort 或奇异结构自动回退旧求解器。
- [x] 输出逻辑/兼容坐标数、消元数、显式规则覆盖率、审计率、失败原因和回退次数。

“仅清理当前计划写入槽”暂不勾选：当前 flow 目标仍先清零再赋值，以保持既有 `target = -residual(target=0)` 语义逐位一致；在 IR 能证明目标系数与历史无关前不移除这一步。

**验收条件**：

- [x] 新主目标因果 flow/force 覆盖率为 `328/328`，0.01/0.2 s 中审计、运行时验证和旧路径回退均为 0。
- [x] kernel on/off 的状态导数、760 个兼容代数槽、积分统计、物理解与输出契约一致。
- [x] 自定义组件、接触模型、非因果结构和故障注入的回退测试通过。
- [x] 在 0.01 s 与 production 0.2 s 证明端到端不退化并取得单次收益；严格性能签收仍需补 3 次中位数。

**风险与回滚**：别名写回、事件后模式改变和不完整依赖声明可能造成静默错误。新路径必须可通过配置关闭，并在审计失败时记录首个违规方程与变量。

| 指标 | 当前 | 完成后 |
| --- | ---: | ---: |
| 兼容代数槽 | 760 | 760（逻辑坐标 440） |
| 重复 effort 别名 | 320 | 逻辑消去 320；兼容镜像保留 |
| 已预热 Python 调用/单 RHS | 9,423 | 5,955（`-36.8%`） |
| 全局代数 solve 中位时间 | 0.708890 ms | 0.521711 ms（`-26.4%`） |
| 整体 RHS 中位时间 | 250.742 ms / 100 次 | 218.343 ms / 100 次（`-12.9%`） |
| 0.01 s worker 墙钟 | 13.5983 s | 12.5878 s（`-7.43%`） |
| production 0.2 s worker 墙钟 | 135.8240 s | 130.8233 s（单次 `-3.68%`） |
| 因果审计 / 运行时验证 / 旧路径回退失败 | 0 / 0 / 0 | 0 / 0 / 0 |

#### 2026-08-17 / 通用因果执行器 v2

- 状态：该段记录低分配执行器 v2 的首版里程碑；后续因果坐标内核已将新主目标的 `760` 个兼容槽压缩为 `440` 个逻辑坐标，OPT-01 当前已达到“基本完成（主要矛盾闭环）”。`760` 个 PortState 兼容镜像的物理删除仍属于 OPT-02 后续。
- 全局执行：直接执行预编译的 432 个 effort 写入与 328 个 flow/force 赋值，普通 fast solve 不再构造 seeded-id set、遍历 760 个未知量或重复构造 diagnostics。
- secondary 执行：对 352 未知量的因果块仅保存和写入 176 个 selected flow 槽，普通 fast solve 跳过完整 mutation snapshot、seed set 和 scale/residual 构造。
- 正确性边界：初始化、事件、显式请求及每 64 次求解仍执行完整残差审计；非有限 assignment、stage 异常或外部机械 x/v 非有限会熔断 v2，并在同次求解回到旧 seed/audit 路径。`SIMULATION_CAUSAL_EXECUTOR_V2=0` 保留一键回滚。
- 默认决策：在目标 0.01 s 逐位 A/B、故障注入、聚焦测试与完整 0.2 s 验收后，v2 设为通用默认；只在原有 causal compile 证明通过时启用，不满足证明的模型继续走原路径。
- 微基准：新目标 100 次同状态 RHS 中位时间由 0.305764 s 降至 0.247467 s（单次基准约 `-19.1%`），导数逐位相同；405 次 v2 fast、7 次完整审计，0 次验证失败。
- 0.01 s 端到端：SciPy Jacobian 下总墙钟 15.160 → 13.172 s（`-13.1%`），积分 14.092 → 12.122 s（`-14.0%`）；`nfev/njev/nlu=526/48/149`、物理解哈希 `0e64c6f...` 均相同。
- 历史 0.2 s solver-only：旧空格路径、SHA `42e2d627...` 与 0.002 s 网格下曾以 132.305 s 完成；报告 `runs/2026-08-17-solver-only-v1.json` 和旧 `runs/2026-08-17-extension-decision.json` 已在 manifest 中标为 `historicalOnly`，不得作为新权威输入的 golden 或耗时预测来源。
- 当前 production 0.2 s：新 SHA `170463d6...` 与 0.01 s 网格下 worker 墙钟 135.824 s、CPU 139.105 s、峰值 RSS 189,874,176 B；`nfev/njev/nlu=5755/307/1081`，接受步 1696，2 个信号分段，0 状态切换/重试。50,615 次闭合全部 seeded，主 v2 fast/audit 为 21,771/341，审计失败、运行时验证失败和旧路径回退均为 0，最大缩放残差 `1.0947e-16`。
- 当前 P0 报告与 golden：`runs/2026-08-17-production-v2-0.2.json` 通过全部验收门；`goldens/production-0.2s-v1.json` 对 134 个投影结果键的 3 个检查点共比较 402 个值，并独立校验 output contract。本目标仍使用 SciPy Jacobian，不能把该成绩归因于半解析 Jacobian。
- 当时的延期决策：`runs/2026-08-17-production-v2-extension-decision.json` 绑定新报告 SHA；`1 s` 的 1018.680 s 由 `135.8240278 × 5 × 1.5` 保守外推，超过 900 s soft budget，因此在该里程碑先未启动 1/5/10 s。后续实测结论统一记录在 OPT-09，不用该历史外推覆盖实测。

### OPT-02 建立扁平数值 IR 和数组执行内核

**目标**：把组件对象、字典查找和端口读写转换成稳定的数值执行计划，为 NumPy、Numba 或原生后端提供共同基础。

**当前状态**：已启动第一版独立、可执行的 schema v1 参考 IR，但尚未接管默认热路径。它把结构程序与运行绑定分离，包含 `440 canonical / 760 compatibility` 双层槽、稳定结构签名、NumPy workspace、按 component 批量 effort 计算、六阶段 flow 执行、逐阶段观察器和可选事务模式。权威目标可编译为 `112` 个 effort 坐标、`328` 个 flow 坐标和 `320` 个逻辑别名消元，flow stages 为 `[110, 130, 49, 33, 5, 1]`。

该原型目前只覆盖全局因果代数计划；secondary、stream、结果提取、模式重编译、自定义适配器和原生后端均未接入。PortState 仍是兼容镜像。事务模式目前只保证受控返回失败的回滚，writer/MemoryError/BaseException 语义尚未冻结；结构签名也未包含组件实现版本和后端，因此不能作为持久缓存键。

**工作项**：

- [x] 定义首批最小代数 IR：canonical/compatibility 双层槽、稳定绑定、常量和分阶段操作码。
- [ ] 将组件方程、因果规则、stream 传播和结果提取分成明确执行阶段。
- [x] 实现可执行的纯 Python/NumPy 全局因果参考后端。
- [x] 添加 IR 与当前对象执行器的结构签名、逐槽和逐阶段差分测试。
- [ ] 评估 Numba 与 C/C++ 后端；在 IR 稳定前不绑定单一编译技术。
- [ ] 对动态自定义组件保留对象适配层和明确的性能降级提示。
- [ ] 缓存编译结果，并以模型结构、组件版本和数值后端作为缓存键。

**验收条件**：

- [ ] 全部现有组件族通过新旧执行器差分测试。
- [ ] 事件切换后能正确重编译或选择预编译模式计划。
- [ ] 明显降低 Python 调用数、对象分配和 RHS 中位时间，并改善完整仿真墙钟。
- [ ] 不以牺牲异常信息、取消检查或回退能力换取速度。

| 指标 | 当前 | 原型后 | 完成后 |
| --- | ---: | ---: | ---: |
| Python 调用/单 RHS | 9,423 | 5,955（OPT-01 默认内核；参考 IR 尚未接线） | 待填 |
| 临时分配字节/单 RHS | 待测 | 待填 | 待填 |
| RHS 中位时间 | 250.742 ms / 100 次 | 218.343 ms / 100 次（OPT-01） | 待填 |
| `2.10 s` 积分时间 | 122.180 s | 待填 | 待填 |

#### 2026-08-17 / 因果数值 IR schema v1

- 新增独立参考实现 `app/simulation/solvers/causal_ir.py`，将结构程序与运行绑定分离，覆盖 `440 canonical / 760 compatibility` 双层槽、`112` 个 effort 坐标、`328` 个 flow 坐标、`320` 个逻辑别名及六阶段 flow 计划。
- `tests/test_causal_numeric_ir.py` 已覆盖结构签名、逐槽、逐阶段、观察器和受控事务回滚差分。
- 该 IR 尚未接管默认 RHS，当前不能把 OPT-01 的调用数或墙钟收益归因于 IR；secondary、stream、结果提取、事件后模式计划和原生后端仍待接入。

### OPT-03 稀疏 Jacobian 数值层与解析/半解析演进

**目标**：先建立可审计、可回滚的 callable sparse Jacobian 数值层，再逐步把组件、因果代数计划、stream 和物性的局部导数传播进来。完整稀疏有限差分、受审计 secant 和真正的解析/半解析 Jacobian 是三个不同阶段，必须分别记录和验收。

**当前状态**：数值层基础与实验候选已经实现；首批“证明门控”的三活塞 6 列半解析切片已经接入，但通用组件、stream SCC 和其余状态列仍未覆盖，因此 OPT-03 总体继续标记为“部分实现”。默认执行路径继续使用 SciPy `jac_sparsity`，半解析路径只允许通过 `SIMULATION_ODE_JACOBIAN_MODE=semi-analytic` 显式启用。

现有实现包括：

- direct 和 stepwise BDF/Radau 均可接收 callable `jac`；信号断点、状态事件和可恢复重启会清空 Jacobian 数值状态并重新构建，显式积分器完全忽略该对象。
- 新增独立的 sparse numerical Jacobian 内核，隔离并检查 SciPy 私有 `num_jac/group_columns` 接口。
- 每个 solver segment 记录完整构建、有限差分扰动、基准 RHS、Jv 审计、secant 复用/失败和装配时间；SciPy 模式的估计值不再伪装成 callable 模式的真实计数。
- 4 条无离散端挡模式歧义的机械运动学行直接装配为 `d(x')/d(v)=1`；带端挡的行继续数值差分。
- callable 内核新增 `exact_columns=(indices, provider)`：已提供精确导数的列从分组有限差分中移除，其余列仍按原始保守结构做 subset FD；原始色数、剩余色数、单次真实 FD、精确列构建及回退次数/原因都进入分段诊断。
- 精确列提供器用类型化 `ExactColumnsUnavailable` 表达当前点不可用；同一次构建会恢复原始 seed 0 的完整数值 Jacobian，避免把未知导数静默当成 0。模型编译证明失败、SciPy 私有接口不兼容或配置关闭时则直接保留原生 SciPy 路径。
- 首批目标是三条同构活塞支路的 6 个机械状态列 `(20, 21, 38, 39, 54, 55)`。编译器只有在组件类型、连接拓扑、因果赋值计划、机械等价组和 stream 影响范围都满足证明条件时才启用；该 XML 中共覆盖 34 条 reachable assignments，FD 颜色由 31 降至 25，另由提供器装配 6 列。
- 已增加 Ideal/PR 介质 `m/U/V` 物性线性化，以及 PNRP、PNCH012、PNL0001、LSTP、MECMAS 的局部切向原语；每个原语都返回 `valid/reason`，以便在非光滑接触、临界流动或不支持的模式上拒绝解析近似。
- Jacobian 内部每次 RHS 都执行取消检查；不安全的共享模型基准缓存已经撤销。随后实现的一次性 generation/dirty token 安全版本在正式 `0.81 s` 中 `253` 次 Jacobian 请求命中 `0` 次：BDF 首次构建前会做初始步长试算，后续构建前也会留下 Newton 试探状态，模型并不位于请求的基准点。该版本没有节省 RHS，最终也已删除。
- `SIMULATION_ODE_JACOBIAN_MODE=scipy` 是默认和回滚路径；小型全稠密结构或 SciPy 私有接口不兼容时也回到该路径。

显式 `SIMULATION_ODE_JACOBIAN_MODE=optimized` 仍构造完整稀疏有限差分 Jacobian，不使用 secant。最终实现严格固定 SciPy seed 0，并从原始 `1284 nnz` 保守结构生成 31 色扰动批次；移除精确行不会重新着色。曾试验的 seed 54 为 30 色，结构虽未删边，却改变了事件敏感模型的运行轨迹，因此多 seed 自动择优已经从代码中删除。

历史 30 色候选有性能收益，但没有通过事件/状态等价验收：

- 最终安全版本的 `0.81 s` 单次相邻 A/B 中，optimized 积分 `55.034 s`、总墙钟 `56.957 s`，SciPy 基线积分 `59.924 s`、总墙钟 `61.953 s`，分别约改善 `8.2% / 8.1%`。
- `0.81 s` 中 callable 实际 Jacobian RHS（扰动加基准）为 `7,103`，SciPy 估计为 `8,096`，约减少 `12.3%`；`nfev/njev/nlu` 为 `3467/228/670`，基线为 `3763/253/761`。
- 两条 `0.81 s` 轨迹具有相同结果键、采样时刻、0 次状态切换和约 `1e-16` 的最大代数残差，但最终 74 维状态的最大差异为 `51.59 × (atol + rtol·|y|)`，最差状态相对差约 `5.2e-5`，超过当前拟定的严格等价门槛。
- `2.10 s` optimized 仍成功越过 2.05 s，积分 `115.928 s`，而 SciPy 基线为 `122.180 s`；但 optimized 出现 `4` 次状态切换、`7` 次 solver 启动和 `215` 个样本，基线为 `2 / 5 / 213`。因此该候选的事件等价验收失败，不能设为默认。
- 短变体隔离显示：seed 0 callable（有或没有 4 条精确行）在 `0.01 s` 的最终 74 维状态与 SciPy 逐项一致；轨迹分叉来自 30 色 seed 54，而不是精确运动学行。这提示事件敏感模型需要更多运行中 Jacobian 漏边/弱依赖审计，不能只依赖初始点结构测试。

最终 seed 0 安全候选的正式 `0.81 s` 探针与 SciPy 基线具有相同的物理解哈希 `c6354c97...`、`3763/253/761` 的 `nfev/njev/nlu`、`1076` 个接受步、3 次 solver 启动、0 次状态切换和 `30,502` 次压力闭合。实际 Jacobian 内部 RHS 为 `7,872 + 253 = 8,125`；安全 token 缓存命中为 0。积分时间 `60.972 s`、探针总墙钟 `62.945 s`，相邻 SciPy 基线为 `59.924/61.953 s`，没有净收益并略有退化。因此安全缓存已删除，seed 0 callable 只保留为后续解析行接入与诊断基础，不进入默认路径；无需为一个已经失败收益门槛的候选继续做 `2.10 s` 性能复测。

`SIMULATION_ODE_JACOBIAN_MODE=hybrid` 另提供实验性的数值 secant 原型：最多连续复用一次，复用前执行确定性方向 Jv 审计，失败或审计无信息量会在同一次调用中完整刷新。目标模型的早期探针中候选审计普遍失败；用 seed 0 的旧完整 Jacobian 做 `0.01 s` 探针时，39 次复用审计全部失败，额外产生 39 次 Jv RHS，实际复用仍为 0。因此它目前既不是解析 Jacobian，也没有可声明的端到端收益。

**已完成的数值层工作**：

- [x] direct/stepwise BDF、Radau callable `jac` 接线；显式方法隔离。
- [x] breakpoint、事件、可恢复重启后的强制重建与分段计数。
- [x] 完整稀疏有限差分内核、严格 seed 0 着色、4 条安全精确行。
- [x] exact-columns subset FD、类型化同次完整回退和原始/剩余色数及回退诊断。
- [x] 真实 RHS/装配计数，以及 SciPy 估计口径分离。
- [x] Jacobian 内部有界取消检查；撤销不安全缓存及命中为 0 的安全 token 缓存。
- [x] 稠密结构、兼容问题和配置关闭时保留 SciPy 路径。
- [x] 最多一次复用、Jv 审计、无信息审计拒绝和失败完整刷新测试。
- [x] 复杂 XML `0.81/2.10 s` 单次性能与事件探针。
- [x] 同一代码版本完成 3 组相邻 `0.81 s` A/B，报告中位数与范围。
- [ ] 为事件敏感模型定义并通过状态、事件时刻/顺序和模式等价契约。
- [ ] 在正式锁定环境完成独立预热后的 3 次 A/B，复核中位数与离散度。

**解析/半解析后续工作**：

- [x] 为首批 Ideal/PR、PNRP、PNCH012、PNL0001、LSTP、MECMAS 路径定义带有效性诊断的局部切向契约。
- [x] 对目标三活塞 6 列沿 34 条可证明因果赋值传播导数，并从 FD 分组中排除这些列。
- [ ] 将局部导数/JVP 契约扩展到其余基础与自定义组件。
- [ ] 将因果传播推广到目标切片以外的状态列和代数计划。
- [ ] 对 stream SCC 推导显式或隐式小块导数。
- [ ] 对物性函数提供解析导数、可靠自动微分或受控局部差分接口。
- [ ] 在接触、饱和、开关和临界模式附近使用分段导数与局部回退。
- [ ] 对自定义组件缺失的导数声明生成明确诊断，不得静默置零。
- [ ] 在 `0.68–0.71`、`0.79–0.81`、事件两侧和 `2.00–2.10 s` 检查点执行稠密数值漏边审计与随机方向 JVP。

**验收条件**：

- [x] 历史 external-volume 跨域结构护栏与初始点稠密数值漏边测试继续通过。
- [x] callable 接线、分段重置、取消、显式方法隔离、secant 上限和审计失败回退有自动测试。
- [ ] `0.81/2.10 s` 的连续状态、事件时刻/顺序、模式和残差满足统一契约；当前 30 色候选未通过。
- [ ] 默认候选在锁定环境的 3 次中位墙钟有净收益，小模型无显著退化。
- [x] 首批目标切向原语和 6 列通过逐列中心差分、模式分支与局部回退验证。
- [ ] 通用组件级解析/半解析导数通过随机方向 JVP、逐列抽查和局部回退验证。

**风险与回滚**：历史 external-volume 漏边说明“颜色更少”本身不是正确性证据。不同合法颜色组合也可能暴露保守结构中未声明的弱依赖，并改变非光滑接触附近的事件序列。默认保持 `scipy`；`optimized/hybrid` 仅显式实验。非光滑点的解析或 secant 近似未必可靠，事件分段重置、审计和旧路径必须长期保留。

| 历史实验指标 | SciPy 基线 | 已撤销的 30 色候选 | 验收 |
| --- | ---: | ---: | --- |
| 保守结构 / 实际 FD 颜色 | 1284 nnz / 31 | 1284 nnz / 30（seed 54） | 结构不删边 |
| 精确装配行 | 0 | 4 条运动学行 | 短变体证明不改变轨迹 |
| `0.81 s` Jacobian RHS（含基准） | 估计 8,096 | 实际 7,103 | `-12.3%` |
| `0.81 s` `nfev/njev/nlu` | 3763 / 253 / 761 | 3467 / 228 / 670 | 工作量下降 |
| `0.81 s` 积分 / 总墙钟 | 59.924 / 61.953 s | 55.034 / 56.957 s | 单次约 `-8.2% / -8.1%` |
| `0.81 s` 最大最终状态误差尺度 | 参考 | 51.59 | 未通过 |
| `2.10 s` Jacobian RHS（含基准） | 估计 15,584 | 实际 14,556 | `-6.6%` |
| `2.10 s` `nfev/njev/nlu` | 6734 / 487 / 1507 | 6606 / 468 / 1469 | 工作量小幅下降 |
| `2.10 s` 积分时间 | 122.180 s | 115.928 s | 单次约 `-5.1%` |
| `2.10 s` 状态切换 / solver 启动 / 样本 | 2 / 5 / 213 | 4 / 7 / 215 | 未通过 |

| 最终安全候选指标（`0.81 s`） | SciPy 基线 | seed 0 callable | 验收 |
| --- | ---: | ---: | --- |
| 保守结构 / FD 颜色 | 1284 nnz / 31 | 1284 nnz / 31（seed 0） | 相同扰动批次 |
| `nfev/njev/nlu` | 3763 / 253 / 761 | 3763 / 253 / 761 | 相同 |
| 接受步 / solver 启动 / 状态切换 | 1076 / 3 / 0 | 1076 / 3 / 0 | 相同 |
| 压力闭合 | 30,502 | 30,502 | 相同 |
| 物理解哈希 | `c6354c97...` | `c6354c97...` | 通过 |
| 安全基准 RHS 缓存命中 | 不适用 | 0 / 253 | 无收益，代码已删除 |
| 积分 / 探针总墙钟 | 59.924 / 61.953 s | 60.972 / 62.945 s | 略有退化，未通过收益门槛 |

#### 2026-08-17 / 工作树基于 `6bb0591d`

- 状态：未开始 → 部分实现（数值接入层完成；30 色候选未通过事件等价，seed 0 候选未通过收益门槛；解析/半解析传播未开始）
- 代码备份：`backup/jacobian-before-20260817-6bb0591`，精确指向 `6bb0591d320d0c448ee8d224dd44127bfe3ce00f`。该分支只备份 tracked 代码基线，不包含当时未跟踪的本文档。
- 运行环境：Python 3.12.3、NumPy 2.4.6、SciPy 1.17.1；输入 SHA-256 `2fb95e65...`；`2.10 s` 仅内存覆盖停止时间，磁盘 XML 未修改。
- 正确性结果：Jacobian 内核、core solver、Generic sparsity 和 Generic XML 共 57 项通过；压力因果、stream 块、机械接触、PNRP17、代数稀疏与方程块另 52 项通过，external-volume 漏边护栏继续通过。热流体闭合计划 13 项中 12 项通过，剩余 1 项因用户已将 fixture 移至 `tests/data/fixtures/`、旧测试仍读取 `tests/fixtures/` 而报既有 `FileNotFoundError`，与本次改动无关。30 色候选在 `2.10 s` 的事件数由 2 变为 4；最终 seed 0 候选在 `0.81 s` 恢复相同物理解哈希与求解统计。
- 性能结果：见上表。数字均为同机相邻单次结果，不是 3 次中位数；最终 seed 0 候选没有减少求解工作并略慢。
- 卡死结果：历史 30 色探针在 `2.040187 s @ 106.499 s`、`2.051323 s @ 113.996 s`、`2.065299 s @ 115.472 s` 持续推进并完成到 2.10 s；默认 SciPy 的正式探针同样越过 2.05 s 并完成，无重试、无死锁。
- 安全收口：默认保持 SciPy；移除多 seed 自动择优、不安全共享缓存和零命中的安全 token 缓存；Jacobian 内部保留取消检查；无信息 Jv 审计强制刷新；显式 solver 不观察或重置 Jacobian。
- 决策：保留严格 seed 0 的 callable/诊断/精确行基础和显式实验开关；30 色、基准缓存与 secant 均不进入默认路径。下一阶段优先建立多检查点弱依赖审计和组件级局部导数，不再以颜色数或数值缓存单独作为优化成功标准。
- 证据文件：`app/simulation/solvers/jacobian.py`、`app/simulation/solvers/solver.py`、`app/simulation/systems/generic.py`、`tests/test_sparse_secant_jacobian.py`、`tests/test_core_solver.py`、`tests/test_generic_jacobian_sparsity.py`、`tests/test_generic_system_xml_simulation.py`

#### 2026-08-17 / 首批三活塞半解析 6 列切片

- 状态：部分实现 → 部分实现（首批目标切片完成并通过局部导数验证；OPT-03 的通用解析/半解析覆盖尚未完成）。
- 实现范围：新增 exact-columns subset FD 接口、类型化同次完整数值回退和分段诊断；为三条目标活塞支路编译状态列 `(20, 21, 38, 39, 54, 55)`，沿 34 条可达因果赋值传播切向量，使剩余 FD 颜色从 31 降到 25。
- 局部导数：实现 Ideal/PR 介质 `m/U/V` 物性线性化，以及 PNRP、PNCH012、PNL0001、LSTP、MECMAS 的几何、压力、质量/能量、流量/力和接触模式切向原语；原语显式报告 `valid/reason`。
- 证明与回退：组件类型、连接拓扑、因果计划、机械组和静态 stream 影响范围必须全部满足编译证明。causal/stream/custom/兼容性证明不成立时不安装 callable，继续使用原生 SciPy；运行点进入非光滑接触边界、临界流动、陈旧 primal 或其他不支持模式时抛出类型化 `ExactColumnsUnavailable`，同一次构建恢复原始 seed 0 完整数值 Jacobian。任何不可证明项都不会静默填 0。
- 配置边界：默认仍为 `SIMULATION_ODE_JACOBIAN_MODE=scipy`；首批路径仅通过 `semi-analytic` 显式 opt-in，不替换生产默认值。
- 自动测试：focused 套件 86 项、adjacent 套件 164 项，共 250 项通过。热流体 closure 计划另为 12/13 项通过；唯一失败仍是旧测试读取 `tests/fixtures/`、而 fixture 已被用户移至 `tests/data/fixtures/` 导致的既有 `FileNotFoundError`，与本轮 Jacobian 改动无关。
- 局部正确性：在平滑检查点，SciPy 分组有限差分漏掉 `J[19,20] ≈ -3201.486`；半解析列相对独立中心差分的最大相对误差为 `1.897e-8`。inactive/active 接触分支、过期 primal、非因果计划和不支持拓扑均覆盖了成功或回退路径。
- 轨迹正确性：默认容差下，两条 `0.81 s` 轨迹最差点为 `t=0.65 s` 的能量状态 `state[33]`，原始相对差 `8.24e-5`，缩放误差 `82.36`；事件数和顺序一致，但尚未满足拟定的严格逐点轨迹门槛。提高精度后互差收敛：`rtol=1e-7` 时最大绝对/相对差为 `0.081965 / 1.592e-6`，`rtol=1e-8` 时为 `0.0175357 / 3.09062e-7`，分别缩小约 `4.67× / 5.15×`，且两组事件均一致。这支持“求解路径差异随容差收敛”，但不足以把候选升为默认。
- 性能口径：`0.81 s` 已在同机、同一工作树连续完成 3 组相邻 A/B；表中时间为中位数，括号给出 3 次范围。测试使用现有 `/opt/srm-trial-review/.venv`，没有独立预热且依赖版本未由项目锁文件固定，因此仍需在正式锁定环境复核，不能单独作为切换默认值的依据。`2.10 s` 为最终 one-shot primal 捕获版本的单次复跑；此前数学路径相同的预备运行墙钟为 `111.068 s`，本次为 `116.512 s`，长程时间仍需重复测量。

| 最终 `0.81 s` 三次指标 | SciPy 基线 | `semi-analytic` 候选 | 变化/说明 |
| --- | ---: | ---: | --- |
| FD 颜色 / 精确状态列 | 31 / 0 | 25 / 6 | 目标列为 20、21、38、39、54、55 |
| `nfev/njev/nlu` | 3763 / 253 / 761 | 3650 / 228 / 711 | 求解工作下降 |
| 接受步 / solver 启动 / 状态事件 / 样本 | 1076 / 3 / 0 / 82 | 1056 / 3 / 0 / 82 | 事件和输出网格一致 |
| Jacobian RHS | 8,096（估计） | 5,985（实计） | `-26.1%` |
| 精确列构建 / 类型化回退 | 不适用 | 224 / 4 | 4 次恢复完整数值构建 |
| 压力闭合 | 30,502 | 25,672 | `-15.8%` |
| 积分时间中位数（范围） | 59.725 s（59.568–60.188） | 55.631 s（55.432–56.307） | 中位数 `-6.85%` |
| 总墙钟中位数（范围） | 61.203 s（61.070–61.704） | 56.708 s（56.508–57.410） | 中位数 `-7.34%`；逐组改善 6.96%–7.47% |

| 延长至 `2.10 s` 单次指标 | SciPy 基线 | `semi-analytic` 候选 | 变化/说明 |
| --- | ---: | ---: | --- |
| 状态 | 完成，越过 2.05 s | 完成，越过 2.05 s | 最终版本越过 2.05 s 的墙钟为 111.660 s |
| `nfev/njev/nlu` | 6734 / 487 / 1507 | 6246 / 445 / 1328 | 求解工作下降 |
| 接受步 | 1857 | 1753 | `-104` |
| solver 启动 / 状态切换 / 样本 | 5 / 2 / 213 | 5 / 2 / 213 | 事件计数和输出网格一致 |
| Jacobian RHS | 15,584（估计） | 11,771（实计） | `-24.5%` |
| 类型化回退 | 不适用 | 26 | 非平滑/不支持点恢复完整数值构建 |
| 压力闭合 | 57,601 | 48,248 | `-16.2%` |
| 积分时间 | 122.180 s | 112.825 s | 单次 `-7.7%` |
| 总墙钟 | 126.211 s | 116.512 s | 单次 `-7.7%` |

- 卡死复核：最终 `semi-analytic` 候选在墙钟 `111.660 s` 越过模拟时刻 `2.05 s`，随后于 `116.512 s` 完成到 `2.10 s`；与 SciPy 基线一样未出现无进度死锁。
- 未覆盖范围：通用 stream SCC 导数、目标三支路以外的组件/状态列、自定义组件导数契约、正式锁定环境的独立预热复测，以及 `10 s` 长时模式覆盖。
- 决策：保留首批半解析切片和自动回退作为显式实验路径；OPT-03 继续为“部分实现”，默认继续使用 SciPy。完成上述通用覆盖、严格轨迹契约和重复基准前，不切换默认值。
- 代码备份：仍使用进入 Jacobian 优化前建立的 `backup/jacobian-before-20260817-6bb0591`，精确指向 `6bb0591d320d0c448ee8d224dd44127bfe3ce00f`。
- 证据文件：`app/simulation/solvers/jacobian.py`、`app/simulation/solvers/tangent.py`、`app/simulation/solvers/solver.py`、`app/simulation/systems/generic.py`、`app/simulation/core/medium.py`、`app/simulation/components/amesim/media/mediums.py`、`app/simulation/components/amesim/mechanical/pistons.py`、`app/simulation/components/amesim/storage/chambers.py`、`app/simulation/components/amesim/flow/pipes.py`、`app/simulation/components/amesim/mechanical/translational.py`、`tests/test_sparse_secant_jacobian.py`、`tests/test_analytic_tangent_primitives.py`、`tests/test_three_piston_tangent.py`

#### 2026-08-17 / 名字无关的受支持活塞支路编译器

- 将原三条固定实例扩展为按组件类型、端口域、连接、机械状态 owner/slot、因果 reach 与 stream 影响证明自动发现任意数量的受支持支路；通用路径不固定组件实例名、支路数或状态 offset，旧三活塞入口仅作为兼容 wrapper。
- 新主目标自动发现 8 条 MECMAS21→PNRP17→PNCH012→PNL0001/LSTP 支路，覆盖 16 个机械状态列 `104..119` 与 84 条可达赋值；理论剩余 FD 颜色由 52 降至 36。
- 平滑工作点 16 列对完整 RHS 中心差分通过；初始接触边界会类型化回退完整 52 色数值 Jacobian，不会静默使用错误列。
- 0.01 s A/B 显示该目标早期 56 次 Jacobian 中只有 16 次使用精确列、40 次因流量局部斜率/接触边界安全回退；单独半解析总墙钟为 17.522 s，慢于 SciPy 的 15.160 s。当前目标因此继续使用默认 SciPy Jacobian，半解析保持显式 opt-in，下一步应做支路分区回退或扩大光滑模式覆盖，而不是放宽守卫。

### OPT-04 stream 拓扑传播与物性成组复用

**目标**：让无环 stream 网络一次传播，只对真正的强连通块迭代；同一状态反算的物性量成组计算和复用。

**当前状态**：stream 求解器已预绑定组件、端口和连接，物性层也有单次运行精确缓存；但每次求解仍构造临时字典/列表、重复调用连接焓计算，尚未编译 SCC/DAG。热流体外层固定点上限仍为 25 次：production `0.2 s` 实测最多 3 次，修复后延长到 `2/5/10 s` 实测最多 18–23 次；修复前在 `t≈1.8595–1.8603 s` 会耗尽 25 次。当前已补充试探点事务回滚和类型化可恢复失败，并由 StreamResolver 为所有覆盖温度参考更新钩子的组件统一刷新连接参考；SCC/DAG 传播与物性成组复用尚未实现。

**工作项**：

- [ ] 构建 stream 图的 SCC，并将缩点图编译为拓扑顺序。
- [ ] 对单节点和无环段使用一次传播，仅在循环 SCC 内迭代。
- [ ] 使用预分配数组和原地误差统计，避免每轮临时字典/列表。
- [ ] 缓存同一求解阶段的连接焓结果，避免返回前重复计算。
- [ ] 将 `p/T/rho/h/s` 等同源物性组织为状态包，按精确输入键成组复用。
- [ ] 增加缓存命中、SCC 迭代、失效原因和物性调用次数指标。
- [ ] 评估脏标记传播，但必须证明事件和反向流切换时不会复用陈旧值。
- [x] 为热流体外层 25 次耗尽提供类型化可恢复失败和单次 RHS 事务回滚，避免失败试探点污染下一次尝试；这是鲁棒性前置，不代表 SCC/DAG 优化已经完成。
- [x] StreamResolver 按组件行为预编译所有覆盖 `update_flow_temperature_references` 的组件，并在每轮 stream 更新后统一刷新温度参考；物理岛边界同时识别 stream outflow 与温度参考钩子覆盖。

**验收条件**：

- [ ] 无环、单环、多环、反向流和事件后拓扑测试全部通过。
- [ ] 复杂模型的最大 stream/热流体迭代不增加，残差不恶化。
- [ ] 量化减少物性调用、临时分配、压力闭合或 RHS 时间。

| 指标 | 当前 | 完成后 |
| --- | ---: | ---: |
| stream 块 / 未知量 | 9 / 192 | 待填 |
| 最大热流体迭代 | production 0.2 s：3；修复后 2/5/10 s：18–23；恢复阈值：25 | 待填 |
| `2.10 s` 压力闭合 | 57,601 | 待填 |
| 物性调用 / 缓存命中率 | 待测 | 待填 |

### OPT-05 最大积分步长路径鲁棒性、状态缩放和步长策略

**目标**：首先保证在合理 `maxStep` 工程区间内，步长上限只影响可解释的误差和成本，而不决定仿真能否完成；随后再减少量纲差异造成的不必要小步和 Jacobian 重建，同时维持事件与守恒精度。

**当前状态**：P0 阻断、先定位。模型中不同物理量的量级差异大。历史试验显示机械绝对容差放宽可能带来约 16% 收益，但属于精度策略变化；热流体固定点容差的简单放宽曾使表现变差，不能直接采用。当前已先完成不改变容差契约的可恢复试探步：按积分器实际 `h_abs` 对半退避，并在首次接受后恢复分段步长上限。Generic 显式 opt-in，即使模型无状态事件、断点或取消回调，也会进入支持重建的 stepwise 路径；普通 `integrate_ode` 调用者的默认路径不变。权威浏览器场景 `BDF / 0.2 s / sampleStep=0.01 s / maxStep=0.001 s` 当前在 `t≈0.0489 s` 计算超时，已构成工程失败；尚须用同 JSON 的 browser/API/worker A/B 定位其属于数值热点、服务假超时或二者叠加。既有 `2 s` 矩阵没有覆盖 `0.001 s`，也未系统验证时域延长与步长细化不变量，不能替代本次 P0 门。

**工作项**：

- [ ] 按状态物理量、标称值和工程容差建立分量 `atol`/缩放规则。
- [ ] 为未提供标称值的组件定义安全默认值并输出诊断。
- [ ] 分开积分误差、代数残差、stream 固定点和事件定位容差。
- [ ] 统计限制步长的状态分量、误差拒步和 Jacobian 重建原因。
- [ ] 对事件前后、接触临界区和稳态区分别评估步长上限策略。
- [ ] 建立严格/标准/快速配置，但默认配置必须有明确精度契约。
- [ ] 用完全相同的 JSON 生成请求，对浏览器流式路径与 production worker 做同参 A/B，逐层核对 requested/effective `tStop/sampleStep/maxStep/method`。
- [ ] 围绕 `t=0.04–0.05 s` 按模拟区间记录 BDF 阶次、实际 `h_abs`、接受/拒绝步、重启、Jacobian/RHS/闭合耗时及最坏组件，定位 `0.0489 s` 的首次性能悬崖。
- [ ] 在改变算法前提交定位报告与候选方案供审阅，明确证据、影响面、正确性风险、预期计数变化和回退方式；获准后只实施一个概念，并以原失败单元及同一行/列相邻配置做 A/B。
- [ ] 审计失败试探的事务恢复、缓存、端口和离散模式，证明失败点不会污染下一条缩步路径。
- [ ] 只在证据支持时对事件、接触、流向或闭合边界使用局部步长上限、有界缩步或模式感知策略；禁止靠全程硬编码某个“幸运” `maxStep` 收口。
- [ ] 将第 3.4 节的 `0.2/1 s × 五档` 二维矩阵设为每次步长/缩放改动的 P0 回归；短时通过后再按 `2/5/10 s` 逐级验证公共前缀。
- [x] 对可恢复的热流体闭合失败使用积分器实际试探步 `h_abs` 对半回退；最多 16 次且不低于 64 ULP，恢复步仅设置 `first_step`，首次接受后恢复分段 `maxStep` 上限并记录 attempted/next step。
- [x] 为 eventless Generic 显式启用 `recoverable_trial_retries`，使没有状态事件、断点或取消回调的通用模型也能选择 stepwise 恢复；该参数默认关闭，避免改变其他调用者的直接 `solve_ivp` 语义。

**验收条件**：

- [ ] 每个配置都有状态、事件、残差和守恒误差界限。
- [ ] 标准配置在复杂模型上减少拒步或分解工作，不引入模式遗漏。
- [ ] 所有收益报告同时给出误差变化，禁止只报告墙钟。
- [ ] 满足第 3.4 节 P0 门：短时二维矩阵满足时域延长与步长细化不变量，事件/模式/守恒满足分类契约，任何性能悬崖都有可复现的阶段与组件归因。

### OPT-06 事件检测与 dense output 按需化

**目标**：避免在绝大多数没有事件候选、也不跨输出采样点的接受步上创建 dense output。

**当前状态**：已有事件候选筛选和部分非事件优化，但只要存在状态转换处理器，接受步仍可能构造 dense output。`2.10 s` 有 1857 个接受步而只有 2 次状态切换，存在减少插值构造的空间。

**工作项**：

- [ ] 在构造 dense output 前执行低成本端点符号/模式候选检查。
- [ ] 仅在跨输出采样点或存在事件候选时创建插值器。
- [ ] 将输出插值与事件定位的生命周期和精度需求分离。
- [ ] 统计候选数、误报数、定位次数、dense output 构造数和耗时。

**验收条件**：

- [ ] 同时事件、擦边事件、抖动防护和多模式顺序测试通过。
- [ ] 事件时刻误差不超契约，事件顺序和最终模式不变。
- [ ] 完整模型 dense output 构造数与耗时明显下降。

### OPT-07 输出、后处理和传输内存优化

**目标**：在长仿真中控制结果生成、JSON 编码、前端复制和峰值内存。

**当前状态**：当前模型有 1,021 个结果变量；`10 s / 0.01 s` 约产生 1,022,021 个标量。现路径会对每个样本重新闭合、追加全部结果，并把完整结果作为一个 NDJSON 消息发送。它不是本次 2.05 s 慢推进的主因，但会成为长时间运行的显著成本。

**工作项**：

- [ ] 支持结果变量白名单、分组和按需派生量。
- [ ] 将积分内部采样、结果存储采样和显示采样分离。
- [ ] 对显示路径提供服务端降采样，同时保留可选完整数据模式。
- [ ] 分块编码和传输结果，或返回 `resultId` 后分页/流式获取。
- [ ] 评估前端 TypedArray/列式数据，减少嵌套对象和重复复制。
- [ ] 避免后处理中对每个样本重复执行不必要的完整闭合。
- [ ] 记录原始标量数、编码/传输字节数、后处理时间和峰值 RSS。

**验收条件**：

- [ ] 完整输出模式保持现有 API 契约，或通过显式版本升级迁移。
- [ ] 精简模式的变量选择和降采样行为可预测、可测试。
- [ ] `10 s` 基准中后处理时间、传输字节和峰值 RSS 有量化改善。

### OPT-08 进度、取消和服务并发鲁棒性

**目标**：区分“内部慢步”和“真正无进度”，并让长任务可取消、可限流、不会拖垮服务进程。

**当前状态**：P0 服务门进行中。已有 stream 进度和取消检查；前端无接受步进度阈值约 60 s。历史 2.05 s 附近可见最大间隔约 7.5 s，且中间有接受步与 CPU 活动，因此没有触发真实无进度条件。当前又补充了热流体失败位置、迭代尾部、最差端口及求解器恢复轨迹；`5 s / maxStep=0.05 s` 在 1200 s soft budget 后合作取消并保留 `t=4.2523535 s` 的部分诊断，属于预算终止而非 solver failure。单格 max-step 矩阵不再把“没有跨步长比较对”误判为失败。权威 `0.2 s / 0.001 s` 浏览器运行当前在 `t≈0.0489 s` 计算超时，浏览器工程门已经失败；但根因尚未确定，必须追踪前端 60 s 计时器、NDJSON 心跳、API worker 与内部求解活动，不能直接等同于求解器死锁。

**工作项**：

- [ ] 分别上报模拟时间、接受步、内部 RHS/闭合活动和墙钟心跳。
- [ ] 将“运行中但步很慢”与“求解器无活动”使用不同状态和超时策略。
- [ ] 在代数闭合、stream 迭代、Jacobian 构建和后处理内加入有界取消检查。
- [ ] 限制并发仿真 worker、队列长度和单任务 CPU/内存预算。
- [ ] 超时报告最后活动阶段、模拟时刻、步长和关键计数，而非只返回通用错误。
- [ ] 添加故意慢 RHS、死循环防护、客户端断连和多任务竞争测试。
- [ ] 将活动心跳从“接受新积分步”扩展到 RHS、Jacobian 构建、stream/热流体闭合和恢复循环；至少携带 phase、wall time、last accepted time、current RHS time、`h_abs`、`nfev` 与闭合迭代。
- [ ] 验证客户端流断开、浏览器本地 watchdog 和显式取消的语义不同；客户端误判或断连不得在无用户授权时静默丢失仍健康运行的 worker 结果。
- [x] 热流体失败记录 RHS 时刻、最近迭代尾部、最大增量/尺度/容差、最差端口及带符号差值，并保留求解器逐次恢复的 attempted/next step 与原因。
- [x] 矩阵报告分别记录外层 `soft_timeout` 和 worker 的合作 `cancelled`，避免把预算取消误记为求解器数值失败。
- [x] 单格 max-step 矩阵将空的跨步长比较集合视为“不适用”而非失败；最终 `2 s / 0.02 s` 单格复验整体通过且 `comparisonFailureCount=0`。

**验收条件**：

- [ ] 正常慢步不会被误判为死锁，真实无活动能在约定时间内终止并给出诊断。
- [ ] 取消请求在每个主要阶段都能在有界时间内生效。
- [ ] 并发压力下服务仍能响应健康检查和新请求拒绝/排队逻辑。
- [ ] 权威 `0.2 s / 0.001 s` 浏览器路径完成且不发生假超时；只要内部活动持续，60 s 无接受步不得触发 `SOLVER_STALLED`，真正无活动仍能按约定上限停止并返回最后阶段与计数。

### OPT-09 建立 10 s 长时验证与模式覆盖

**目标**：用权威 JSON 的 `BDF / tStop=10 s / sampleStep=0.01 s / maxStep=0.001 s` 完整实测，替代“短仿真或较大 `maxStep` 可以外推到最终工程场景”的假设。

**当前状态**：权威 `0.001 s` 长基线尚未完成。既有 `10 s / maxStep=0.02 s` 只作为算法可行性、恢复机制和历史性能证据，不能签收当前 JSON 的工程基线。此前新主目标的 solver-only `1 s / maxStep=0.05 s` 已完成，worker 墙钟 `182.111 s`。修复前，`tStop=2 s` 与 `tStop=5 s` 在同一 `maxStep=0.05 s` 下具有相同的首次失败时刻和求解统计，均在 `t=1.859512845 s` 耗尽热流体外层 25 次；四档 `maxStep` 的失败时刻集中在 `1.8595–1.8603 s`。这说明远端 `tStop` 不是直接失败原因，它只决定运行是否到达该局部数值困难区。

PNL00R stream 语义、单次 RHS 事务回滚和基于实际试探步的恢复完成后，production `2 s` 的 `maxStep=0.01/0.02/0.05/0.10 s` 四个单元均到达 `2.0 s`，`caseFailureCount=0`。矩阵命令整体退出码仍为 1，原因是跨 `maxStep` 的严格状态一致性门未通过，而不是任何单元运行失败：差异集中在事件后的 8 个 MECMAS21 速度和 8 个加速度；在差异最大的一组跨 `maxStep` 终点比较中，绝对差约 `1.01e-6–1.12e-6`。`0.05/0.10 s` 两档则逐位一致。因此当前结论是“2 s 运行失败已解决”，但“跨步长数值等价”尚未签收，不能据此批准长时 golden。

`5 s / maxStep=0.02 s` 已完成，worker 墙钟 `696.418 s`，0 次可恢复重试，最大热流体迭代 19，`nfev/njev/nlu=18736/1347/4988`。`maxStep=0.05 s` 在 1200 s soft budget 后由 runner 合作取消，停止于 `t=4.2523535 s`，此前仅发生 1 次已成功恢复的试探步；它是有界预算结果，不是 solver failure，也不能与已完成的 `0.02 s` 单元做终点一致性签收。形成该阶段记录时，`10 s / maxStep=0.02 s` 尚在运行；完成结果及其后追加的通用接线复验见下方收口记录。

| `tStop` | `maxStep` | lane / 结果 | worker 墙钟或预算 | 可恢复重试 | 说明 |
| ---: | ---: | --- | ---: | ---: | --- |
| 1 s | 0.05 s | solver-only / 完成 | 182.111 s | —（旧版未记录） | 首次延长门通过 |
| 2 s | 0.01 s | production / 完成 | 324.727 s | 8 | 最大热流体迭代 19 |
| 2 s | 0.02 s | production / 完成 | 292.035 s | 0 | 首次 recovery 矩阵当时最快；最大热流体迭代 19 |
| 2 s | 0.05 s | production / 完成 | 450.425 s | 1 | 最大热流体迭代 18 |
| 2 s | 0.10 s | production / 完成 | 448.033 s | 1 | 与 0.05 s 路径逐位一致，上限未实际约束 |
| 2 s | 0.02 s | production / 最终通用接线复验完成 | 301.782 s | 0 | 2 次事件；单格矩阵整体通过 |
| 5 s | 0.02 s | production / 完成 | 696.418 s | 0 | 最大热流体迭代 19；`18736/1347/4988` |
| 5 s | 0.05 s | production / soft budget 合作取消 | 1200 s | 1 | 停止于 4.2523535 s；不是 solver failure |
| 10 s | 0.02 s | production / 历史：最终通用接线前单元完成 | 803.622 s | 0 | 接线前历史证据，不作为最终性能口径 |
| 10 s | 0.02 s | production / 最终通用接线后完成 | 1602.733 s | 1 | orchestration 1604.152 s；`45455/3075/15282`；接受步 9569；启动 6；事件 2 |

#### 2026-08-17 / PNL00R 正确性、热流体事务与实际步长恢复

- PNL00R 的端口温度参考改为同侧连接对端的温度参考焓：连接到 node 时使用对端组件的 `temperature_reference_h`，普通组件则使用常规 `connected_h`（即连接端口的 `h_outflow`）；零容积元件自身的 `h_outflow` 仍保持对侧传播语义。42 项 PNL00R/stream 相关测试通过。
- 单次 RHS 事务会回滚物理端口、flow、物性缓存、因果绑定及相关诊断，防止失败试探点污染下一次尝试。只有热流体外层 25 次耗尽被分类为可恢复错误；`StreamSolveError` 和 secondary `AlgebraicSolveError` 仍保持致命错误语义。
- 事务开销的 7×100 RHS 微基准为关闭 `0.813488 s`、开启 `0.829156 s`，增加 `1.926%`，导数逐位一致。
- 聚焦组合回归共 163 项通过、1 项跳过。修复后 production `0.2 s` worker 墙钟 `128.296 s`，402 个 golden 值通过，最大绝对差 `0.0171461`、最大容差比 `0.151304`，output contract 不变。
- 证据：`runs/2026-08-17-production-thermofluid-recovery-v1-0.2.json`、`runs/2026-08-17-production-2s-max-step-matrix-v1.json`、`runs/2026-08-17-production-2s-max-step-matrix-recovery-v2.json`、`runs/2026-08-17-production-5s-max-step-matrix-recovery-v1.json`。

#### 2026-08-17 / 最终通用接线后的 `10 s` repeat 与收口

- 最终通用接线后的 `runs/2026-08-17-production-10s-max-step-0p02-general-recovery-v3.json` 完成到 `10.0 s`：worker 墙钟 `1602.733 s`、orchestration 墙钟 `1604.152 s`，`nfev/njev/nlu=45455/3075/15282`，接受步 9569，solver 启动 6 次，2 次状态事件。运行在 `t=6.9640458 s` 发生 1 次热流体可恢复失败并以 1 次重试继续完成，最大热流体迭代 23，最大缩放残差 `1.082e-16`；1717 条序列、1,722,151 个标量全部有限。
- `runs/2026-08-17-production-10s-max-step-0p02-recovery-v1.json` 的 worker `803.622 s` 结果明确属于上述两项最终通用接线之前的历史运行，只保留为阶段性正确性和故障定位证据，不作为最终版本的性能数据。
- 该接线前历史 10 s 报告的运行单元和 case acceptance 均通过，但旧版单格矩阵因 `sameHorizonAcrossMaxSteps=[]` 被空比较器误判，导致报告顶层 `passed=false` 和旧退出码 1；这不是仿真或数值验收失败。空比较器缺陷已经修复，最终接线后的 10 s repeat 与 `2 s / maxStep=0.02 s` 单格报告均整体 `passed=true`；后者另明确记录 `caseFailureCount=0`、`comparisonFailureCount=0`。
- 旧 10 s 报告生成时曾根据目标的状态事件与拓扑边界推断两项最终接线不会改变已覆盖边界；该推断作为历史说明保留，现在已由最终接线后的完整 10 s repeat 直接取代。
- 最终接线前后 `0.01 s` 输出逐值一致。两次 production `0.2 s` final candidate 运行也彼此逐值相同并均完成到终点，但两次对旧批准 golden 都只有 `398/402` 个值通过：同样的 4 个 `t=0.2 s` 派生 MECMAS21 加速度超出旧容差，最大容差比均为 `1.373`。因此不覆盖或重新批准旧 golden；应先独立确认派生加速度语义或调整投影契约。
- 最终 `2 s / maxStep=0.02 s` 复验 worker 墙钟 `301.782 s`，0 次热流体失败/可恢复重试，2 次状态事件，单格矩阵整体通过。真实 SciPy RK45/BDF 的 direct 与 opt-in stepwise A/B 在无失败时采样、状态及 `nfev/njev/nlu` 一致。完整 `unittest discover` 共 828 项，OK（3 项跳过）。
- 证据：`runs/2026-08-17-production-general-recovery-v2-smoke.json`、`runs/2026-08-17-production-general-recovery-v2-0.2.json`、`runs/2026-08-17-production-general-recovery-v2-repeat-0.2.json`、`runs/2026-08-17-production-2s-max-step-0p02-general-recovery-v3.json`、`runs/2026-08-17-production-10s-max-step-0p02-recovery-v1.json`、`runs/2026-08-17-production-10s-max-step-0p02-general-recovery-v3.json`。

**工作项**：

- [ ] 在 OPT-00 的 `0.2/1 s` 短时二维门通过后，使用同一 JSON 和 `maxStep=0.001 s` 依次延长到 `2/5/10 s`；在任何针对本次长跑的性能调优前先完整运行一次权威 `10 s / 0.001 s` 原始基线。
- [ ] 首次长基线不得因总墙钟较长而提前当作性能失败；只有 worker、CPU 和内部活动心跳均停止并满足真停滞条件时才有界终止。若发现致命正确性问题，只做使基线可完成的最小修复，然后从 `t=0` 重新运行。
- [ ] 在正式锁定环境运行未优化基线 `10 s`，设置心跳、资源上限和可恢复日志。
- [ ] 保存事件、模式、步长、拒步、Jacobian、闭合和内存随模拟时间的时间线。
- [ ] 为长跑设置阶段性检查点，支持定位首次偏差而非只比较终点。
- [ ] 将每项 P1 优化分别加入 `10 s` A/B，不把多个改动混成一个结果。
- [ ] 根据首次基线制定合理的 CI 频率和资源门槛。
- [x] 最终通用接线后的当前工作树完成首次 `10 s / maxStep=0.02 s` 单次运行并保存完整统计；连续 3 次验收仍待后续。
- [ ] 首次 `10 s / maxStep=0.001 s` 完整报告生成后，才根据各阶段墙钟与内部计数决定性能优化目标；旧 `0.02 s` 报告不得用于跳过该顺序。

**验收条件**：

- [ ] 权威 `10 s / 0.001 s` 首次基线到达 `t=10`，输出 `0..10 s` 共 1001 个采样时刻且全部有限；事件、模式、关键状态、压力/流量和守恒量满足契约。
- [ ] 连续 3 次完成 `10 s`，没有无解释回退、NaN/Inf 或资源失控。
- [ ] 全程模式、事件、关键状态和守恒量满足契约。
- [ ] 可从日志快速判断任何慢区属于积分、Jacobian、闭合、事件还是输出。
- [ ] 同一 `maxStep=0.001 s` 下，`0.2/1/2/5/10 s` 的严格公共前缀按分类契约一致；短任务终点单独标记 terminal，不与长任务内部插值作位级误判。
- [ ] 最终 `10 s` 至少完成 `maxStep=0.001/0.005/0.02 s` 三个代表档，并逐步补齐 `0.002/0.01 s`；较小步长不得出现较大步长没有的可复现数值失败或更早真停滞。

### OPT-10 明确高指数 DAE 和强非光滑系统边界

**目标**：明确当前通用求解能力的工程边界，并决定是否值得引入真正的 DAE/互补问题求解器。

**当前状态**：当前架构更适合结构明确、可唯一闭合、状态较连续的规则 index-1 类系统。超硬非光滑接触、临界抖动、近奇异代数系统、更高指数 DAE 和依赖声明不完整的自定义组件仍是薄弱点。

**工作项**：

- [ ] 建立小型基准族：刚性接触、反复开闭、近奇异闭合、尺度跨越、自定义漏依赖和 index-2/3 示例。
- [ ] 对每类系统定义“支持”“降级支持”“明确拒绝”，并给出诊断。
- [ ] 评估质量矩阵 DAE、指数约简、互补/半光滑方法与现有架构的成本。
- [ ] 只有真实模型需求和基准证明必要时，才启动通用 DAE 后端项目。

**验收条件**：

- [ ] 文档与运行时错误能明确说明能力边界，不出现静默错误。
- [ ] 若启动新后端，有独立设计、基准和迁移计划，不与普通 RHS 性能优化混合。

## 6. 统一回归矩阵

| 场景 | 结构 | 数值状态 | 事件/模式 | 回退 | 性能 | 长时内存 |
| --- | --- | --- | --- | --- | --- | --- |
| 小型线性组件 | 必测 | 必测 | 不适用 | 必测 | 冒烟 | 不适用 |
| 非线性压力/流量 | 必测 | 必测 | 可选 | 必测 | 必测 | 可选 |
| stream 无环/成环/反向流 | 必测 | 必测 | 必测 | 必测 | 必测 | 可选 |
| 接触与模式切换 | 必测 | 必测 | 必测 | 必测 | 必测 | 可选 |
| 自定义组件与漏依赖 | 必测 | 必测 | 可选 | 必测 | 可选 | 不适用 |
| 本文复杂 XML `0.81 s` | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
| 本文复杂 XML `2.10 s` | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
| 本文复杂 XML `10 s` | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
| 主目标 `test-mql-8` `0.2 s` | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
| 主目标 `test-mql-8` `1/5/10 s` | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
| 权威 JSON 浏览器/流式 API `0.2 s / maxStep=0.001 s` | 必测 | 必测 | 必测 | 必测 | 必测（含内部活动心跳） | 可选 |
| 权威 worker `0.2/1 s × maxStep={0.001,0.002,0.005,0.01,0.02} s` | 必测 | 必测（分类容差） | 必测 | 必测 | 必测（串行矩阵） | 可选 |
| 权威 JSON `10 s / maxStep=0.001 s` | 必测 | 必测 | 必测 | 必测 | 必测（完整时间线） | 必测 |

2026-08-17 的 `maxStep=0.01/0.02/0.05/0.10 s` 延长结果继续作为恢复机制与历史路径证据，但不替代
2026-08-18 权威 `maxStep=0.001 s` 的 browser/API/worker P0 门和 10 s 最终基线。

当前相关回归套件包括：

- `tests/test_sparse_secant_jacobian.py`
- `tests/test_generic_jacobian_sparsity.py`
- `tests/test_pressure_flow_causal_execution.py`
- `tests/test_stream_pressure_block_solver.py`
- `tests/test_core_solver.py`
- `tests/test_causal_numeric_ir.py`
- `tests/test_thermofluid_recovery.py`
- `tests/test_amesim_pnl00r_component.py`
- `tests/test_stream_resolver_execution_plan.py`
- `tests/test_thermofluid_closure_plan.py`
- `tests/test_max_step_matrix.py`

这些测试目前覆盖部分关键机制，但不能替代复杂 XML 的端到端数值和长时回归。最终完整 `unittest discover` 共 828 项，OK（3 项跳过）。

## 7. 单项更新模板

完成一个原型或 PR 后，在对应任务下追加以下记录：

```markdown
#### YYYY-MM-DD / <commit-or-branch>

- 状态：未开始 → 进行中 / 部分实现 → 已完成
- 实现范围：
- 未覆盖范围：
- 运行环境：
- 输入与配置：
- 正确性结果：
- 性能结果（中位数与离散度）：
- 回退/审计结果：
- 风险或已知退化：
- 决策：合入默认路径 / 继续实验 / 回滚 / 不采用
- 证据文件或 CI 链接：
```

## 8. 总体更新记录

| 日期 | 代码/分支 | 任务 | 变化 | 正确性 | 性能 | 决策 |
| --- | --- | --- | --- | --- | --- | --- |
| 2026-08-17 | `6bb0591d` | 基线 | 原始 `0.81 s` 完成；内存延长 `2.10 s` 完成并越过 2.05 s | 无卡死；当前环境哈希与历史不同，待正式环境复核 | 63.779 s / 126.211 s（单次） | 建立任务清单，先完成 OPT-00 |
| 2026-08-17 | 工作树基于 `6bb0591d`；备份 `backup/jacobian-before-20260817-6bb0591` | OPT-03 | callable sparse Jacobian、真实计数、分段重置、取消、严格 seed 0 与实验 secant | 121 项相关测试通过；另 1 项既有 fixture 路径错误；30 色候选事件不等价，seed 0 候选恢复相同哈希 | 30 色历史候选有收益但不正确；seed 0 候选略慢且缓存 0 命中 | 默认 SciPy；移除多 seed/缓存；保留接入基础；解析/半解析继续后续 |
| 2026-08-17 | 工作树基于 `6bb0591d`；同一备份分支 | OPT-03 首批半解析切片 | exact-columns subset FD、类型化回退/诊断、三活塞 6 列与 34 条因果赋值；31→25 个 FD 颜色；新增 Ideal/PR、PNRP、PNCH012、PNL0001、LSTP、MECMAS 切向原语 | focused 86 + adjacent 164 = 250 项通过；closure 12/13，唯一失败为既有 fixture 路径；局部列对中心 FD 最大相对误差 `1.897e-8`；默认容差轨迹仍超严格逐点门槛，但随 rtol 收紧约 4.67×/5.15× 收敛且事件一致 | `0.81 s` 三次墙钟中位数 61.203→56.708 s，Jac RHS 8096（估计）→5985（实计）；最终 `2.10 s` 单次 126.211→116.512 s，正常越过 2.05 s，事件/启动/样本均与基线一致 | 首批目标切片完成，OPT-03 总体仍部分实现；默认 SciPy，`semi-analytic` 显式 opt-in；待通用 stream/其余列、正式锁定环境独立预热和 10 s 验证 |
| 2026-08-17 | 同一 OPT-03 工作树；3 组相邻 A/B | OPT-03 重复性能复核 | 原始 `0.81 s`，每组先 SciPy 后 `semi-analytic`，运行期间无并发仿真负载 | 三组求解统计、哈希、事件和输出网格各自完全稳定；Jacobian RHS 8096（估计）→5985（实计） | 总墙钟中位数 61.203→56.708 s（`-7.34%`），积分中位数 59.725→55.631 s（`-6.85%`） | 保持显式 opt-in；仍需正式锁定环境独立预热、严格轨迹契约和 10 s 验证 |
| 2026-08-17 | 工作树基于 `16a7eb2d`；备份 `backup/general-solver-v1-before-20260817-16a7eb2` | OPT-00/01/03/09 通用求解器 v1（历史输入） | 初版 `test-mql-8` runner/正确性门；默认低分配因果执行器 v2；名字无关的 8 支路/16 列半解析编译器 | 旧 SHA `42e2d627...` 下 0.01 s v1/v2 物理解逐位相同；0.2 s 全有限且 0 审计/回退失败 | v2 RHS 微基准 `-19.1%`；0.01 s 总墙钟 `-13.1%`；旧 0.2 s 132.305 s | v2 升为默认并保留 opt-out；旧报告标为 `historicalOnly`，不得生成新 golden |
| 2026-08-17 | 同一工作树；新权威 SHA `170463d6...` | OPT-00 P0 基础闭环 | 固化无空格 XML/JSON、参考依赖约束、runner v2、state golden、output contract、三层 CI 和有界延期决策 | production 0.2 s 全有限；402 个 golden 值逐项重放误差 0；信号分段/机械事件/残差/审计/回退门均通过；全量共 792 项，OK（3 项跳过） | worker 135.824 s；1 s 保守预测 1018.680 s，未启动 1/5/10 s | P0 基础设施完成，完整 OPT-00/09 仍部分实现；先优化算法，再恢复长时递进 |
| 2026-08-17 | 同一工作树 | OPT-01/02 因果坐标与参考 IR | `760` 个兼容槽压缩为 `440` 个逻辑坐标；独立 schema v1 参考 IR 覆盖 `112+328` 坐标和 320 个逻辑别名 | kernel on/off、兼容槽、状态导数、结构签名和逐阶段差分通过；审计/验证/回退失败均为 0 | Python 调用 `-36.8%`，RHS 微基准 `-12.9%`，production 0.2 s 单次 `-3.68%` | OPT-01 基本完成；IR 暂不接管默认热路径 |
| 2026-08-17 | 同一工作树 | OPT-00/04/05/08/09 热流体恢复与延长矩阵 | 修正 PNL00R 温度 stream 参考；加入 RHS 事务、类型化闭合失败、基于 `h_abs` 的对半重试和完整诊断 | production 0.2 s golden 通过；2 s 四档 `maxStep` 均完成且 `caseFailureCount=0`，但跨步长严格门因近零机械 `a/v` 差异未过；5 s 的 0.02 s 档完成，0.05 s 档为预算取消而非 solver failure | 2 s worker 墙钟为 324.727/292.035/450.425/448.033 s；5 s 的 0.02 s 档为 696.418 s、0 retry、`18736/1347/4988`，0.05 s 档在 1200 s 预算停止于 4.2523535 s | 原 1.86 s 致命失败已恢复；暂以 0.02 s 作为延长测试首选但不修改正式默认值或批准 golden；10 s 的 0.02 s 档进行中 |
| 2026-08-17 | 同一工作树；最终通用接线与 10 s repeat | OPT-04/05/08/09 `10 s` 最终收口 | eventless Generic opt-in stepwise recovery；StreamResolver 刷新全部温度参考 override；修复单格矩阵空比较器 | 0.01 s 接线前后逐值一致；两次 0.2 s final candidate 彼此逐值相同且均为旧 golden 398/402，同样 4 个终点派生 MECMAS21 `a` 超差、最大容差比 1.373，未覆盖 golden；最终 2 s 单格通过；真实 SciPy direct/stepwise A/B 等价；完整 unittest 828 项 OK（3 项跳过） | 最终接线后 10 s worker/orchestration 1602.733/1604.152 s，`45455/3075/15282`，接受步 9569、启动 6、事件 2；`t=6.9640458 s` 的 1 次热流体失败经 1 次重试恢复，最大迭代 23、残差 `1.082e-16`，1717 序列/1,722,151 标量全有限；最终 2 s worker 301.782 s | 最终通用接线后的 10 s 已完成；803.622 s 旧报告只作接线前历史证据、不作最终性能；旧 exit 1 仅为空比较器缺陷；旧 golden 保留，连续 3 次 10 s 仍待后续 |
| 2026-08-18 | 工作树基于 `684d287`；AME SHA `cbc3aadd...` | OPT-00 完成 | AME→XML/JSON 权威契约、22 包发布锁、双 golden、最终 replay 与历史 2.10 s 三次复测 | AME 25 项外部评估通过；状态 426/426、物理 33/33 本地重放零误差；quick 179、全量 849 项通过 | 0.2 s worker 159.607 s；2.10 s 三次 113.497–115.868 s | OPT-00 本地验收完成；1 s 预算内 eligible，长时递进转 OPT-09；远端 CI 待提交触发 |
| 2026-08-18 | 同一权威 AME/XML/JSON 工作树 | OPT-00/05/08/09 步长鲁棒性重新打开 | 浏览器在 `BDF / 0.2 s / sampleStep=0.01 s / maxStep=0.001 s` 下于 `t≈0.0489 s` 计算超时，当前工程路径判定失败；新增 browser/API/worker 对账、`0.2/1 s × 五档` 短时矩阵、内部活动心跳和权威 10 s 门 | 失败事实已确认，具体根因尚未区分为数值真停滞、内部慢步、后处理/传输或 60 s 服务假超时；离线 OPT-00 证据保留但不足以签收浏览器工程路径 | 暂不使用旧 `0.02 s` 长跑推断 `0.001 s`；先定位并提交方案审阅，短时门通过后再完整取得未经本次性能优化的 `10 s / 0.001 s` 基线 | OPT-00 工程端到端门重新打开；OPT-05 提升为 P0/P1，OPT-08 为 P0 服务门，OPT-09 只认 `0.001 s` 权威长基线 |

## 9. 相关文档

- [后端求解逻辑与效率优化调研](./后端求解逻辑与效率优化调研.md)
- [仿真性能评估-2026-08-15](./仿真性能评估-2026-08-15.md)
- [文档目录说明](../README.md)