linuxcncWebWASM/docs/linuxcnc-web-wasm-implementation-readiness.md

LinuxCNC Web/WASM 实施准备基线

状态：M0 已落地，M1 ABI 骨架已验证，LinuxCNC 功能移植尚未完成 目标：把既有技术路线收敛成可执行的实施顺序、完整性证明和发布前置条件 固定基线：LinuxCNC 2.10.0~pre0，提交 239dcf4284762ad7e9c65d390bc5524d855c2f8e 关联文档：技术路线、覆盖矩阵、源程序关联、通信设计、执行策略、总控手册

本文件是开始编写程序前的单页入口。专项文档保留详细契约；本文件只固定真实基线、先后顺序、完成定义和阻断条件。

1. 现状和不可误读项

本仓库已经具备完整设计文档，但此前没有 Web/WASM 运行时代码。当前 M0/M1 产物如下：

产物	当前事实	允许的结论
context-lock.json	锁定 LinuxCNC 提交、Emscripten 3.1.6、schema v1 和索引哈希	基线可复现
coverage/source-index.jsonl	7,992 个来源文件，来自 docs/src/configs/tests/unit_tests/build	来源扫描已开始，可审计
coverage/manifest.jsonl	7,992 个一对一种子条目，全部 planned/needs_owner	没有来源被静默漏掉；不代表已实现
wasm-core	C ABI 生命周期、固定 tick、快照、导入导出骨架	工程边界可编译、可调用
build-wasm/build-native	WASM 模块生成，宿主 ABI 单测通过	构建链路可重跑

以下能力目前都不能声明完成：rs274ngc、TP、motion、kinematics、HAL、ClassicLadder、Python/remap、OPFS、Worker、UI、Three.js、全量配置和浏览器回归。

2. 产品边界和“完整”的定义

产品是浏览器内离线运行的 LinuxCNC 仿真机床。状态权威在 Worker 内的 WASM/兼容运行时，主线程只负责 UI 和渲染；所有影响结果的操作都经过固定 tick、版本化协议和可恢复账本。

功能全集由以下集合并集产生，而不是由一组三轴演示决定：

