Advance simulation parity and 3-axis tutorial coverage

2026-08-23 18:00:56 +08:00
parent 4a11d9692b
commit 938654b19d
107 changed files with 13537 additions and 3565 deletions
--- a/docs/linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md
+++ b/docs/linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md
@@ -0,0 +1,238 @@
+# 3axis Tutorial 全功能对标总方案
+
+## 0. 目标和执行边界
+
+唯一目标案例：
+
+`/home/mes006/linuxcncWebWASM/linuxcnc/configs/sim/axis/vismach/3axis-tutorial`
+
+入口文件：
+
+`linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial.ini`
+
+目标不是“再做一个示例”，而是把该案例在 LinuxCNC 中可观察的配置、启动、运动、解释器、HAL、工具、主轴、冷却、探针、Vismach、AXIS UI、持久化和恢复行为逐项映射到 WASM + Dedicated Worker + React + Three.js。后续任务不得切换到其它 `configs/sim` 案例；其它案例只能作为通用模块回归输入，不能作为本案例完成证据。
+
+明确排除：实时内核调度、真实硬件、PCI/串口设备、宿主动态 loader、宿主 Python GUI 进程。排除项必须有 `REAL-EXCLUDED`/`HOST_EXCLUDED` 诊断，不得静默删除功能。
+
+## 1. 锁定输入和执行规约
+
+### 1.1 Exact 输入
+
+| 输入 | 作用 | 规则 |
+|---|---|---|
+| `3axis-tutorial.ini` | AXIS、Task、RS-274、TRAJ、EMCIO、KINS、AXIS/JOINT limits | 原路径、原始字节和 source line 保留 |
+| `3axis-tutorial.hal` | trivkins/motmod/ddt/hypot、反馈环、手动换刀、Vismach pins | 按原顺序解析 `loadrt/addf/net/loadusr` |
+| `3axis-tutorial` | Vismach Python model 和 5 个 HAL pins | Web 使用源码驱动 `WEB-EQUIV` adapter，不运行宿主 Python |
+| `tool.tbl` | T1/T2/T3/T99999 工具、长度和直径 | exact path；工具状态必须可恢复 |
+| `linuxcnc/linuxcnc.gif` | `DISPLAY.INTRO_GRAPHIC` | 仅作为 shared display asset |
+| runtime `.var/.bak/position_mm.txt` | 参数、备份、位置持久化 | 运行时生成，写入 workspace journal，不作为 source fixture |
+
+### 1.2 Native 标准命令
+
+每次运行前必须停止本 runner 或历史运行留下的 `linuxcncsvr`、`rtapi_app`、`milltask`、`halui`、`iocontrol`、`axis`，确认没有活动进程持有 `/tmp/linuxcnc.lock`；只允许在 lock 无活动持有者时删除 stale lock。
+
+然后固定使用：
+
+```bash
+cd /home/mes006/linuxcncWebWASM/linuxcnc
+linuxcnc <isolated-case-dir>/3axis-tutorial.ini
+```
+
+成功条件同时包括：
+
+- `update_ini -f` 在隔离目录成功；
+- AXIS WM class 为 `axis / Axis`；
+- 标题含 `3axis-tutorial`；
+- 窗口至少 `600x400`；
+- native log 没有未分类首错；
+- 记录生成的 `.var/.bak/position_mm.txt`；
+- 退出后 LinuxCNC 服务和 lock 清理完成。
+
+禁止用 timeout、`Starting LinuxCNC`、后台 `task:`、进程存在或 lock 文件存在替代窗口证据。
+
+## 2. 全功能对标清单
+
+### 2.1 配置、资源和流程
+
+1. `VERSION/MACHINE/DEBUG` 解析和 `update_ini` 迁移。
+2. `[DISPLAY]`：AXIS、cycle time、relative/actual 初始显示、feed/spindle override、increments、program prefix、intro graphic、file filters。
+3. `[RS274NGC]`：参数文件路径、缺失文件空初始化、保存和 `.bak` 策略。
+4. `[EMCMOT]/[TASK]/[EMCIO]`：motmod、milltask、io、cycle/servo period、tool table、tool-change position。
+5. `[TRAJ]`：3 axes、XYZ、mm/degree、速度、加速度、position file、arc blend 参数。
+6. `[KINS]/[AXIS_X/Y/Z]/[JOINT_0/1/2]`：trivkins identity、limits、velocity、acceleration、scale、FERROR、MIN_FERROR、home offset。
+7. HAL 文件和 `LIB:`/相对路径解析保持 exact path、行号、顺序、缺失诊断。
+8. 启动状态映射：`NEW -> MOUNTED -> PARSED -> RESOLVED -> CORE_CREATED -> HAL_READY -> TASK_READY`。
+9. 退出状态映射：停止、HAL unload、服务退出、参数/位置提交和 journal close。
+
+### 2.2 运动、Task 和解释器
+
+1. MANUAL/MDI/AUTO 模式和 READY/RUNNING/PAUSED/STOPPED/ESTOP/FAULT 状态。
+2. X/Y/Z 全部 home、独立 jog、连续/增量 jog、stop、速度/加速度、override。
+3. trivkins pose/joint identity、commanded/actual/relative DRO。
+4. X `[-500,500]`、Y `[-100,100]`、Z `[-240,0.001]` limits。
+5. following error、limit fault、fault latch、recover 和禁用条件。
+6. `G20/G21`、`G90/G91`、`G0/G1`、F feed、G17/G40/G49/G54/G64、G10/G92、M2/M30、参数表达式和错误列。
+7. PROGRAM_LOAD/RUN/PAUSE/RESUME/STEP/SEEK/ABORT/RESTART、MDI 队列和活动程序期间 MDI 拒绝。
+8. fixed tick 1x/fast/step 与 pause/recovery endpoint parity。
+
+### 2.3 HAL、工具、主轴、冷却、探针和故障
+
+1. `trivkins`、`motmod`、6 个 ddt、2 个 hypot 的 component/thread/function 记录。
+2. 三轴 motor-pos-cmd 到 motor-pos-fb 的 loopback。
+3. velocity/acceleration 派生信号 `Xvel/Yvel/Zvel/XYvel/XYZvel`。
+4. estop loopback、`hal_manualtoolchange` prepare/change/changed 生命周期。
+5. Vismach pins：`jointX/jointY/jointZ/toollength/tooldiameter`，pin direction/type 和 net 连接。
+6. T1/T2/T3/T99999 prepare、pocket、change、abort、fault、clear。
+7. spindle direction/RPM、ramp、at-speed、encoder/index、inhibit、orient、fault。
+8. mist/flood/lube request、interlock、coolant fault 和恢复。
+9. probe arm/input/trip/latched position/disarm；没有 source pin 时保留 capability boundary。
+10. ESTOP、door/interlock、following-error、limit、tool/spindle/coolant fault 的错误码、message key、状态 hash 和 UI gate。
+
+### 2.4 Vismach 和 AXIS UI
+
+1. frame/base/column/top、X table/work、Y assembly、Z frame/spindle、CAT30/tool/tooltip 的几何层次。
+2. `HalTranslate` 对 jointX/Y/Z 的轴向变换和工具长度/直径变化。
+3. tool cylinder 半径、z offset、当前工具和 tooltip 连续性。
+4. AXIS File/Machine/View/Help 菜单、快捷键、toolbar icon、F3 Manual、F5 MDI、Preview、DRO、G-code editor、active G-codes。
+5. DRO machine/relative、actual/commanded、mm/inch、tick/hash。
+6. Three.js canvas 非空像素、pose/joint/toolpath/limits/layers、desktop/mobile 不重叠。
+7. 控件 enable/disable 必须来自 Worker snapshot；所有不可用操作必须显示诊断。
+
+### 2.5 持久化、恢复和证据治理
+
+1. `.var` 缺失/空文件/参数写入/`.bak` 生成/重启恢复。
+2. `position_mm.txt` 保存、读取、恢复和错误处理。
+3. `tool.tbl` 读取、工具状态更新、workspace commit 和重启恢复。
+4. checkpoint、event cursor、journal、trace import、replay endpoint equality。
+5. recovery 不重复已提交副作用；坏 checkpoint、seq gap、tick regression、未知 event 必须 fail-closed。
+6. 每个报告保存 context id、输入 hash、输出 hash、命令、首个 divergent phase/tick、失败样本和 self-hash。
+
+## 3. 实施任务和依赖
+
+| ID | 实施结果 | 主要输出 | 依赖 |
+|---|---|---|---|
+| `TUTORIAL-00` | 锁定源目录、隔离副本、服务清理和 native AXIS runner | native report + AXIS screenshot | 无 |
+| `TUTORIAL-01` | exact INI/HAL/resource graph 和 runtime file policy | resource graph report | 00 |
+| `TUTORIAL-02` | HAL manifest、loadrt/addf/net、Vismach `WEB-EQUIV` adapter | HAL adapter report | 01 |
+| `TUTORIAL-03` | startup phase、TASK_READY、loader/startup hash | startup report | 01/02 |
+| `TUTORIAL-04` | home/jog/limit/FERROR/trivkins fixed tick | motion report | 03 |
+| `TUTORIAL-05` | RS-274/G-code/MDI/program controls | program report | 04 |
+| `TUTORIAL-06` | tool/spindle/coolant/probe/ESTOP/IO full matrix | tool-io report | 03/05 |
+| `TUTORIAL-07` | Vismach geometry graph、pin-to-pose、tool continuity | model report + canvas samples | 02/04/06 |
+| `TUTORIAL-08` | AXIS menus、DRO、tabs、editor、gates、mobile layout | DOM/visual report | 03/05/07 |
+| `TUTORIAL-09` | var/tool/position commit、checkpoint/journal/replay | persistence report | 05/06/08 |
+| `TUTORIAL-10` | same operation sequence native/Worker/UI integrated acceptance | complete scoped report | 00..09 |
+| `TUTORIAL-11` | probe and complete tool-offset behavior closure | probe/tool report + native/Worker diff | 06/09/10 |
+| `TUTORIAL-12` | native/Web same-sequence recorder and first-divergence report | sequence ledger + endpoint comparison | 10/11 |
+| `TUTORIAL-13` | persistence restart with explicit service/lock cleanup and visual recovery evidence | restart report + screenshots | 09/12 |
+| `TUTORIAL-14` | final selected-case acceptance freeze and evidence index | signed/self-hashed closure index | 11/12/13 |
+
+当前 `TUTORIAL-00..10` 的已验证报告必须继续复用；下一阶段从 `TUTORIAL-11` 开始，不得重复创建其它案例任务。
+
+当前执行状态：`TUTORIAL-11` verified；`TUTORIAL-12` verified with source-defined individual `Z/X/Y` homing and real `change_button` ACK；`TUTORIAL-13` verified after replay-order fix；`TUTORIAL-14` verified as selected-case closure index. Firefox/Safari、OPFS physical crash、realtime hardware 和 full release 仍是独立外部边界。
+
+## 4. 统一实施顺序
+
+每个任务执行以下固定步骤：
+
+1. 读取 `nextTask1.md`、context lock 和本任务直接输入。
+2. 服务清理；native exact command；保留截图、日志和 source hash。
+3. 先新增失败边界测试，再实现最小 vertical slice。
+4. Worker 使用真实 WASM 和固定 logical tick；不使用 mock Worker 作为完成证据。
+5. React 只消费 Worker authoritative state；UI gate、错误和状态不能本地猜测。
+6. 运行任务专项测试、native CTest、WASM build、selected-case Worker/App 回归。
+7. 生成 self-hashed report，记录正常、边界、错误、非有限、容量、暂停/恢复/终止和确定性 hash。
+8. 只有当前任务达到验收条件才更新指针；若输入、oracle 或环境缺失，保留 `blocked` 和 failure sample。
+
+## 5. 验证计划
+
+### 5.1 基线和构建
+
+```bash
+python3 scripts/validate_baseline.py
+python3 scripts/validate_task_pointer.py nextTask1.md
+scripts/build-wasm.sh
+ctest --test-dir build-native --output-on-failure
+cd web/react && npm run typecheck && npm run build
+```
+
+### 5.2 Native 验证
+
+```bash
+python3 scripts/run_axis3_tutorial_native.py \
+  --output coverage/axis3-tutorial-native-run.report.json \
+  --screenshot coverage/axis3-tutorial-visual/native-axis.png
+python3 scripts/test_axis3_tutorial_native.py
+```
+
+必须检查：窗口 class/title/geometry、服务清理、lock、exact source hashes、生成文件、首错和截图 hash。
+
+### 5.3 Worker/WASM 验证
+
+```bash
+node web/worker/test_axis3_selected_case.mjs
+node web/worker/test_axis3_tutorial_hal_adapter.mjs
+node web/worker/test_axis3_tutorial_startup.mjs
+node web/worker/test_axis3_tutorial_motion.mjs
+node web/worker/test_axis3_tutorial_program.mjs
+node web/worker/test_axis3_tutorial_tool_io.mjs       # TUTORIAL-06/11
+node web/worker/test_axis3_tutorial_persistence.mjs   # TUTORIAL-09/13
+node web/worker/test_axis3_tutorial_sequence.mjs     # TUTORIAL-12
+```
+
+每个 Worker endpoint 必须同时记录 `task/program/motion/joints/devices/hal/authoritative/state_hash`，不能只断言 `status=verified`。
+
+### 5.4 React/Chromium 验证
+
+```bash
+npm --prefix web/react run preview -- --port 5174
+python3 scripts/generate_gui_browser_visual_report.py
+python3 scripts/test_gui_browser_visual_report.py
+```
+
+桌面 `1440x900` 和移动 `390x844` 都必须有：DOM marker、4 tabs/tabpanel 关系、至少 20 toolbar icons、ARIA labels、非空截图、Three.js canvas、case selector、DRO、G-code、Manual/MDI 和无重叠布局。
+
+### 5.5 Integrated acceptance
+
+```bash
+python3 scripts/generate_axis3_tutorial_complete_report.py
+python3 scripts/test_axis3_tutorial_complete_report.py
+python3 scripts/validate_baseline.py
+python3 scripts/validate_task_pointer.py nextTask1.md
+```
+
+统一逻辑序列：启动 -> 全轴 home -> X/Y/Z jog -> override -> MDI -> G-code load/run -> pause/resume/step -> abort/restart -> tool prepare/change -> spindle/at-speed -> coolant -> probe -> limit/FERROR/ESTOP -> checkpoint -> 继续一个 tick -> recover -> persistence restart。native、Worker 和 UI 必须使用同一操作 ID 顺序；时间只用 logical tick。
+
+## 6. 通过、阻塞和停止条件
+
+### 通过
+
+- exact path 和 source hash 一致；
+- native AXIS 窗口真实可见；
+- Worker `TASK_READY` 且 HAL blocked count 为 0；
+- native/Worker endpoint 和恢复 hash 可解释；
+- UI 证据有持久化图片、DOM hash 和 canvas 非空；
+- report self-hash 和 pointer validation 通过。
+
+### 保持 blocked
+
+- native 服务或 lock 未清理；
+- 首个 divergent tick/phase 未定位；
+- probe/tool offset 没有 source 或实现契约；
+- checkpoint/event/hash 不可验证；
+- 只能依赖墙钟、随机数、宿主 Python、mock Worker 或真实硬件；
+- Firefox/Safari/OPFS/oracle 外部条件缺失。
+
+### 不得宣称
+
+该方案的 `verified` 只代表固定 `3axis-tutorial` 选定案例范围。它不代表 LinuxCNC 全功能、235-case acceptance、实时硬件、Firefox/Safari release 或 owner/license gate 已完成。
+
+## 7. 当前证据索引
+
+- 总报告：`coverage/axis3-tutorial-complete.report.json`
+- Native：`coverage/axis3-tutorial-native-run.report.json`
+- Resource graph：`coverage/axis3-tutorial-resource-graph.report.json`
+- Program：`coverage/axis3-tutorial-program.report.json`
+- Chromium visual：`coverage/gui-browser-visual-fe-m4.report.json`
+- 图片目录：`coverage/axis3-tutorial-visual/`
+- 接续入口：`nextTask1.md`
--- a/docs/linuxcnc-web-wasm-3axis-tutorial-parity.md
+++ b/docs/linuxcnc-web-wasm-3axis-tutorial-parity.md
@@ -0,0 +1,102 @@
+# 3axis Tutorial 案例对标实施文档
+
+**唯一案例**：`linuxcnc/configs/sim/axis/vismach/3axis-tutorial`
+**入口 INI**：`linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial.ini`
+**机床**：3 轴笛卡尔、`trivkins`、X/Y/Z、3 joints、AXIS + Vismach
+**范围**：LinuxCNC 源程序案例与 Web/WASM 仿真的功能、流程、界面三层对标
+**状态**：单案例执行、功能、流程、界面、真实 individual home、真实 `change_button` tool ACK 和恢复证据已闭合；完整 235-case/release 仍不在本案例范围
+
+**完成总报告**：[`coverage/axis3-tutorial-complete.report.json`](../coverage/axis3-tutorial-complete.report.json)
+
+下一阶段总控方案：[`linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md`](linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md)。
+
+状态机契约：[`linuxcnc-web-wasm-3axis-tutorial-state-machine.md`](linuxcnc-web-wasm-3axis-tutorial-state-machine.md)。
+
+**持久化图片证据**：native AXIS [`native-axis.png`](../coverage/axis3-tutorial-visual/native-axis.png)、Chromium desktop [`chromium-desktop.png`](../coverage/axis3-tutorial-visual/chromium-desktop.png)、Chromium mobile [`chromium-mobile.png`](../coverage/axis3-tutorial-visual/chromium-mobile.png)。
+
+后续工作只允许围绕这个案例展开。其它 `configs/sim` 案例、全量 matrix、其它机床族和 release closure 不属于本任务。
+
+## 1. 已锁定的 exact 输入
+
+案例目录中仅以下四个文件由 native runner 复制到隔离可写目录：
+
+| 文件 | 用途 |
+|---|---|
+| `3axis-tutorial.ini` | AXIS、Task、RS-274、HAL、TRAJ、KINS、AXIS/JOINT limits |
+| `3axis-tutorial.hal` | trivkins/motion/ddt/hypot、estop、manual toolchange、Vismach pins |
+| `3axis-tutorial` | LinuxCNC Vismach Python model；Web 侧对应 Three.js model adapter |
+| `tool.tbl` | 工具表和 tool-change 输入 |
+
+运行时生成的 `3axis-tutorial_mm.var`、`.bak`、`position_mm.txt` 不复制为 source fixture，由 LinuxCNC/Web workspace 在运行时创建或提交。`INTRO_GRAPHIC = linuxcnc.gif` 通过 `linuxcnc/linuxcnc.gif` 共享资产语义解析。
+
+源程序关联：
+
+- 启动：`linuxcnc/scripts/linuxcnc.in`、`linuxcnc/scripts/update_ini`。
+- INI：`linuxcnc/src/libnml/inifile/**`、`linuxcnc/src/emc/ini/**`。
+- Task/IO：`linuxcnc/src/emc/task/**`、`linuxcnc/src/emc/iotask/ioControl.cc`、`linuxcnc/src/emc/tooldata/**`。
+- Motion/Kinematics：`linuxcnc/src/emc/motion/**`、`linuxcnc/src/emc/kinematics/trivkins.c`、`linuxcnc/src/emc/tp/**`。
+- HAL：案例 `3axis-tutorial.hal`、`linuxcnc/src/hal/hal_lib.c`、`linuxcnc/src/hal/utils/halcmd*`、`linuxcnc/src/hal/components/{ddt,hypot,sim_home_switch}.comp`。
+- Vismach：`linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial`、`linuxcnc/lib/python/vismach.py`、`linuxcnc/lib/python/hal.py`、`linuxcnc/lib/python/linuxcnc.py`。
+- AXIS UI：`linuxcnc/src/emc/usr_intf/axis/scripts/axis.py`、`linuxcnc/lib/python/rs274/glcanon.py`。
+
+## 2. 正确 native 执行规约
+
+执行器为 `scripts/run_axis3_tutorial_native.py`，报告为 `coverage/axis3-tutorial-native-run.report.json`。
+
+1. 创建临时可写目录。
+2. 只复制上表四个 exact source files。
+3. 在副本上运行官方 `update_ini -f`，因为源 INI 的 `VERSION = 1.0` 会触发 LinuxCNC 的配置升级流程。
+4. 保持 LinuxCNC 源程序目录 `/home/mes006/linuxcncWebWASM/linuxcnc` cwd、系统 `HALLIB_DIR`、真实 `DISPLAY`。
+5. 先退出旧 LinuxCNC 服务（`linuxcncsvr`、`rtapi_app`、`milltask`、`halui`、`axis`）并确认 `/tmp/linuxcnc.lock` 不再被活动服务持有；然后在 `/home/mes006/linuxcncWebWASM/linuxcnc` 源程序目录执行 `linuxcnc <case_dir>/3axis-tutorial.ini`。
+6. 轮询 X11 window tree；只有 WM class `axis / Axis`、标题含 `3axis-tutorial`、几何至少 `600x400` 才算成功。
+7. 记录 update hash、source hash、生成文件、native log hash 和启动诊断。
+
+已验证结果：AXIS `2.10.0~pre1` 窗口 `1300x1293`，标题 `AXIS ... on 3axis-tutorial`，LinuxCNC task 正常运行，生成 parameter/position 文件。
+
+## 3. Web/WASM 对标流程
+
+Web loader 固定入口为同一 `3axis-tutorial.ini`：
+
+1. 解析 exact INI 和 `3axis-tutorial.hal`。
+2. 获取 `tool.tbl`、共享 intro graphic 和 Vismach Python executable。
+3. 对缺失 `3axis-tutorial_mm.var` 生成空 parameter workspace file，并记录 `data_hash`。
+4. 将案例 `loadusr -W ./3axis-tutorial` 识别为唯一的 `WEB-EQUIV` Vismach adapter；任意其它 `loadusr` 仍 blocked。
+5. 用同一 `trivkins`、3 joints、X/Y/Z 配置启动 Worker。
+6. Three.js 使用 Worker 的 joints/pose/toolpath snapshot，不直接运行宿主 Python GUI。
+
+## 4. 功能对标任务
+
+| ID | 任务 | 完成条件 |
+|---|---|---|
+| `TUTORIAL-00` | 锁定案例和 native runner | native AXIS 可见窗口 verified；exact source/update/generated hashes 有报告 |
+| `TUTORIAL-01` | exact resource/INI graph | INI、HAL、tool、var、intro、Vismach executable 路径和 source line 全部可追踪 |
+| `TUTORIAL-02` | HAL/Vismach adapter | `3axis-tutorial.hal` 的 loadrt/addf/net/loadusr 通过 Web 等价 adapter；非该程序的宿主 loader 仍 blocked |
+| `TUTORIAL-03` | Task startup | Worker 阶段映射到 `TASK_READY`；startup hash 与资源 hash 稳定 |
+| `TUTORIAL-04` | 三轴 motion | home、X/Y/Z jog、速度/加速度、limit、following error、trivkins pose/joint 一致 |
+| `TUTORIAL-05` | RS-274/MDI | mm units、G90/G91、G0/G1、feed、M2、MDI、pause/resume/step/abort/restart 一致 |
+| `TUTORIAL-06` | Tool/IO | `tool.tbl`、prepare/change、source `hal_manualtoolchange.change_button` ACK、spindle/at-speed、冷却、probe、estop/recover 一致 |
+| `TUTORIAL-07` | Vismach model | Python model 的 jointX/Y/Z、toollength、tooldiameter pin 语义映射到 Three.js，姿态不跳变 |
+| `TUTORIAL-08` | AXIS UI | 菜单、DRO、Manual/MDI、G-code、Preview、jog/home、tool/spindle/coolant/estop、错误和快捷键对标 |
+| `TUTORIAL-09` | persistence/recovery | var/tool/position workspace commit、checkpoint、journal、replay、重启恢复无重复副作用 |
+| `TUTORIAL-10` | integrated acceptance | native panel、Worker state、Three.js canvas、DOM controls、operation/event/checkpoint hashes 同一操作序列通过 |
+
+每项必须有专项测试、正常/边界/错误样本、source/data hash 和 self-hashed report。不能用 `timeout`、后台 `task:` 或静态 catalog READY 代替真实结果。
+
+## 5. 统一对标操作序列
+
+1. native/Web 启动并确认 AXIS panel / Worker `TASK_READY`。
+2. 按源 AXIS 语义依次执行 Z、X、Y individual home，记录 X/Y/Z pose、joint 和 homed 状态。
+3. 分别 jog X/Y/Z，记录 position/velocity/limit。
+4. 加载并运行 `G21 G90`、`G0 X0 Y0 Z0`、`G1 X10 Y5 F120`、`G1 Z-1`、`M2`。
+5. 执行 MDI、pause、resume、step、abort、restart。
+6. prepare/change tool 1，启停主轴，等待 at-speed，切换 coolant。
+7. 注入 limit、following error、probe 和 ESTOP，检查错误码、禁用控件和 recover。
+8. checkpoint 后继续一个 tick，再恢复并比较 endpoint/event/state hash。
+9. 退出并重启，比较 var/position/tool workspace state。
+
+## 6. 明确边界
+
+- `3axis-tutorial` Python 模型在 Web 中是源码驱动的 `WEB-EQUIV` Three.js adapter，不运行宿主 Python 进程。
+- POSIX fallback 只说明 native 仿真可以运行，不是实时内核或硬件验证。
+- AXIS native window 是启动成功必要条件；完整对标仍需功能、流程、界面三层分别通过。
+- 其它案例、浏览器矩阵、OPFS 物理崩溃、官方 oracle 和 release acceptance 不在本案例任务范围内。
--- a/docs/linuxcnc-web-wasm-3axis-tutorial-state-machine.md
+++ b/docs/linuxcnc-web-wasm-3axis-tutorial-state-machine.md
@@ -0,0 +1,77 @@
+# 3axis Tutorial 状态机契约
+
+本契约以 LinuxCNC `axis.py`、`linuxcnc` Python API 和 `emctaskmain/taskclass` 的源语义为 oracle。`sim_task.v1` 保持原有 schema；`axis_state` 是 Worker 响应中的附加 AXIS 视图。
+
+## 源常量
+
+| LinuxCNC 源常量 | 数值 | AXIS 视图 |
+|---|---:|---|
+| `STATE_ESTOP` | 1 | `machine_state=ESTOP` |
+| `STATE_ESTOP_RESET` | 2 | `machine_state=ESTOP_RESET` |
+| `STATE_OFF` | 3 | `machine_state=OFF` |
+| `STATE_ON` | 4 | `machine_state=ON` |
+| `MODE_MANUAL` | 1 | `source_mode=MANUAL` |
+| `MODE_AUTO` | 2 | `source_mode=AUTO` |
+| `MODE_MDI` | 3 | `source_mode=MDI` |
+| `INTERP_IDLE` | 1 | `operation_state=IDLE` |
+| `INTERP_READING` | 2 | `operation_state=RUNNING` |
+| `INTERP_PAUSED` | 3 | `operation_state=PAUSED` |
+| `INTERP_WAITING` | 4 | `operation_state=RUNNING`，`source_interp_state=INTERP_WAITING` |
+
+## 八个 AXIS 核心状态
+
+```text
+ESTOP, ESTOP_RESET, OFF, ON, HOME, IDLE, RUNNING, PAUSED
+```
+
+`ESTOP/ESTOP_RESET/OFF/ON` 是 machine/task 层；`HOME` 是 home command 的 transient operation；`IDLE/RUNNING/PAUSED` 是 interpreter/task activity 层。响应字段：
+
+```json
+{
+  "axis_state": {
+    "state": "RUNNING",
+    "machine_state": "ON",
+    "operation_state": "RUNNING",
+    "source_task_state": "STATE_ON",
+    "source_interp_state": "INTERP_READING",
+    "source_mode": "AUTO"
+  }
+}
+```
+
+## 源对齐迁移
+
+| 当前 | 允许迁移 | 触发源行为 |
+|---|---|---|
+| `ESTOP` | `ESTOP_RESET`、`ESTOP` | AXIS `estop_clicked`: `command.state(STATE_ESTOP_RESET)` 或保持急停 |
+| `ESTOP_RESET` | `ON`、`OFF`、`ESTOP` | AXIS `onoff_clicked`: `STATE_ON`；再次急停回 `ESTOP` |
+| `OFF` | `ESTOP_RESET`、`ESTOP`、`OFF` | 上电必须先经过源定义的 reset 流程 |
+| `ON` | `HOME`、`IDLE`、`RUNNING`、`PAUSED`、`OFF`、`ESTOP` | `manual_ok`、home、auto/mdi、off/estop |
+| `HOME` | `ON`、`IDLE`、`ESTOP` | `axis.py::go_home`；本案例按 `Z -> X -> Y` individual home |
+| `IDLE` | `HOME`、`RUNNING`、`PAUSED`、`OFF`、`ESTOP` | `manual_ok`、program run/pause、power/estop |
+| `RUNNING` | `PAUSED`、`IDLE`、`ESTOP` | `INTERP_READING/WAITING`、pause/abort/complete/estop |
+| `PAUSED` | `RUNNING`、`IDLE`、`ESTOP` | `INTERP_PAUSED`、resume/abort/estop |
+
+`RUNNING -> HOME`、`PAUSED -> HOME`、`ESTOP -> HOME` 等迁移必须拒绝。Home 不是普通程序运行状态，必须先满足源 `manual_ok`：task `STATE_ON` 且不在 `MODE_AUTO/MDI` 非 idle 执行中。
+
+## 按钮门控
+
+- 急停按钮始终可用；`ESTOP` 时触发 reset，其他机器状态触发 estop。
+- 上电按钮只有源状态允许时可用；`ESTOP_RESET` 才发送 `STATE_ON`，否则发送 `STATE_OFF`。
+- Open/Load/MDI/Jog/Home 需要 `STATE_ON`，且 interpreter idle 或符合 MDI queue 条件。
+- Run 需要 `STATE_ON + MODE_AUTO + INTERP_IDLE + task file`。
+- Pause 只允许 `MODE_AUTO` 且 `INTERP_READING/INTERP_WAITING`。
+- Resume 只允许 `INTERP_PAUSED`。
+- Step 需要 machine on 和 task file，不能在 ESTOP/OFF 执行。
+- Home 需要 machine on、manual mode、interpreter idle；本案例 UI 逐轴执行。
+- Tool/spindle/coolant/probe 操作必须同时受 ESTOP、fault、interlock、spindle busy 和 tool lifecycle gate 约束。
+
+## 验证
+
+- 单元状态契约：`node web/worker/test_axis_state.mjs`
+- 源序列：`node web/worker/test_axis3_tutorial_sequence.mjs`
+- native recorder：`python3 scripts/run_axis3_tutorial_native_sequence.py`
+- native/Worker sequence report：`coverage/axis3-tutorial-sequence.report.json`
+- 现有 gate contract：`web/app/test_axis_contract.mjs`、`web/app/test_axis_operation_controller.mjs`
+
+禁止修改锁定 ABI、protocol、`sim_task.v1` 字段来承载这组视图；状态契约新增字段只能作为 additive `axis_state`，并必须有 hash/迁移测试。
--- a/docs/linuxcnc-web-wasm-autonomous-execution-prompt.md
+++ b/docs/linuxcnc-web-wasm-autonomous-execution-prompt.md
@@ -20,7 +20,7 @@
 9. 任务完成后生成自哈希报告，更新 `nextTask1.md` 和 `docs/task-history.md`，将下一个依赖满足的任务写入 `Next`，然后在同一轮立即把该任务认领为 `in_progress` 并继续执行；不得在 `verified + queued` 状态结束本轮。
 10. 保留工作区已有改动，不使用 `git reset --hard`、`git checkout --` 或其他破坏性回退命令。
 11. 远程 compact、网络断开或会话恢复后，重新读取 `nextTask1.md` 和已有报告，从最近的 `in_progress` 任务继续，不从头重做。
