# LinuxCNC Web/WASM 仿真功能补全计划

**版本**：3.1
**范围**：只实现 LinuxCNC 仿真功能，不处理其他项目。
**接续入口**：[`nextTask1.md`](../nextTask1.md)

## 目标

在 Dedicated Worker 中实现可重复的 LinuxCNC 仿真行为，并用 WASM/native/Worker 测试验证：

- INI、HAL、工具表、参数、程序、Python、VCP、ClassicLadder 资源加载。
- rs274 G/M/O 解释、modal、参数、子程序、循环、宏、canned cycle 和错误定位。
- canonical queue、TP、直线/圆弧/同步运动、速度/加速度/jerk、blend、exact-stop。
- Task mode、MDI、run/pause/resume/step/abort/restart、jog、home、override、limits。
- trivkins、gantry/CoreXY、5/6-axis、TRT、机器人、Delta/Tripod/Hexapod/Pentapod、switch/user kins。
- HAL pin/signal/parameter/thread/function、静态 `.comp`、ClassicLadder、PLC、采样和背压。
- spindle、encoder、probe、limit、home、tool、coolant、door、interlock、estop 数字孪生。
- Python `linuxcnc/hal/INI/tool/parameter`、remap、filter、VCP callback 和异常隔离。
- snapshot/event/trace、checkpoint、journal、Worker restart、OPFS、offline、migration、rollback。
- editor、MDI、状态/HAL/IO/Python/PLC/alarm 面板和 pose/toolpath/stock Canvas。

## 不变量

1. Worker 是 authoritative state 唯一写者；UI 只消费 snapshot/event。
2. `sim_step(cycles)` 是唯一改变仿真结果的入口；不使用墙钟或随机数。
3. `seq`、`operation_id`、checkpoint、event、snapshot 和 state hash 全部确定性。
4. 非法路径、缺失资源、非有限值、容量、未知能力和 schema 错误 fail closed。
5. 真实硬件、设备文件、宿主进程、网络和动态库不进入仿真实现。

## 实施阶段

### S1 解释器与运动主链

`S1-01` rs274 完整 word/modal/system parameter；`S1-02` canonical/TP 圆弧、同步运动、accel/jerk 和暂停；`S1-03` motion/kinematics feedback、home/limit、override。

### S2 HAL、PLC、设备

`S2-01` `.clp` ClassicLadder parser/runtime；`S2-02` HAL component runtime batch；`S2-03` encoder/coolant/door/interlock/IO ack；`S2-04` 配置入口资源修复。

### S3 Python、恢复、浏览器

`S3-01` Python API compatibility；`S3-02` remap/filter/VCP；`S3-03` Worker crash/OPFS/offline/recovery；`S3-04` browser simulation compatibility/performance。

### S4 仿真回归

`S4-01` full simulation regression；`S4-02` 1x/fast/step/recover endpoint replay parity。

## 任务队列

| ID | 任务 | 依赖 | 主要输出 |
|---|---|---|---|
| S1-01A | implement rs274 parameter space and modal expansion | 无 | interpreter native/WASM/Worker tests |
| S1-01B | implement rs274 G/M words, canned cycles, coordinates and compensation | S1-01A | interpreter native/WASM/Worker tests |
| S1-02A | implement TP arcs, sync FIFO and accel/jerk bounded profile | S1-01B | TP/motion tests |
| S1-02B | implement pause/resume and canonical multi-segment expansion | S1-02A | TP/motion tests |
| S1-03 | implement motion/kinematics feedback, home/limit and override | S1-02B | motion fault matrix |
| S2-01 | implement `.clp` ClassicLadder parser/runtime | S1-03 | PLC runtime/tests |
| S2-02 | implement HAL component runtime batch | S1-03 | component runtime/tests |
| S2-03 | implement encoder/coolant/door/interlock/IO ack parity | S1-03 | device/IO tests |
| S2-04 | implement blocked sim entrypoint resource batch | S2-02 | startup/runtime tests |
| S3-01 | implement Python API compatibility | S1-01 | Python bridge/session tests |
| S3-02 | implement remap/filter/VCP callback path | S3-01 | callback tests |
| S3-03 | implement Worker/OPFS/offline recovery | S2-03/S3-01 | recovery tests |
| S3-04 | implement browser simulation compatibility/performance | S3-03 | app/Canvas/Worker tests |
| S4-01 | complete simulation regression | S2-04/S3-04 | full simulation report |
| S4-02 | complete endpoint replay parity | S4-01 | determinism/recovery report |

## 当前任务

当前直接执行 `S1-01`。它读取 `linuxcnc/src/emc/rs274ngc`、`linuxcnc/unit_tests/interp`、`wasm-core/src/sim_interpreter.c` 和 `web/worker/program-runner.mjs`，输出代码、native/WASM/Worker 测试和确定性状态报告。

## 验收

每个任务必须有正常、边界、错误、容量、暂停/恢复和非有限样本；必须运行对应 native/WASM/Worker 测试、`scripts/build-wasm.sh`、CTest 和全部 Worker/App 测试。任务报告必须包含输入、输出、测试和 self-hash。

## 停止条件

- 需要修改已冻结 ABI、protocol 或 schema。
- 结果依赖墙钟、随机数、真实设备、宿主路径、动态库或 mock Worker。
- checkpoint/event/hash 不可验证，或恢复会重复副作用。
- 仿真差异未定位到具体 tick、字段、单位或错误位置。