linuxcncWebWASM/docs/linuxcnc-web-wasm-complete-simulation-plan.md

LinuxCNC Web/WASM 完整仿真移植实施计划

版本：1.0 状态：implementation baseline 目标基线：仓库 context-lock.json 锁定的 LinuxCNC 版本 接续入口：nextTask1.md 已有专项资料：

• linuxcnc-web-wasm-full-port-implementation.md
• linuxcnc-web-wasm-simulation-coverage.md
• linuxcnc-web-wasm-source-map.md
• linuxcnc-web-wasm-frontend-communication-design.md
• linuxcnc-web-wasm-kinematics-migration-plan.md

本文件是“完整仿真移植”实施轨道的唯一执行目录。仿真实现不依赖 release、owner、许可证审批或发布候选流程；这些内容不参与仿真任务的排队、执行和验收。

1. 目标和边界

1.1 目标

在浏览器 Dedicated Worker 中运行 LinuxCNC 的可观察仿真行为，使用 WASM 承载数值密集型核心，使用 Web API 承载工程、恢复、界面和可视化。用户应能：

1. 导入或创建一个 LinuxCNC 仿真工程。
2. 解析 INI/HAL/工具表/参数/程序/Python/VCP/ClassicLadder 等资源。
3. 启动仿真并看到确定性的 READY、RUNNING、PAUSED、ESTOP、FAULT、STOPPED 状态。
4. 执行 G-code、MDI、jog、home、pause、resume、single-step、abort、override 和模式切换。
5. 观察轴/关节/姿态/轨迹、HAL pin/signal、主轴、工具、探针、限位、冷却、报警和 Python/VCP 状态。
6. 注入故障、暂停、导出 checkpoint、刷新 Worker、从 OPFS 恢复并得到相同的确定性终点。
7. 对纳入范围的 configs/sim 入口给出 READY 或可定位的 BLOCKED/ERROR，不静默跳过资源。

1.2 仿真范围

以下行为必须实现或有原生/WASM 对照证据：

功能域	必须覆盖的行为	浏览器实现边界
工程与配置	workspace、INI/include/变量、HAL、工具表、参数、程序、Python、VCP、ClassicLadder、资源错误	/workspace 虚拟文件系统；禁止宿主绝对路径、..、符号链接逃逸
Task/命令	mode、MDI、program load/run/pause/resume/step/abort、错误、状态、operation ledger	Worker 单写者；主线程只能发送版本化命令
解释器	G/M/O words、模态、单位、坐标、参数、子程序、循环、宏、过滤器和错误行号	运行在 WASM/Python Worker；能力拒绝必须稳定
TP/motion	canonical queue、直线/圆弧/同步运动、速度/加速度/jerk、blend、exact stop、暂停和恢复	逻辑 tick 取代硬实时墙钟，保持顺序和结果确定
运动学	trivkins、gantry/CoreXY、5/6 轴、TRT、机器人、Delta/Tripod/Hexapod/Pentapod、switchkins/userk	静态链接、注册表选择；动态模块加载不进入浏览器
轴/关节	joint/axis 映射、home、软限位、following error、外部偏置、jog、override、estop	由数字孪生提供输入和故障状态
HAL/组件	pin、signal、parameter、thread、function、addf、setp、net、twopass、.comp 静态组件	组件不得访问宿主设备、进程、网络或动态库
PLC/IO	ClassicLadder scan、寄存器、定时器、计数器、数字/模拟 IO、采样、触发、背压	虚拟寄存器和逻辑设备；真实 transport 为 REAL-EXCLUDED
设备数字孪生	主轴、编码器、探针、限位、home、换刀、冷却/润滑、故障/延迟/抖动	故障注入必须可记录、回放、恢复，不使用未固定的随机数
Python/remap/VCP	白名单模块、参数/工具/INI API、remap/filter 生命周期、VCP pin/回调/异常	Pyodide Worker；subprocess/socket/device files 明确拒绝
持久化/恢复	journal、checkpoint、snapshot、event replay、Worker restart、OPFS quota、migration、rollback、offline	OPFS 只保存已提交数据，不参与运动计算
Web 工作流	编辑器、MDI、控制台、HAL/PLC 面板、报警、恢复向导、轨迹和机床可视化	UI 只消费 authoritative snapshot/event，不反写核心状态