-12. 只有 `nextTask1.md` 明确 `next_task: none`，或当前任务进入 `blocked` 且需要用户提供外部源码、权限、owner 决策或新 context 时才暂停；外部阻塞要保留证据并说明原因。
+12. 只有 `nextTask1.md` 明确 `next_task: none` 且 `local_continuation.status` 已为 `verified`，或当前任务进入 `blocked` 且没有可执行的本地 continuation、确实需要用户提供外部源码、权限、owner 决策或新 context 时才暂停；只要本地证据漂移，就继续生成/修复/验证并保留失败样本。外部阻塞要保留证据并说明原因。

 工作期间每隔约 30 秒发送简短进度更新。最终汇报实际完成项、测试结果、未闭合阻塞和下一个任务，不把模块测试通过说成全功能完成。

--- a/docs/linuxcnc-web-wasm-axis-3axis-complete-parity.md
+++ b/docs/linuxcnc-web-wasm-axis-3axis-complete-parity.md
@@ -0,0 +1,155 @@
+# 三轴 AXIS 案例完整对标规格
+
+**文档状态**：Historical draft; superseded by `linuxcnc-web-wasm-3axis-tutorial-parity.md`
+**选定案例**：`linuxcnc/configs/sim/axis/axis.ini`
+**机床类型**：3 轴笛卡尔仿真机，`trivkins`，`X Y Z`，3 joints
+**LinuxCNC 源版本**：`linuxcnc/VERSION` 中的锁定版本
+**Context**：`linuxcnc-2.10.0-pre0-wasm-m1-py-c1`
+**执行入口**：`nextTask1.md`
+
+本规格把“完全对标”定义为同一个案例的三层可观察等价：
+
+1. **功能等价**：运动、解释器、HAL、IO、工具、主轴、冷却、回零、限位、急停、MDI、程序控制和恢复的结果、错误和边界一致。
+2. **流程等价**：从选择 INI 到配置解析、资源装载、HAL/Task/IO 启动、显示启动、运行、停止和清理的阶段、顺序、诊断和状态迁移一致。
+3. **界面等价**：AXIS 面板中的可见控件、标签、状态、快捷操作、禁用条件、错误显示和 3D/轨迹反馈均有 Web 对应物，并驱动同一 Worker 权威状态。
+
+Web 使用 React、Dedicated Worker、WASM、WorkspaceRuntime 和 Three.js；不要求复制 GTK/Tk 的进程或窗口实现，但不允许删减用户可观察的 AXIS 功能、流程或状态。
+
+## 1. 证据边界
+
+### 1.1 入口与 exact resources
+
+| 类型 | exact path |
+|---|---|
+| INI | `linuxcnc/configs/sim/axis/axis.ini` |
+| parameter file | `linuxcnc/configs/sim/axis/sim.var` |
+| tool table | `linuxcnc/configs/sim/axis/sim.tbl` |
+| local HAL | `linuxcnc/configs/sim/axis/cooling.hal` |
+| shared intro | `linuxcnc/linuxcnc.gif` |
+| HALLIB HAL | `linuxcnc/lib/hallib/core_sim.hal`、`sim_spindle_encoder.hal`、`axis_manualtoolchange.hal`、`simulated_home.hal`、`check_xyz_constraints.hal` |
+
+`axis.ini` 的 `HALFILE` 顺序、`TOOL_TABLE`、`PARAMETER_FILE`、`INTRO_GRAPHIC` 和 `[TRAJ]/[KINS]/[AXIS_*]/[JOINT_*]` 值必须按源文件逐行记录 source hash、line 和 data hash。不得用其它案例的同 basename 文件替代缺失资源。
+
+### 1.2 正确 native runner
+
+native 验证必须：
+
+- 只把上表中案例声明的文件复制到隔离、可写的案例目录；不复制整个 `configs/sim/axis` 目录。
+- cwd 保持仓库根，使用系统 `HALLIB_DIR` 解析 `LIB:` HAL。
+- 使用真实 `DISPLAY` 执行 `linuxcnc -r <case_dir>/axis.ini`；`-k` 只能用于保留 HAL 错误诊断，不得把它当作无错误成功。
+- 成功条件必须包含可见 AXIS 窗口：WM title 类似 `AXIS <version> on LinuxCNC-HAL-SIM-AXIS`、WM class 为 `axis / Axis`，几何尺寸至少 `600x400`。
+- `timeout`、`Starting LinuxCNC`、`task:` 或后台进程存活都不能单独算成功。
+
+native runner 需要记录：命令、cwd、DISPLAY、LinuxCNC 版本、窗口 title/class/geometry、启动阶段、stdout/stderr hash、生成的 `.var/.bak/position.txt` 和首个错误。
+
+## 2. 功能对标矩阵
+
+| 功能域 | LinuxCNC 源程序 | Web/WASM 对应 | 完成证据 |
+|---|---|---|---|
+| INI/include/资源 | `scripts/linuxcnc.in`、`src/libnml/inifile/**`、`src/emc/ini/**` | `ini-parser.mjs`、`resource-resolver.mjs`、`sim-case-loader.mjs` | exact graph、source line、resource hash、missing/optional 诊断 |
+| 启动状态 | `scripts/linuxcnc.in` 2.x/4.x 阶段、`emctaskmain.cc`、`taskclass.cc` | `configuration-startup.mjs`、`SimSession` | `NEW→MOUNTED→PARSED→RESOLVED→CORE_CREATED→HAL_READY→TASK_READY` 与 native 阶段映射 |
+| Task/模式 | `emctaskmain.cc`、`taskclass.cc`、`emccanon.cc` | `sim_task`、`task-state.mjs`、`sim-session.mjs` | MANUAL/MDI/AUTO、READY/RUNNING/PAUSED/STOPPED/ESTOP/FAULT、状态 hash |
+| RS-274 | `src/emc/rs274ngc/interp_*.cc`、`rs274ngc_pre.cc` | WASM interpreter、`program-runtime.mjs` | G0/G1、G20/G21、G90/G91、feed、M2、参数、错误行和 modal hash |
+| TP/motion | `src/emc/tp/**`、`src/emc/motion/{motion,control,homing}.c` | `sim_motion`、固定 tick scheduler、WASM core | 1x/fast tick、位置/速度/加速度、following error、limit、checkpoint parity |
+| trivkins | `src/emc/kinematics/trivkins.c`、`kins_util.c` | `sim_kinematics` trivkins module | XYZ pose↔joint identity、3 joint mapping、flags、边界和 source hash |
+| HAL | `src/hal/hal_lib.c`、`src/hal/utils/halcmd*`、`.comp` manifest | `hal-configuration.mjs`、`hal-runtime.mjs` | 6 HAL files、threads/functions/pins/signals、load order、unsupported command diagnostics |
+| 模拟主轴 | `lib/hallib/core_sim.hal`、`sim_spindle_encoder.hal`、`src/hal/components/sim_spindle.comp` | `DeviceIoRuntime`、spindle model | command RPM、mass/limit/at-speed、encoder/index、固定 tick hash |
+| 回零/限位 | `lib/hallib/simulated_home.hal`、`motion/homing.c` | virtual home switches、`sim_motion.home` | X/Y/Z home sequence、shared switches、home result、limit error |
+| 工具/换刀 | `src/emc/tooldata/**`、`src/emc/iotask/ioControl.cc`、`axis_manualtoolchange.hal` | tool table parser、virtual tool IO | `sim.tbl` entries、prepare/change/prepared/changed/abort/fault、pocket/tool state |
+| 冷却/IO | `cooling.hal`、`ioControl.cc`、virtual IO source | `DeviceIoRuntime.coolantCommand` | mist/flood/lube request、pin absence/error、interlock/estop behavior |
+| 探针/故障 | `src/hal/components/sphereprobe.comp`、motion limits、IO errors | virtual probe/limit/fault paths | probe pose latch、nonfinite/limit/estop/fault/recover |
+| 参数文件 | `rs274ngc_pre.cc::restore_parameters/save_parameters` | workspace runtime-generated `.var` and OPFS commit | missing/empty/startup/exit-save semantics、exact path/data hash |
+| 清理/恢复 | `linuxcnc.in::Cleanup`、task/interpreter exit | checkpoint、journal、replay、WorkspaceRuntime | stop/abort/estop/recover、event cursor、endpoint hash equality、无重复副作用 |
+
+功能任务不得只验证“命令返回 verified”；必须比较最终 pose/joints、task/program/tool/device/HAL 状态和 state hash，并保留错误路径。
+
+## 3. 流程对标矩阵
+
+### 3.1 native 流程
+
+1. 解析 `axis.ini`，展开 `#INCLUDE`，检查版本和 config。
+2. 读取 `PARAMETER_FILE`、EMCMOT、EMCIO、TASK、DISPLAY、NML 和 TRAJ/KINS。
+3. `cd INI_DIR`，解析 `INTRO_GRAPHIC`，启动 AXIS splash。
+4. 启动 `linuxcncsvr`、RTAPI/HAL、IO、HALUI。
+5. 按 `[HAL]HALFILE` 顺序加载 `core_sim.hal`、`sim_spindle_encoder.hal`、`axis_manualtoolchange.hal`、`simulated_home.hal`、`check_xyz_constraints.hal`、`cooling.hal`。
+6. 启动 `milltask`，执行 HALCMD，最后启动 AXIS 面板。
+7. 用户执行 home/jog/MDI/program/tool/spindle/coolant/probe/estop/recover。
+8. 关闭 AXIS 后执行 Cleanup、保存参数、停止 HAL/RTAPI、删除 NML/锁文件。
+
+### 3.2 Web 流程
+
+1. exact-path loader 建立 bundle，补齐运行时生成资源并记录 hash。
+2. WorkspaceRuntime 挂载，INI/include/resource graph 解析完成后才允许 startup。
+3. WASM core 创建并加载 workspace；HAL preflight 依照 native 文件顺序执行。
+4. Dedicated Worker attach Task，发布 `CAPABILITIES`/`SESSION_READY`。
+5. `LOAD_WORKSPACE` 进入 `TASK_READY`，React AppShell 绑定 snapshot/event。
+6. 所有用户操作经 `command-envelope.v1` 进入 Worker；固定 tick 更新 interpreter→TP→IK→motion→HAL→IO→publish。
+7. checkpoint/journal/replay 代替 native 退出时文件/进程清理；提交 `.var/.tbl` 变更必须可恢复。
+
+两条流程必须有阶段映射表、seq/tick 对账、首个 divergence、source line 和 hash；不能用流程末尾的 READY 结果掩盖中途阶段差异。
+
+## 4. AXIS 界面对标矩阵
+
+### 4.1 必须覆盖的可见区域
+
+| AXIS 区域 | Web 对应 | 必须验证 |
+|---|---|---|
+| File/Machine/View/Help 菜单 | AppShell command/navigation menus | 菜单项、禁用条件、错误提示、快捷键语义 |
+| DRO X/Y/Z、machine/relative/commanded/actual | authoritative snapshot panel | 三轴数值、单位、位置反馈模式、tick 更新和 hash |
+| Manual/F3、MDI/F5、Auto tabs | Radix/Web tabs | tab order、aria-controls、模式切换、运行中禁用规则 |
+| G-code editor/program list | Web editor/project workflow | load/edit/reload/run/line seek、当前行、错误行 |
+| Preview/Gremlin plot | Three.js machine view | nonblank canvas、轨迹、坐标系、刀具/机床 pose 与 Worker 一致 |
+| Jog controls/increments | manual control panel | X/Y/Z jog、continuous/incremental、速度、stop、home |
+| Home Axis/Unhome/limits | axis controls | 每轴 home sequence、limit override、blocked reason |
+| Feed/spindle overrides | sliders/step controls | range、实时反映、非有限/超限拒绝 |
+| Spindle/coolant | device panel | RPM/direction/at-speed、mist/flood/lube、故障和 interlock |
+| Tool table/tool touch off | tool panel | tool/pocket/offset、prepare/change、probe/touch-off、错误可见 |
+| ESTOP/OFF/ON/Recover | safety controls | ESTOP latch、动作禁用、recover 后状态和 event cursor |
+| status/error/operator messages | state/error panel | native message key/source line/code、可追踪 hash |
+| keyboard shortcuts | Web keyboard command map | F3/F5、jog、run/pause/abort、焦点和重复触发规则 |
+
+### 4.2 界面完成条件
+
+- DOM controls、labels、ARIA tab/tabpanel 关系和 keyboard map 全部通过。
+- 每个控件都绑定一个 Worker command 或明确的 `HOST_EXCLUDED/REAL-EXCLUDED` 诊断；不得存在“看得见但无效”的装饰控件。
+- 控件 enable/disable 条件来自同一 Task/IO authoritative snapshot；不能由 React 本地猜测状态。
+- 桌面与移动 viewport 均验证布局不重叠；Three.js canvas 必须有非空像素和可变 pose。
+- AXIS 与 Web 对同一操作序列输出相同的可观察状态字段、错误键和 checkpoint endpoint hash；UI 像素差异必须单独记录，不能掩盖行为差异。
+
+## 5. 任务分解
+
+| ID | 任务 | 主要输入 | 主要输出/验收 | 依赖 |
+|---|---|---|---|---|
+| `AXIS3-00` | 锁定案例和 native runner | `axis.ini`、exact resources、`scripts/linuxcnc.in` | 可见 AXIS 窗口证据、窗口 geometry、source/resource hashes、native log | 无 |
+| `AXIS3-01` | 完整 source/resource graph | INI、HAL、tool/var、HALLIB、`inifile`/`resource-resolver` 源 | 0 unresolved exact resources；include/HAL 顺序、optional/shared asset 和 runtime file policy | AXIS3-00 |
+| `AXIS3-02` | native/Web startup phase parity | `linuxcnc.in`、`taskclass.cc`、`ioControl.cc`、`configuration-startup.mjs` | 阶段映射、首个 divergence、每阶段 hash；两端 `TASK_READY` | AXIS3-01 |
+| `AXIS3-03` | 3-axis trivkins/motion parity | `trivkins.c`、motion/homing/TP 源、axis/joint INI | home、jog、limit、following error、1x/fast endpoint parity | AXIS3-02 |
+| `AXIS3-04` | RS-274/program/MDI parity | `rs274ngc/interp_*`、G-code tests、`program-runtime.mjs` | modal/units/G0/G1/M2、MDI、pause/resume/abort/restart、line diagnostics | AXIS3-03 |
+| `AXIS3-05` | HAL/IO/tool/spindle/coolant parity | 6 HAL files、tooldata/ioControl、sim components | HAL records、spindle encoder/at-speed、tool lifecycle、coolant/IO/probe/fault matrix | AXIS3-02, AXIS3-03 |
+| `AXIS3-06` | workspace/parameter/tool persistence parity | `restore_parameters/save_parameters`、tooldata writer、WorkspaceRuntime/OPFS | startup empty/missing semantics、exit commit、journal/checkpoint/replay、no duplicate side effects | AXIS3-04, AXIS3-05 |
+| `AXIS3-07` | AXIS shell and navigation parity | `axis.py`、AXIS Tcl/Python UI source、React AppShell | menus, tabs, labels, shortcuts, focus, accessibility and enable gates | AXIS3-02 |
+| `AXIS3-08` | controls and machine-view parity | AXIS controls/Gremlin/graphics、Three.js panels | DRO, jog/home, overrides, tool/spindle/coolant/estop panels, nonblank 3D/plot and mobile layout | AXIS3-03, AXIS3-05, AXIS3-07 |
+| `AXIS3-09` | integrated native/WASM/Worker/UI acceptance | all previous reports, browser visual/performance/recovery evidence | one deterministic operation script; native window + Worker endpoint + UI DOM/canvas + recovery hash; explicit blockers | AXIS3-00..08 |
+
+每个任务必须新增或更新一个专项测试和自哈希报告；状态只能是 `queued → in_progress → verified` 或 `in_progress → blocked`。`verified` 只表示该层和依赖层通过，不代表 LinuxCNC 全功能 release。
+
+## 6. 统一验收操作序列
+
+对 native AXIS 和 Web Worker 使用同一逻辑操作序列（时间由逻辑 tick 表示）：
+
+1. 启动案例并确认 AXIS panel/Worker `TASK_READY`。
+2. 三轴全 home，记录每轴 home 状态和位置。
+3. X/Y/Z 增量 jog，记录 commanded/actual/relative DRO、速度和 endpoint hash。
+4. 切换 Manual→MDI，执行 `G21 G90`、`G0 X0 Y0 Z0`、`G1 X10 Y5 F120`、`M2`，比较 modal、轨迹和当前行。
+5. Auto 运行同一程序，执行 pause/resume/step/abort/restart，比较 task/program 状态。
+6. 设置 spindle RPM/direction、等待 at-speed、切换 mist/flood/lube，执行 tool prepare/change/abort。
+7. 注入 limit、following error、probe、coolant/IO fault 和 ESTOP，比较错误键、禁用控件、recover 结果。
+8. 创建 checkpoint，继续一步，再恢复；比较连续和恢复 endpoint/event/state hash。
+9. 退出/重启，确认参数/工具 workspace commit、journal cursor 和面板初始状态一致。
+
+## 7. 不得伪装成完整对标的边界
+
+- native 安装包与锁定源码版本不一致时，必须记录版本差异；不能把安装包行为当作官方 source oracle。
+- 实时内核、RTAPI 真实调度、PCI/串口/真实硬件和宿主动态 loader 保留 `REAL-EXCLUDED` 或 `HOST_EXCLUDED`。
+- Firefox/Safari minimum matrix、OPFS 物理崩溃恢复和官方 LinuxCNC 全状态 oracle 未完成前，整体验收保持 `blocked/STOP_RELEASE`。
+- AXIS 面板可见是 native 启动必要证据，但不等于功能、流程和 Web UI 三层都已对齐；三层报告必须同时 verified。
--- a/docs/linuxcnc-web-wasm-case-parity-plan.md
+++ b/docs/linuxcnc-web-wasm-case-parity-plan.md
@@ -1,9 +1,15 @@
 # LinuxCNC Simulation Case Parity Plan

