8.0 KiB
LinuxCNC Web/WASM 唯一来源迁移计划
目标
Web 仿真的行为、预览、轨迹、状态和错误必须由 LinuxCNC 源码编译出的 WASM core 决定。React/UI 只负责输入和渲染；Worker 只负责协议、生命周期和快照转发；不得由 JavaScript 重复解释 G-code、复制 TP/kinematics 规则或伪造 canonical state。
来源分层
| 层 | 唯一来源 | Web 允许做什么 | 禁止做什么 |
|---|---|---|---|
| RS274 | wasm-core/src/sim_interpreter.c 与 LinuxCNC rs274ngc |
分配内存、读取状态 | JS 重新解析 G/M/O 词 |
| Canonical motion | WASM interpreter motion event API | 排序、序列化协议 | JS 推导圆弧/整圆/终点 |
| TP/motion | sim_motion_queue / sim_kinematics_motion WASM API |
调用 tick、读取 sample | JS 插值、速度、队列进度 |
| Task | sim_task WASM state/canonical |
映射按钮状态 | JS 自己改变任务状态 |
| HAL/IO/tool/probe | WASM runtime canonical | 显示/转发事件 | JS 模拟设备结果 |
| UI | React | 发送命令、渲染 snapshot | 直接成为 authority |
任务安排
T0 基线审计和门禁
输入：WASM exports、Worker/React source、现有 native/WASM/Worker reports。
产出：来源审计报告、JS authority 清单、当前功能矩阵、固定 3-axis baseline hash。
验收：报告能明确列出每个用户可见行为的唯一来源；现有 3dtest.ngc Web/native baseline 可重复。
停止条件：来源或 ABI 不明确时，不把 JS fallback 标为 WASM parity。
T1 WASM canonical motion event
输入：sim_interpreter state/modal implementation、LinuxCNC rs274ngc canonical callbacks、posemath segment types。
产出：WASM sim_interpreter_read_motion/motion-event buffer，覆盖 G0/G1/G2/G3、G17/G18/G19、IJK/R、G20/G21、G90/G91、螺旋轴变化和 source line。
验收：C native test、WASM test、Worker test 对同一程序输出相同 segment count、source line、端点、center、normal、turn、units 和 hash。
T2 WASM-backed preview
输入：T1 motion events。
产出：Worker PROGRAM_PREVIEW，React 只消费 snapshot/toolpath；删除 previewGcode 作为行为来源。
验收：3dtest.ngc 三个整圆和 XYZ extents 与原生 AXIS 对齐；无 WASM event 时 fail closed，不回退到 JS 解析器。
T3 WASM-backed visible execution
输入：T1 events、WASM TP/kinematics/motion APIs。
产出：运行、暂停、恢复、单步、停止、末段排空全部由 WASM tick/queue state 驱动；移除 AuthoritativeRuntime 的运动 authority。
验收：浏览器点击 Power/Home All/Run 后 DRO、当前行、Three.js tool pose、queue depth、最终 M2 endpoint 与 native sequence 对齐。
T4 WASM canonical state
输入：WASM task/motion/HAL/IO/tool/probe canonical APIs。
产出：Worker snapshot 只转发 WASM canonical；React gate 只读取 snapshot；逐轴 home、limit、estop、tool、spindle、coolant、probe 状态一致。
验收：snapshot hash、event hash、checkpoint/recovery hash 在 native/WASM/Worker 重复运行中稳定。
T5 完整功能矩阵
输入：LinuxCNC source inventory、unit tests、真实 INI/HAL/NGC fixtures。
产出：按 RS274、TP、kinematics、HAL、IO、Python/remap、配置、恢复、浏览器 UX 分层的 native/WASM/Worker matrix。
验收：每项为 verified、blocked 或 queued，均有 owner、输入、测试、差异和停止原因；不允许用 selected-case 结果覆盖全量。
T6 功能闭合
按矩阵逐项实现：RS274 G/M/O/canned/compensation，TP blend/exact-stop/accel/jerk，HAL component/PLC，IO/tool/probe，Python/remap/filter/VCP，配置资源和恢复边界。
每一项必须先有 LinuxCNC source reference，再有 WASM C test，再接 Worker/UI；任何宿主进程、动态库、真实设备或墙钟行为保持排除。
T7 发布门禁
必须同时通过：WASM build、CTest、native source adapters、Worker tests、React typecheck/build、浏览器可见执行、native AXIS screenshot、功能矩阵和 release closure。仍有 STOP_RELEASE blocker 时只能报告 blocked，不能宣称完成。
当前执行状态
T0 已完成：来源审计报告为 coverage/wasm-only-source-audit.report.json，selected-case baseline 通过但整体保持 blocked。
T1 已完成第一切片：sim_interpreter_read_motion 和 sim_interpreter_motion_size 已导出，Worker ProgramRunner 能读取 WASM canonical segment；native/WASM interpreter test 和 web/worker/test_wasm_motion_event.mjs 通过。T1 的完整覆盖仍需补齐 R 弧、螺旋、同步运动和 canonical queue 排序。
当前 T2 的 selected-case 切片已完成：PROGRAM_LOAD 返回 WASM canonical preview segments，React 只消费 Worker toolpath；visual-workflow.ts 不再参与行为预览。T2 仍需扩展到完整 canonical callback、canned cycle、R 弧、同步运动和所有配置族。
T3 的 selected-case 切片已完成：WASM motion queue 接收 interpreter canonical segments，负责固定 tick 的 position/velocity/queue depth；3axis-tutorial trivkins 运行路径不调用 AuthoritativeRuntime.syncProgram/step/applyMotion，pause/resume、PROGRAM_STEP、abort 和末段排空均由 queue 状态驱动。queue raw state、active segment、tick、controls、position 和 hash 已纳入 checkpoint、trace/workspace state；恢复 replay 与连续 endpoint hash 相同，损坏 queue state fail-closed。Worker snapshot 公开 motion_authority: wasm 与 source: wasm_motion_queue。JS AuthoritativeRuntime 仍只作为非 selected-case/非 trivkins 兼容镜像，program-runner/motion-state/sim-task 的其它 canonical state 仍待 T4/T5；因此整体 source-of-truth audit 仍为 blocked。
T4 selected-case 切片已完成：Worker SimTask 通过 sim_task_canonical 读取 WASM task state，WasmHomeLimit 通过锁定 sim_kinematics_home_limit_* ABI 读取 trivkins home/limit state；snapshot、checkpoint、trace/import 和 recovery 都带 task/home-limit authority、state hash 和 logical tick。JS task tamper 不覆盖 WASM canonical state，损坏 home-limit bytes fail-closed。HAL/IO/tool/probe canonical state、外部设备 limit 输入和非 selected-case compatibility 仍保持开放，整体 audit 仍 blocked。
T5 已生成 coverage/wasm-feature-matrix-t5.report.json：RS274、TP、kinematics、HAL、IO、Python/remap、configuration、recovery、browser UX 九个领域均有 native/WASM/Worker 行、输入 hash、测试命令、覆盖样本、差异和停止原因。对照 LinuxCNC AXIS 源码修复空/缺失 OPEN_FILE 语义并将缺失 HALFILE 分类为 BLOCKED_HAL 后，235-case matrix 恢复 verified，分类为 BLOCKED_HAL=106/BLOCKED_RESOURCE=11/TASK_READY=96；完整 oracle、配置资源、三浏览器 minimum 和物理 OPFS recovery 仍 blocked，不将 selected-case 结果提升为全量 parity。
T6 已完成 source-backed closure audit，但保持 blocked：八个矩阵 closure row 均有真实 source reference、可执行 WASM/Worker slice 和 23 个通过的专项命令，另保留 4 个 failure samples。完整 RS274/TP/kinematics 仍缺官方 oracle，配置仍有 exact-resource blockers，HAL/IO/Python 仍受 REAL-EXCLUDED 能力边界限制，恢复和浏览器仍缺物理 OPFS/三浏览器输入；没有使用 JS fallback 或 selected-case promotion。
T7 已完成 simulation-track 的只读 release-gate audit，报告为 blocked：T6 closure、既有 release/remediation evidence、owner refresh 和六项 blocker identity 均核对通过，但 candidate 仍不可 eligible、STOP_RELEASE 保持。该 audit 不刷新 K8 gate、不修改 context lock、manifest、许可证或 owner decision；没有新输入时不自动重试或升级 release。
源语义已固化为 coverage/linuxcnc-source-semantics-contract.json 与 web/workspace/linuxcnc-source-semantics.mjs，供后续 Web 控制面板直接复用。控制面板只能投影 Worker 的 startup snapshot；OPEN_FILE/INTRO_GRAPHIC optional、BLOCKED_HAL/BLOCKED_RESOURCE 分类、exact-path 和 runtime fixture policy 均由该契约决定。