1.3 明确排除

以下是宿主能力排除，不是仿真行为排除：

• 真实 PCI/USB/串口/GPIO/并口、真实伺服和真实安全回路。
• Linux PREEMPT_RT、内核线程、共享内存 NML/CMS 进程边界、fork/exec 和动态 .so 加载。
• 浏览器无法提供的设备文件、任意宿主路径、任意网络 socket 和真实硬件时钟。

被排除的宿主层必须返回稳定的 REAL-EXCLUDED 错误；对应的轴、主轴、编码器、探针、限位、换刀和 IO 仍必须由数字孪生覆盖。

2. 架构和不变量

Web UI / Editor / Three.js
             │ protocol.v1
Dedicated Worker
  CommandRouter → TaskLedger → SimScheduler
                              ├─ SimTask / rs274 / canonical
                              ├─ TP / posemath / kinematics
                              ├─ SimMotion / home / limits
                              ├─ SimHAL / components / ClassicLadder
                              ├─ SimIO / digital twins
                              └─ PythonRuntime / remap / VCP
             ├─ SnapshotPublisher / EventBus / TraceRecorder
             └─ WorkspaceRuntime → WasmFS/POSIX → OPFS journal/checkpoint
                       │
                       └─ native oracle 使用同一输入和命令序列

必须保持以下不变量：

1. Worker 是唯一 authoritative state 写者；UI 不读取 WASM 指针，不直接写 HAL/OPFS。
2. sim_step(cycles) 是唯一改变仿真结果的入口；墙钟只负责调度和让出事件循环。
3. 命令按 seq 顺序提交，operation_id 幂等；确认丢失先对账，不重复执行副作用。
4. 固定宽度 ABI、明确的 protocol/snapshot/event/workspace schema 和稳定错误码优先于 UI 便利。
5. 状态、事件、轨迹、HAL、IO、Python 和恢复结果都能产生确定性 hash。
6. 缺少输入、未支持能力、配额不足、非法路径、非有限数和 schema mismatch 必须 fail closed。
7. 任何 native/WASM 差异都保留首个 divergent tick、字段路径、单位、容差和来源证据。

2.1 固定 tick 顺序

每一个逻辑 tick 依次执行：

1. 对账并去重已确认命令。
2. 执行 Task/解释器预算，更新模态、参数、当前行和 canonical。
3. 执行 TP 前瞻、速度/加速度/jerk、blend/exact-stop。
4. 调用 kinematics inverse，检查奇异性、joint 数量、limits 和 NaN/Inf。
5. 更新 motion、home、jog、following error、外部偏置、estop/limit。
6. 按静态线程/function 顺序运行 HAL、组件、编码器、主轴、探针、换刀和 PLC scan。
7. 运行 IO 完成、超时、报警、Python/remap/VCP 回调；回调不能越过当前 tick。
8. 生成 snapshot/event/trace/state hash，再执行已提交 checkpoint/journal。

快速运行、1x、单步、暂停恢复、导出导入和 replay 在相同逻辑终点必须得到相同 hash。

3. 功能实施顺序

F0：输入、来源和契约

• 以 context-lock.json、source index、manifest、config resource graph 和 protocol schema 为输入。
• 为每个 source/file/symbol/config/test 建立 source_id → feature_id → task_id → test_id → oracle_id 关系。
• 固定 sim_task.v1、command-envelope.v1、snapshot.v1、event-log.v1、workspace-package.v1 的字段、版本和错误策略。
• 缺少官方测试输入时保留 blocked，不得用近似目录伪装官方 oracle。

F1：运行时骨架

• 建立 SimTask、SimScheduler、TaskLedger、SnapshotPublisher 和 EventBus。
• 把现有 WASM lifecycle、fixed tick、event、snapshot、G-code runner 接入 authoritative task state。
• 增加容量、非有限值、取消、abort、pause/resume、operation replay 和 checkpoint 边界。

F2：工作区和配置启动

• 实现虚拟 POSIX 文件 API、规范化路径、大小/配额和事务写入。
• 解析 INI/include/变量，解析 HAL/工具表/参数/程序/Python/VCP/ClassicLadder 资源图。
• 统一 NEW → MOUNTED → PARSED → RESOLVED → CORE_CREATED → HAL_READY → TASK_READY 状态机。
• 每个 configs/sim 入口输出 READY 或带文件/行/字段/source_id 的诊断。