-This plan is the execution queue for making the real cases under
-`linuxcnc/configs/sim` behave like LinuxCNC in the browser. It supplements the
-implementation roadmap with case-level acceptance rules and keeps source
-resource blockers explicit.
+This plan is the execution queue for making one exact source case behave like
+LinuxCNC in the browser. It supplements the implementation roadmap with
+case-level acceptance rules and keeps source resource blockers explicit.
+
+The only active target is specified in
+[`linuxcnc-web-wasm-3axis-tutorial-parity.md`](linuxcnc-web-wasm-3axis-tutorial-parity.md).
+Its `TUTORIAL-00..10` tasks are the required functional, process, Vismach and AXIS UI
+parity slice for `linuxcnc/configs/sim/axis/vismach/3axis-tutorial`.
+No later task may switch to another case; a new case requires a separate approved
+plan and must not change this continuation scope.

 ## Baseline

--- a/docs/task-history.md
+++ b/docs/task-history.md
@@ -108,7 +108,18 @@
 | `S8-07` | verified：从真实 INI/include declarations 生成 235-case display family catalog；Axis 85、QtVCP 61、Gscreen 14、VisMach 21、GladeVCP 6、Touchy 6、PyVCP 5、other 37；AppShell 按案例显示 family capabilities/host plugin boundaries，未改变 Worker 权威状态或 blocked 语义 | `coverage/sim-display-families-s8-07.report.json`, `web/app/sim-display-families.mjs`, `web/app/display-family.mjs`, `web/app/test_display_family_s8_07.mjs`, `scripts/generate_sim_display_families_s8_07.py`, `scripts/test_sim_display_families_s8_07.py` |
 | `S8-08` | verified：ldelta/rdelta 真实案例通过 HALLIB exact resolution、sim.var/sim.tbl fixtures、lineardelta/rotarydelta virtual adapters；nominal joints `[300,300,300]`/`[10,10,10]`、1x/fast/recovery parity 和 TASK_READY 通过，official oracle 与其它机床族边界保留 | `coverage/machine-families-s8-08.report.json`, `web/worker/test_machine_families_s8_08.mjs`, `scripts/generate_machine_families_s8_08.py`, `scripts/test_machine_families_s8_08.py` |
 | `S8-09` | verified：10 个真实 Worker runtime extension runners 全部通过，覆盖 remap/O-word/filter、Python callbacks、tool/probe/IO ack、virtual devices 和 PLC；固定 tick、能力拒绝和 recovery/ack 边界保留，host Python/dynamic loader 不被误报为浏览器 parity | `coverage/runtime-extensions-s8-09.report.json`, `scripts/generate_runtime_extensions_s8_09.py`, `scripts/test_runtime_extensions_s8_09.py` |
