linuxcncWebWASM/docs/linuxcnc-web-wasm-simulation-gap-plan-v2.md

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

版本：3.1 范围：只实现 LinuxCNC 仿真功能，不处理其他项目。 接续入口：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、字段、单位或错误位置。