F3：解释器、Task、TP、motion、kinematics

• 先让 native oracle 输出每个 block 的 modal/canonical/参数和错误，再接入 WASM。
• 接入 O-word/子程序/循环/参数/宏/remap/filter、MDI、program state machine。
• 将 canonical queue 连接 TP、motion 和 kinematics；实现暂停、单步、abort、jog、home、override、limits、following error。
• 按 kinematics registry 逐族接入并保留每个族的 forward/inverse、branch、singularity 和 limit 证据。

F4：HAL、PLC、IO 和数字孪生

• 解析并执行 pin/signal/parameter/thread/function、loadrt/addf/setp/net/sets/link* 和静态 .comp。
• 实现 ClassicLadder 工程、scan、寄存器、计数器、定时器、HAL 绑定和诊断。
• 接入 spindle/encoder/probe/limit/home/tool/coolant/IO，支持故障注入、延迟、抖动、恢复和回放。

F5：Python、remap、VCP

• 固定 Pyodide 版本、manifest、模块白名单、内存/时间/源码限制。
• 实现 linuxcnc/hal/gstat/INI/tool/parameter/workspace/virtual-clock 兼容 API。
• 接入 remap/filter 生命周期、VCP descriptor、pin callback、异常隔离和权限拒绝。

F6：恢复、离线和迁移

• 将 Task、解释器、TP、motion、kinematics、HAL、IO、Python、workspace 和 ledger 纳入 checkpoint。
• 实现 journal prepare/commit、确认丢失对账、崩溃恢复、OPFS quota、离线包、版本迁移和 rollback。
• 恢复必须从最近有效 checkpoint 重放已提交 event，不得只重新加载配置。

F7：Web 工作流和可视化

• 完善工程导入、编辑器诊断、MDI、run/pause/step/abort、jog/home/override、HAL/PLC/IO/报警面板。
• 以 authoritative snapshot/event 驱动姿态、joint、toolpath、stock、坐标系、工具、主轴和故障渲染。
• 用 Worker 重启、离线、配额和错误场景覆盖 UI 恢复向导；不使用 mock 替代真实 Worker。

F8：全量兼容、性能和交付

• 对所有纳入范围的 configs/sim、相关 tests/unit_tests 和资源入口执行 native/WASM 差异矩阵。
• 固定至少三次重复、快速/1x/单步/恢复、浏览器矩阵、性能、内存和离线报告。
• 许可证、来源、下载、迁移、回滚和 REAL-EXCLUDED 边界全部有证据；只有所有 gate 满足时才讨论 release candidate。

4. 任务分解

任务状态只能按 queued → in_progress → verified 或 in_progress → blocked 转移。每个任务只有一个主要结果，并必须提供输入 context、直接证据、专属测试、完整回归和回滚点。