-| `S8-10` | blocked（正式停止条件）：新增最终 235-case acceptance 聚合；WASM/native/Worker/App 构建与回归 72/72 通过，10 个案例 TASK_READY、225 个案例保留 resource/HAL/INI/STARTUP blockers，display/machine family 与 runtime extension 证据已汇总；official full LinuxCNC oracle 仍 source-gated，Chromium/Firefox/Safari minimums 仍 TBD/Safari unavailable；implementation coverage=verified、acceptance=blocked、`STOP_RELEASE`，不宣称 LinuxCNC 全功能 release | `coverage/full-case-acceptance-s8-10.report.json`, `scripts/generate_full_case_acceptance_s8_10.py`, `scripts/test_full_case_acceptance_s8_10.py`, `nextTask1.md` |
+| `S8-10` | blocked（正式停止条件）：资源运行时语义修复后重新聚合 235-case acceptance；95 个案例 TASK_READY、140 个案例保留 HAL/INI/资源/STARTUP blockers，WASM/native/Worker/App 技术回归通过；official full LinuxCNC oracle 仍 source-gated，Chromium/Firefox/Safari minimums 仍 TBD/Safari unavailable，OPFS recovery 仍 blocked；implementation coverage=verified、acceptance=blocked、`STOP_RELEASE`，不宣称 LinuxCNC 全功能 release | `coverage/full-case-acceptance-s8-10.report.json`, `scripts/generate_full_case_acceptance_s8_10.py`, `scripts/test_full_case_acceptance_s8_10.py`, `nextTask1.md` |
+| `TUTORIAL-00` | verified：固定唯一案例 `linuxcnc/configs/sim/axis/vismach/3axis-tutorial`；隔离目录先运行官方 `update_ini -f`，再以真实 DISPLAY 启动 LinuxCNC；AXIS `axis/Axis` 窗口 1300x1293 可见；Web exact bundle/Worker `TASK_READY` 和功能操作序列通过，Vismach executable 作为唯一 `WEB-EQUIV` model adapter 资源加载 | `coverage/axis3-tutorial-native-run.report.json`, `scripts/run_axis3_tutorial_native.py`, `web/worker/test_axis3_selected_case.mjs`, `docs/linuxcnc-web-wasm-3axis-tutorial-parity.md` |
+| `TUTORIAL-01` | in_progress：锁定 4 个案例源文件、运行时 `.var/.bak/position_mm.txt` 生成规则、共享 intro graphic、HAL source lines 和 Vismach Python imports；下一步生成 exact resource/source graph 自哈希报告 | `docs/linuxcnc-web-wasm-3axis-tutorial-parity.md`, `linuxcnc/configs/sim/axis/vismach/3axis-tutorial`, `linuxcnc/lib/python/vismach.py`, `linuxcnc/lib/python/hal.py` |
+| `TUTORIAL-01..03` | verified：3axis tutorial exact resource graph、Vismach `loadusr ./3axis-tutorial` 唯一 `WEB-EQUIV` HAL adapter、startup phase `NEW→TASK_READY` 和 deterministic loader/startup hash 通过；运行时 `3axis-tutorial_mm.var` 在 workspace exact path 生成 | `coverage/axis3-tutorial-resource-graph.report.json`, `web/worker/test_axis3_tutorial_hal_adapter.mjs`, `web/worker/test_axis3_tutorial_startup.mjs`, `scripts/test_axis3_tutorial_resource_graph.py`, `scripts/test_axis3_tutorial_hal_adapter.py`, `scripts/test_axis3_tutorial_startup.py` |
+| `TUTORIAL-04` | verified：3axis tutorial `trivkins` X/Y/Z home、独立三轴 jog、limit 注入/清除、following error fault 和固定 tick snapshot 通过；X/Y/Z 位置变化、错误码和 snapshot hash 保留 | `web/worker/test_axis3_tutorial_motion.mjs`, `scripts/test_axis3_tutorial_motion.py` |
+| `TUTORIAL-05` | verified：固定 `3axis-tutorial` 案例的 RS-274/G-code `G21/G90/G91/G0/G1/F/M2`、程序 Run/Pause/Resume/Step/Abort/Restart 和 MDI 通过；暂停/运行态 MDI 保留 `mdi_while_program_active` 拒绝边界，abort/recover 后 MDI 成功；非法 G-code 在执行阶段保留解释器错误和最终 state hash | `coverage/axis3-tutorial-program.report.json`, `web/worker/test_axis3_tutorial_program.mjs`, `scripts/generate_axis3_tutorial_program_report.py`, `scripts/test_axis3_tutorial_program.py` |
+| `TUTORIAL-10` | verified（selected-case scope）：固定源程序目录执行 `linuxcnc <case_dir>/3axis-tutorial.ini` 前清理旧 LinuxCNC 服务和 lock；native AXIS 窗口图片、Chromium desktop/mobile 图片、exact Worker startup/HAL/motion/program/tool/IO/checkpoint/recovery 和 self-hash 总报告均已生成；Firefox/Safari、OPFS 物理崩溃和全量 release 保持独立 blocked | `coverage/axis3-tutorial-complete.report.json`, `coverage/axis3-tutorial-native-run.report.json`, `coverage/axis3-tutorial-visual/`, `web/worker/test_axis3_selected_case.mjs`, `scripts/run_axis3_tutorial_native.py` |
+| `TUTORIAL-11` | verified：固定案例 Worker 真实 WASM 通过 T1 prepare/change、主轴 600 RPM/at-speed/stop、mist/flood 冷却与 fault、probe arm/update/trip/disarm、ESTOP/recover；保留 tool state、probe position、错误码和最终 hash | `coverage/axis3-tutorial-tool-io.report.json`（`529b35a6fb84f561772b941a57d8bea3cf355969a622c01287afd5e642e0e246`）, `web/worker/test_axis3_tutorial_tool_io.mjs`, `scripts/generate_axis3_tutorial_tool_io_report.py`, `scripts/test_axis3_tutorial_tool_io.py` |
+| `TUTORIAL-12` | verified：参考 AXIS/QtVCP 源码遵循案例未定义 `HOME_SEQUENCE` 时的 individual home 语义，真实 native 按 `Z -> X -> Y` home；参考 `hal_manualtoolchange.py` 的 `change_button` pin，通过真实 HAL ACK 完成 T1 M6；native/Worker 同序列无首差，保留 source-defined semantics | `coverage/axis3-tutorial-sequence.report.json`, `coverage/axis3-tutorial-native-sequence.report.json`, `web/worker/test_axis3_tutorial_sequence.mjs`, `scripts/run_axis3_tutorial_native_sequence.py` |
+| `TUTORIAL-13` | verified：修复 program recovery replay 顺序，selected case checkpoint 后连续/recovered endpoint hash 相等；坏 checkpoint fail-closed，runtime `.var/tool.tbl/position` policy 和无重复副作用均有证据 | `coverage/axis3-tutorial-persistence.report.json`（`a2d125b06fe81ad8442c3b2b1f766e2a01e8a3160b4738ebc1cba59f565800f2`）, `web/worker/test_axis3_tutorial_persistence.mjs`, `web/worker/sim-session.mjs` |
+| `TUTORIAL-14` | verified（selected-case closure index）：所有 native/Worker/Chromium/tool-IO/persistence/sequence 证据冻结；native individual home 和 `change_button` tool ACK 已按源程序语义闭合；release action 仍为 `STOP_RELEASE`，外部浏览器/OPFS/硬件边界独立保留 | `coverage/axis3-tutorial-closure-index.report.json`, `scripts/generate_axis3_tutorial_closure_index.py`, `scripts/test_axis3_tutorial_closure_index.py` |
+| `AXIS-STATE-CONTRACT` | verified：新增 additive `axis_state` 视图，严格记录 LinuxCNC `STATE_*`/`MODE_*`/`INTERP_*` 数值、ESTOP_RESET/上电/关机/individual HOME/IDLE/RUNNING/PAUSED 迁移和 AXIS button gate；不修改 `sim_task.v1` | `docs/linuxcnc-web-wasm-3axis-tutorial-state-machine.md`, `web/worker/axis-state.mjs`, `web/worker/test_axis_state.mjs`, `web/react/src/store.ts`, `web/react/src/App.tsx` |
 | `FE-M1-REACT` | verified：按技术路线新增 React 19/TypeScript/Vite/Tailwind/Radix/Three.js 前端入口；Dedicated Worker/WASM bundle、protocol.v1 reducer、exact-path `configs/sim` loader、LinuxCNC AXIS source icons 和 Three.js r185 三轴 viewer 通过 typecheck/build/preview；OPFS 仍 Worker-owned | `coverage/react-frontend-m1.report.json`, `web/react`, `scripts/generate_react_frontend_m1.py`, `scripts/test_react_frontend_m1.py` |
 | `FE-M4-GUI-01` | verified：扫描 LinuxCNC AXIS/Gmoccapy/Touchy/Gscreen/QtVCP/PyVCP/GladeVCP/Vismach/NGCGUI/QtPlasmaC 等 GUI 源码、Python 库、sim descriptors/assets，1837 条文件记录、12 个 family、source hash/path 通过；341 条 manifest 反向归属缺口保留审计，许可证不阻塞技术移植 | `coverage/gui-source-inventory-fe-m4.report.json`, `scripts/generate_gui_source_inventory.py`, `scripts/test_gui_source_inventory.py`, `nextTask1.md` |
 | `FE-M4-GUI-02` | verified：集中 React GUI domain model，定义 12 family、23 个 protocol.v1 Worker command、panel/capability/boundary 映射；PY-WASM、SIM-DEVICE、WEB-EQUIV、REAL-EXCLUDED 和 Worker/OPFS ownership 均有 contract evidence | `coverage/react-gui-domain-fe-m4.report.json`, `web/react/src/gui-domain.ts`, `scripts/generate_react_gui_domain_report.py`, `scripts/test_react_gui_domain_report.py` |