LinuxCNC 文档能力
∪ src/emc、src/hal、classicladder、lib/python 的可观察 API/符号
∪ configs/sim/** 的全部入口和引用资源
∪ tests/**、unit_tests/** 的全部可运行用例
∪ Web 工程、VCP、可视化、持久化和恢复工作流

每个功能必须同时闭合：正常、边界、错误/报警、暂停/恢复/急停、持久化/刷新/离线，以及适用的跨域交互。accepted 必须有实现、自动测试、oracle、差异报告和 context lock。真实硬件、内核实时性、物理安全和宿主设备访问只能标记 REAL-EXCLUDED，且配置检查必须返回明确错误；仿真配置依赖的主轴、编码器、探针、限位、换刀和 IO 必须用数字孪生实现。

3. 已冻结的技术决策

1. 核心优先复用：posemath、rs274ngc、TP、可移植 kinematics 优先以最小补丁编译；Linux 进程、NML/CMS、共享内存、实时 API、动态加载和桌面 GUI 不直接移植。
2. 单 Worker、单写者：WASM、Python、HAL、虚拟设备、工作区和恢复全部在同一 Dedicated Worker 中串行；UI 不读 WASM 指针、不直接写 OPFS。
3. 确定性时间：sim_step(cycles) 是唯一推进入口；墙钟只负责节流和渲染，不参与结果计算。1x、快速、暂停恢复、单步和回放必须得到同一逻辑终点。
4. 两层文件系统：WASM 内同步工作树承接 LinuxCNC 文件语义；Worker 通过 OPFS journal、checkpoint 和迁移持久化，不能每个 tick 写 OPFS。
5. 稳定 C ABI：TypeScript 只见版本化 C ABI 和消息 schema，不暴露 C++ 布局、STL、指针或异常字符串。
6. Python 受控运行时：PY-01 前不锁定运行时；启用后必须单独创建锁，固定 Pyodide、包、补丁和 artifact hash，只提供 linuxcnc/hal/INI 虚拟模块，拒绝 subprocess、socket、设备和宿主路径。
7. 镜像可替换、字节不可替换：允许中国大陆镜像、官方站点和离线缓存；下载记录必须包含 URL、版本、大小、SHA-256、许可证。镜像切换但字节相同不改变 context；字节、补丁或版本变化必须生成新 context。
8. 先建立 oracle 再扩展功能：原生 LinuxCNC runner 输出解释器状态、canonical、每周期运动、HAL/IO、错误和最终状态；WASM 只以首个 divergent tick、字段差异和定义容差对照。

4. 完整移植功能分层

层	必须覆盖的能力	实现策略	完成证据
L0 配置/工作区	INI/include、HALFILE 顺序、TBL/VAR/NGC/PY/XML/TCL/CLP、路径和诊断	虚拟 /workspace + 解析器 + OPFS	233 个 sim INI 全部资源图；错误含文件/行
L1 解释器	全部 G/M/O、模态、单位、坐标系、参数、循环、补偿、remap 边界	复用 rs274ngc；Python 通过受控桥接	G/M/O manifest、错误行和 golden
L2 轨迹/运动	canonical、前瞻、blend、速度/加速度、急停、暂停、jog、home、limit、following error	TP/posemath 复用；sim_motion 状态机	每 tick 状态、容差、恢复终点
L3 运动学	trivkins、5 轴、gantry、CoreXY、Delta、机器人、foam 等内置模块	静态编译注册，按配置选择	forward/inverse、姿态、奇异/越限错误
L4 HAL/PLC	pin/signal/param、thread/function/addf、全量仿真组件、ClassicLadder	.comp 构建期清单 + 固定扫描顺序	组件条目、HAL graph、scan/golden
L5 虚拟设备	主轴、编码器、stepgen、探针、限位、换刀、冷却、等离子/激光	可脚本化数字孪生和故障注入	正常/不到速/超时/失败/恢复
L6 Python/VCP	linuxcnc/hal API、remap/filter、VCP 回调和权限	Pyodide Worker + manifest 能力授权	API/异常/资源限制/隔离
L7 Web 工作流	工程、编辑器、MDI、run/pause/abort、jog/home、工具/IO/报警、HAL/PLC	React+TS，WorkerClient，domain store	浏览器 E2E、键盘/触摸、恢复
L8 可视化/发布	轨迹、姿态、刀具、毛坯、日志、导入导出、离线 PWA、兼容/许可证报告	Three.js + transferable streams + 发布清单	多浏览器、性能、离线和回滚演练

5. 可执行路线和退出条件

M0：基线和来源闭包（已完成第一版）

入口是 LinuxCNC 版本和提交已确认。必须生成 source index、manifest seed、context lock、状态枚举、扫描器版本和下载策略。退出条件是索引/manifest 哈希与锁一致，重复 ID、孤儿来源和缺字段检查生效。

M1：最小运行时闭环（当前）

先完成 sim_create → sim_load_workspace → sim_command → sim_step → snapshot/event → export/import → destroy，固定 ABI、错误码、消息 envelope、Worker 单会话队列和虚拟工作区最小接口。正常、非法状态、buffer 不足、暂停/恢复各至少一条测试；不得接 UI mock 作为完成证据。

M2：解释器和运动核心

按 posemath → TP → rs274ngc → canonical → task/motion → kinematics 顺序接入。每个切片先接原生 runner 和差异报告，再接 Worker。M2 退出前，受影响核心条目必须达到 verified，且任何差异能定位到首个 tick/字段/源映射。

M3：HAL、数字孪生、Python、持久化

接入 HAL 图和固定线程顺序，再接主轴/编码器/探针/限位/换刀/PLC；随后实现 OPFS prepare/commit、checkpoint、迁移、配额和 Worker 崩溃恢复，最后锁定 Python runtime 并接 remap/VCP。M3 不允许用“刷新后重新初始化”替代恢复。

M4：Web 工作流和可视化

以真实 Worker/WASM 状态接入工程选择、编辑器、MDI、run/pause/abort、jog/home、工具/报警、HAL/PLC、3D、导入导出和离线 PWA。mock 只能用于早期 UI 结构开发，里程碑退出必须全部切换真实协议。

M5：全量回归和发布

递归运行全部 configs/sim/**、可移植 tests/**、unit_tests/**、G/M/O、HAL 组件、Python API 和浏览器故障矩阵。发布包必须同时包含 WASM、Python 运行时、Service Worker、schema、source/coverage/golden manifest、兼容报告、排除项和回滚包；任何孤儿、无 oracle、未覆盖维度或静默降级都阻断发布。

6. 实施顺序（直接照此开工）

1. 保持 context-lock.json 不变，运行 M0 校验和上下文包测试。
2. 为 coverage/manifest.jsonl 建立 owner/feature/domain 分配器，将 seed:* 按功能归并但保留一对多来源引用。
3. 在原生 LinuxCNC 环境建立 runner，先覆盖 unit_tests/interp、unit_tests/tp 和 configs/sim/axis/minimal_xyz.ini，冻结 JSONL golden schema。
4. 将 wasm-core 从 bootstrap API 扩展为 posemath/TP 最小链接；每加入一个源组就更新 manifest、编译参数和 ABI 测试。
5. 实现固定 tick scheduler、事件队列、快照 schema 和 WorkerClient；先完成命令幂等和 prepare/verify/commit 账本。
6. 实现虚拟工作区的 open/read/write/stat/readdir/rename/unlink/fsync，然后接 OPFS journal 和恢复，不提前接高频 UI。
7. 接 HAL 核心和最小三轴数字孪生，完成正常/限位/急停/恢复四条端到端场景。
8. 锁定 Python runtime（允许中国镜像下载，但必须记录校验）并接 linuxcnc/hal、remap 和一个 VCP descriptor。
9. 接 React/TypeScript AppShell、状态面板、G-code/MDI 和 Three.js 轨迹；只消费 Worker 快照和 transferable 流。
10. 扩展全部配置、组件、运动学、GUI 工作流和回归矩阵，按 M2-M5 门禁推进。

7. 必须持续保持的检查

python3 scripts/generate_source_inventory.py
python3 scripts/validate_baseline.py
python3 scripts/validate_download_index.py
python3 -m unittest discover -s scripts -p 'test_*.py' -v
scripts/build-wasm.sh

清单重生成后若哈希变化，必须先审查来源差异并创建新 context；不能直接覆盖锁文件。任何新下载都必须进入 vendor/downloads/index.jsonl（M1 前建立），任何新源码、配置或测试都必须在同一变更中更新 manifest。只有 validate_baseline、受影响测试、原生/WASM 对照和相应恢复场景都通过，任务才可从 implemented 进入 verified。

8. 当前明确风险

• 现有 LinuxCNC meson.build 面向原生依赖（Python、Boost、libdl），不能直接作为 Emscripten 构建；WASM 必须保持独立 CMake 目标。
• configs/sim 文件量大且资源类型复杂，清单生成必须先于功能归并；不能用目录状态或抽样配置宣称全覆盖。
• 浏览器没有 PREEMPT_RT；任何依赖墙钟的行为都必须改成逻辑 tick，并单独报告实时性不等价。
• OPFS 有配额和淘汰风险；已提交版本、导出备份和配额错误必须优先于自动保存便利性。
• Python、GUI 和 HAL 组件是最大移植面；它们必须按受控能力和静态清单接入，不允许把宿主进程/设备能力直接暴露给工程脚本。

当前基线允许开始编写程序，但只允许从 M1 的 ABI、runner、工作区和协议契约开始；在 M0/M1 证据闭合前，不应投入全量 UI 或声称 LinuxCNC 功能已经移植完成。