ID	任务	依赖	主要产物	验收重点
P0-01	冻结来源、工具链、schema 和 source hash	无	context/source baseline	baseline 可重建，缺输入 fail closed
P0-02	建立 source→feature→task→test 图	P0-01	coverage graph/manifest	无孤儿、重复、未知 ID
P0-03	固定 ABI/protocol/snapshot/event/workspace 契约	P0-01	schema + compatibility tests	版本 mismatch 和字段缺失拒绝
P1-01	建立 sim_task.v1 authoritative 状态对象	P0-03	Task state/native/WASM tests	state hash、状态机、错误码一致
P1-02	固定 sim_step 调度顺序和 tick budget	P1-01	scheduler + tick golden	快速/1x/单步终点一致
P1-03	接入 command ledger、幂等和 abort	P1-01	ledger/replay tests	operation replay 不重复副作用
P1-04	将现有 G-code/MDI runner 接入 Task snapshot	P1-01	Worker/native/WASM report	当前行、模态、程序状态可观察
P2-01	虚拟 POSIX/Workspace API	P1-01	workspace runtime	路径、编码、配额、事务错误稳定
P2-02	INI/include/变量解析器	P2-01	parser/resource graph	行号、循环、缺失资源可诊断
P2-03	HAL/工具表/参数/程序/Python/VCP/CLP resolver	P2-01	config resource graph	所有依赖可定位、不静默替换
P2-04	统一配置启动状态机	P2-02/P2-03/P1-02	startup resolver/233-entry report	入口只进入 READY 或 BLOCKED
P3-01	rs274 grammar/modal/parameter 完整闭环	P1-04	native/WASM interpreter oracle	block、错误列和 modal hash 一致
P3-02	O-word、子程序、循环、宏和过滤器	P3-01/P5-02	interpreter golden	深度、预算、异常边界完整
P3-03	canonical queue、TP 前瞻、blend/exact-stop	P1-02/P3-01	TP golden/diff report	segment 顺序、速度和首差 tick
P3-04	Task mode、MDI、program state machine	P1-03/P3-01	command golden	run/pause/resume/step/abort 可恢复
P3-05	motion、jog、override、home、limits、following error	P3-03	motion state/故障矩阵	轴/关节、estop、limit、home 一致
P3-06	kinematics registry 和 trivkins/gantry/CoreXY	P3-05	registry + native/WASM tests	forward/inverse/branch/limits
P3-07	5/6-axis、TRT、机器人、并联和 switch/user kins	P3-06	每族 report/golden	singularity、非有限、缺 oracle 明确
P4-01	HAL graph/twopass/pin/signal/thread/function	P2-03/P1-02	HAL graph/runtime	顺序、类型、重复、未知组件 fail closed
P4-02	静态 .comp 组件和能力 manifest	P4-01	component manifest/tests	不动态加载、不访问宿主
P4-03	ClassicLadder/采样/触发/背压	P4-01	PLC runtime/report	scan 顺序、寄存器、故障可回放
P4-04	spindle/encoder/probe/limit/home/tool/coolant twin	P4-01/P3-05	device model/fault matrix	延迟、故障、恢复、hash 一致
P4-05	IO command/ack/timeout/estop/recover	P4-04/P1-03	IO Worker/native tests	ack 丢失和恢复不重复副作用
P5-01	Pyodide runtime、模块白名单和虚拟时钟	P2-01	runtime manifest/report	资源和能力限制稳定
P5-02	Python linuxcnc/hal/INI/tool/parameter API	P5-01/P3-04	API compatibility tests	正常、异常、禁止能力
P5-03	remap/filter/VCP callback 和隔离	P5-02/P4-01	remap/VCP report	异常不破坏 Worker 核心
P6-01	snapshot/event/trace 全状态导出	P1-02/P3-05/P4-05/P5-03	schema/hash tests	导入导出 round-trip
P6-02	journal/checkpoint/operation reconciliation	P6-01/P1-03	recovery matrix	crash、半提交、确认丢失
P6-03	OPFS/offline/migration/rollback	P6-02/P2-01	browser recovery report	离线、配额、版本迁移
P7-01	Worker protocol/client、backpressure、cancel	P1-03/P6-01	protocol E2E	seq、schema、timeout、cancel
P7-02	editor/diagnostic/MDI/run workflow	P3-04/P7-01	browser E2E	真实 Worker，不用 mock
P7-03	state/HAL/IO/Python/PLC/alarm panels	P4/P5/P7-01	UI tests	snapshot/event 单向消费
P7-04	Three.js pose/joint/toolpath/stock view	P3-05/P7-03	WebGL/canvas tests	非空、姿态和轨迹跟随 authoritative state
P7-05	recovery/offline/error/permission UX	P6-03/P7-02	browser fault E2E	恢复状态可操作、错误可定位
P8-01	native oracle runner 和 golden schema	P0-03/P3/P4	JSONL oracle	同输入、同命令、首差 tick
P8-02	全量 sim entrypoint matrix	P2-04/P8-01	startup/diff matrix	每入口 READY 或诊断 BLOCKED
P8-03	三次重复和执行模式 determinism	P8-02/P6	determinism report	1x/fast/step/recover hash 一致
P8-04	browser/performance/memory/offline matrix	P7/P8-03	perf/compat report	P95/P99、配额、WebGL、离线
P8-05	来源/许可证/下载/迁移/回滚交付闭合	P8-02/P8-04	release evidence	所有排除项和剩余 blocker 显式保留

5. 里程碑

里程碑	名称	包含任务	退出条件
M0	输入和契约闭合	P0-01..03	context/source/schema hash 可重建；输入缺失不会被接受
M1	Task/WASM/Worker 会话闭合	P1-01..04	create/load/MDI/program/tick/pause/abort/snapshot/replay 通过 native/WASM/Worker
M2	解释器和运动主链	P3-01..07	G-code→canonical→TP→motion→kinematics→snapshot 闭合，首差可定位
M3	配置启动闭合	P2-01..04	纳入范围的每个入口进入 READY 或带来源诊断的 BLOCKED
M4	HAL/IO/数字孪生闭合	P4-01..05	HAL/PLC/主轴/编码器/探针/限位/工具/冷却/estop 故障可执行、可回放
M5	Python/remap/VCP 闭合	P5-01..03	白名单 API、remap、VCP、异常、能力拒绝和资源限制通过
M6	恢复和离线闭合	P6-01..03	Worker 重启、OPFS checkpoint、journal、迁移、回滚、离线路径通过
M7	Web 工作流和可视化闭合	P7-01..05	UI 真实消费 Worker authoritative state，Three.js/Canvas 非空并可恢复
M8	全量兼容和交付闭合	P8-01..05	全量矩阵、三次 determinism、浏览器/性能和来源证据齐全；仿真结果独立可运行

每个里程碑完成时必须生成一份确定性 report，包含 context_id、任务 ID、输入/输出 hash、native/WASM/Worker 测试、已知 blocked 项和下一个依赖任务。里程碑不能从 blocked 自动跳回 in_progress。

6. 验收证据和回归门禁

每个任务至少保留：

• native test；适用时必须有 WASM/Worker 对照 test。
• 正常、边界、非有限值、容量、错误、abort、pause/resume、恢复和离线样本。
• 输入 context、source hash、ABI/protocol/schema 影响和直接 evidence 路径。
• 状态 hash、event hash、首个 divergent tick 或明确的 REAL-EXCLUDED/BLOCKED 原因。
• 可重跑命令和报告 self-hash。

技术任务的最小回归：

python3 scripts/validate_baseline.py
python3 scripts/validate_download_index.py
python3 scripts/validate_task_pointer.py
scripts/build-wasm.sh
ctest --test-dir build-native --output-on-failure
for f in web/worker/test_*.mjs; do node "$f" || exit 1; done
for f in web/app/test_*.mjs; do node "$f" || exit 1; done

修改配置、协议、恢复或发布证据时，再运行对应的生成器专项测试和完整 Python unittest；生成器产生的报告不能被手工改 hash 伪装为通过。

7. 停止线

立即将当前任务标记为 blocked 并保留证据的情况：

1. LinuxCNC 来源、官方测试输入、配置资源或协议契约缺失。
2. 需要改变 ABI/protocol/schema/manifest 时，必须同步更新兼容性测试和迁移证据。
3. native/WASM 差异的首个 divergent tick 未定位。
4. 只能删除失败样本、降低检查、静默替换资源或把缺失能力改成 REAL-EXCLUDED 才能通过。
5. Python/组件/VCP 需要未经允许的宿主路径、设备、进程或网络能力。
6. checkpoint/journal 无法验证 hash、确认丢失无法对账或恢复会重复副作用。
7. 运行结果依赖未固定的墙钟、随机数、线程竞争或浏览器环境。

blocked 不是失败样本删除理由，也不是自动跳过前置任务的理由。修复后必须重新运行原任务的专属测试和完整回归，再认领下一个依赖满足的任务。

8. 当前实现基线

截至本计划建立时，仓库已有：

• WASM/native 核心构建、posemath、解释器、多个 kinematics、HAL、IO 和固定 tick 切片。
• Worker protocol/session、虚拟设备、Python bridge、workspace recovery 和前端基础面板。
• G-code PROGRAM_LOAD/RUN/PAUSE/RESUME/ABORT/STEP/SEEK、MDI_EXECUTE 的 Worker/WASM 垂直切片。

这些能力仍不能替代 M1-M8 的完整验收。下一项直接实现任务由 nextTask1.md 指向 P1-01：把已有 runner、解释器、motion/kinematics、HAL、IO 和 snapshot 统一纳入 sim_task.v1 authoritative state，并固定首个可对照的 tick 边界。