Implement WebAssembly runtime and kinematics coverage

2026-08-21 06:04:48 +08:00
parent 5dd614c335
commit 554b72dae8
112 changed files with 47148 additions and 807 deletions
--- a/docs/linuxcnc-web-wasm-context-governance.md
+++ b/docs/linuxcnc-web-wasm-context-governance.md
@@ -5,17 +5,23 @@
 **生成器**：[`scripts/context_packet.py`](../scripts/context_packet.py)
 **测试**：[`scripts/test_context_packet.py`](../scripts/test_context_packet.py)

-本文件只解决两个问题：任务如何拆到可以持续接续的大小，以及一次任务交接究竟允许携带什么上下文。架构、功能范围、源文件关联和发布门禁分别以[技术路线](linuxcnc-web-wasm-technical-roadmap.md)、[源程序关联目录](linuxcnc-web-wasm-source-map.md)、[覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)和[执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)为准。本文件不复制这些文档的内容。
+本文件只解决两个问题：任务如何拆到可以持续接续的大小，以及一次任务交接究竟允许携带什么上下文。架构、功能范围、源文件关联和发布门禁分别以[技术路线](linuxcnc-web-wasm-technical-roadmap.md)、[完整仿真机床实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)、[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)、[源程序关联目录](linuxcnc-web-wasm-source-map.md)、[覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)和[执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)为准。本文件不复制这些文档的内容。

 ## 1. 不变量

 1. 一个任务只有一个主工作流、一个里程碑、一个可验证结果和一个回滚点。跨三个以上工作流必须拆分。
-2. 一个上下文包只有固定八段：`header`、`baseline`、`scope`、`contracts`、`evidence`、`risks`、`next`、`forbidden`。禁止追加 `history`、聊天记录或完整日志段。
+2. 一个上下文包只有固定八段：`header`、`baseline`、`scope`、`contracts`、`evidence`、`risks`、`next`、`forbidden`。禁止追加 `history`、聊天记录或完整日志段。`nextTask.md` 只是 8 KiB 以内的启动指针，历史和证据摘要必须移到按需读取的索引。
 3. 默认 profile 为 `feature`（4,096 tokens/16 KiB）；里程碑任务才使用 `milestone`（8,192 tokens/32 KiB）。`doc` 和 `contract` 只在确有需要时使用。
 4. `total_bytes` 同时限制序列化包和选中证据负载：`context_bytes = packet_bytes + selected_evidence_bytes`。`evidence_bytes` 是独立的证据总量上限，不能用文件数量替代。
 5. 证据在生成阶段筛选。可选证据被排除时必须记录稳定 `reason_code`；必需证据无法容纳时生成失败，不输出部分成功包。
 6. 交接只携带最新包、context lock 摘要、受影响 manifest ID 和可重跑命令。完整日志、golden 和差异报告只通过路径、大小和哈希引用。

+7. 模型请求必须为输出预留独立预算。`context` 输入预算、请求外固定开销（system/developer、工具 schema 和必要的当前状态摘要）、`max_output_tokens` 和模型上下文窗口分别记录；不能把完整日志追加到输入后再把输出预算设为最大值。连续执行从最新包重建请求，旧对话只保留路径/哈希，不能累加。请求失败时先缩减输入证据或拆分任务，不自动重试同一超大请求。
+
+8. 流式响应必须经过 [`scripts/model_stream.py`](../scripts/model_stream.py) 的有界 SSE 消费器。只有收到 `response.completed` 且 provider `usage` 通过校验时结果才可复用；断流、残缺 UTF-8、`response.failed`、`context_length_exceeded`、usage 缺失/不一致或 `max_output_tokens` 截断都必须写入 metadata-only checkpoint。checkpoint 只能保存 `context_id`、`packet_id`、事件/字节计数、输出哈希和恢复建议，不得保存半截模型文本；恢复必须生成新的、更小的 packet。
+
+9. `context_packet.py` 的 `token_limit`、`total_bytes`、`evidence_bytes` 和 `max_files` 覆盖值只能小于或等于 profile 默认值；扩大值必须改用新的、经过审查的 profile。没有 provider tokenizer 时，生成器和校验器按 UTF-8 字节作硬上界；调用方拿到精确令牌数后可通过 `--input-tokens` 替换保守估算，但不得放宽 profile 上限。
+
 ### 1.1 包的分层读取

 任务执行者按以下顺序读取，读到足够完成任务即停止：
@@ -137,6 +143,29 @@ next: INV-06b
 | COM-05a | 能力/限制注册表 | 全量 manifest | INV-02b、CORE-07b | contract |
 | COM-05b | 未支持能力解释 | 能力注册表 | COM-05a | doc |

+#### 3.3.1 K0-K8：运动学主线
+
+运动学任务按实现族和验收闭环拆分，完整契约、来源文件和测试矩阵见[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)。下列 ID 是最小任务目录的入口，不得把 CORE-07 作为一个不可拆分的大任务：
+
+| ID | 单一结果 | 依赖 | Profile |
+|---|---|---|---|
+| K0-INV-01 | 运动学源文件、符号、缺失测试输入审计 | INV-01..02 | milestone |
+| K0-INV-02 | `configs/sim` 运动学入口图和参数样本 | K0-INV-01 | feature |
+| K0-ORACLE-01 | native FK/IK JSONL golden schema 和样本 | K0-INV-01 | contract |
+| K1-CONTRACT-01 | pose/joint、flags、home、错误码 C ABI | K0-ORACLE-01、CORE-02 | contract |
+| K1-CONTRACT-02 | 坐标映射、extra joints、数值/迭代政策 | K1-CONTRACT-01 | feature |
+| K2-TRIV-01 | trivkins 四种类型、重复轴和 home | K1-CONTRACT-02 | feature |
+| K2-COUPLED-01 | corexy/rose/max/rotate 及 HAL 等价链 | K2-TRIV-01、RT-02a | feature |
+| K3-5AXIS-01 | 5axiskins、xyzac/xyzbc TRT | K2-COUPLED-01 | feature |
+| K3-ROBOT-01 | GenSer、SCARA、PUMA、Scorbot | K1-CONTRACT-02 | feature |
+| K4-PARALLEL-01 | Delta、RotaryDelta、Tripod | K1-CONTRACT-02 | feature |
+| K4-PARALLEL-02 | Hexapod、Pentapod 迭代正解和分支 | K4-PARALLEL-01 | feature |
+| K5-SWITCH-01 | switchkins 静态切换和 lastpose | K3、K4 | contract |
+| K5-USER-01 | userk/ugenser 构建期静态能力 | K5-SWITCH-01 | feature |
+| K6-MOTION-01 | TP→IK→motion→FK feedback | K2..K5、CORE-04/06 | milestone |
+| K7-REG-01 | 全配置、UI 姿态和浏览器故障回归 | K6、FE/COM | milestone |
+| K8-REL-01 | 运动学兼容、来源和发布闭合 | K7、REL-01 | milestone |
+
 ### 3.4 M4-M5：前端、回归和发布

 | ID | 单一结果 | 直接输入 | 依赖 | Profile |
@@ -176,7 +205,7 @@ next: INV-06b
 ### 4.1 正常交接

 1. 从 context lock 和父任务摘要生成新的 `packet_id`；只填本子任务的八段。
-2. 用候选证据的实际字节数调用生成器。生成前就排除 `E1`-`E5`，输出后只接受 `budget.packet_bytes <= byte_limit` 且 `packet_bytes + selected_evidence_bytes <= byte_limit`。
+2. 用候选证据的实际字节数调用生成器。生成前就排除 `E1`-`E6`，输出后只接受 `budget.packet_bytes <= byte_limit`、`packet_bytes + selected_evidence_bytes <= byte_limit` 且估算输入令牌不超过 profile 上限。
 3. 完成一步就更新 `evidence`、`risks`、`next`；不追加旧包全文。
 4. 提交正文只写 `Context-ID`、`Context-Packet`、子任务 ID、测试命令和证据路径。

@@ -201,7 +230,7 @@ budget.packet_bytes <= byte_limit
 budget.packet_bytes + budget.selected_evidence_bytes <= byte_limit
 selected_evidence_bytes <= evidence_byte_limit
 selected_evidence_files <= evidence_file_limit
-所有排除项都有 E1-E5 reason_code
+所有排除项都有 E1-E6 reason_code
 required 证据无法容纳时命令失败且不写输出
 ```

@@ -209,6 +238,10 @@ required 证据无法容纳时命令失败且不写输出

 ```bash
 python3 -m unittest discover -s scripts -p 'test_*.py' -v
+python3 scripts/validate_task_pointer.py
+python3 scripts/validate_model_budget.py <packet.json> --context-window <model-window> --overhead-tokens <current-request-overhead>
 ```

+流式请求还必须通过 `scripts/test_model_stream.py`：覆盖跨 chunk UTF-8、无终态断流、provider failure/context overflow、usage 校验、输出截断和 checkpoint 不包含部分文本。网络传输异常只能记录为 `stream_disconnected`，不能重试原 packet。
+
 本规范的目标不是把所有信息压进一个更大的包，而是让每个任务只携带完成当前结果所需的最小、可重建、可审计上下文。
--- a/docs/linuxcnc-web-wasm-execution-strategy.md
+++ b/docs/linuxcnc-web-wasm-execution-strategy.md
@@ -3,7 +3,7 @@
 **文档状态**：Draft v0.1
 **适用范围**：本仓库的纯 Web/WASM 仿真移植、浏览器运行时、OPFS 工程存储、覆盖矩阵和发布物
 **固定基线**：LinuxCNC `2.10.0~pre0`（以 `linuxcnc/VERSION` 和锁定的源码提交为准）
-**关联文档**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)、[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)、[功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)、[前端与 LinuxCNC 通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)、[总控执行手册](linuxcnc-web-wasm-integration-playbook.md)、[上下文治理与最小任务目录](linuxcnc-web-wasm-context-governance.md)
+**关联文档**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)、[完整仿真机床实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)、[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)、[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)、[功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)、[前端与 LinuxCNC 通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)、[总控执行手册](linuxcnc-web-wasm-integration-playbook.md)、[上下文治理与最小任务目录](linuxcnc-web-wasm-context-governance.md)

 本文件是项目执行的治理入口。技术路线回答“做什么以及采用什么架构”，覆盖矩阵回答“逐项覆盖什么以及如何验收”，本文件回答“谁在什么固定上下文中交付、如何在断网或失败后接续、什么证据才能过门禁”。三份文档必须以同一基线版本更新；若规则冲突，以本文件的交付门禁和覆盖矩阵的逐项验收要求为准。

@@ -76,6 +76,8 @@ M0 必须冻结来源扫描和规范化规则；每个来源项至少映射到

 “固定上下文”指每次任务交接和每次提交都重新装载一个固定格式、固定预算的上下文包，而不是把整个历史对话、全部日志或已完成阶段重新带入。上下文包是可丢弃的工作索引；完整源码、日志、golden 和差异报告留在仓库或 CI 产物中，只通过路径和摘要引用。

+启动顺序同样受预算约束：先只读取 `nextTask.md` 指针（不超过 8 KiB），再按当前子任务读取 `context-lock.json` 摘要和直接输入。`docs/task-history.md`、完整路线图、覆盖矩阵、`coverage/*.jsonl` 和完整 stdout/stderr 均为按需 L3 资料，不能在启动时批量加载。
+
 上下文包使用固定的八段结构，逻辑预算为 **8,192 tokens，UTF-8 序列化不超过 32 KiB**。实现上由 [`scripts/context_packet.py`](../scripts/context_packet.py) 在选择证据时执行预算；校验器不能成为第一次发现超限的地方。每段有上限，缺省内容用 `none`，不得追加自由历史段：

 | 段 | 固定内容 | 建议上限 |
@@ -91,6 +93,19 @@ M0 必须冻结来源扫描和规范化规则；每个来源项至少映射到

 包的 `packet_id` 由 `context_id`、任务 ID 和修订号组成；修订只替换对应段，不复制旧包。超过任一段上限或总预算时，必须先拆分任务、生成摘要或把内容移到可寻址产物，不能扩大上下文预算。每次交接从最新包重建，旧包只保留哈希和归档链接，因此移植从阶段 A 深入阶段 E 时，上下文大小不变。

+模型调用还必须显式保留输出空间：
+
+```text
+request_input_tokens = packet_input_tokens + fixed_overhead_tokens
+model_context_window >= request_input_tokens + max_output_tokens + safety_margin
+```
+
+请求前由 `validate_model_budget.py` 阻断超限；请求后还必须由 `validate_provider_response` 校验 provider 返回的 usage，确认 `output_tokens <= max_output_tokens`。若 `finish_reason` 为 `length`/`max_tokens`/`max_output_tokens`，只保存 metadata-only checkpoint 并从最新 packet 发起更小的新请求，不能把截断响应追加回下一轮。
+
+`fixed_overhead_tokens` 必须由调用方按当前请求重新计数，不能把上一次请求的历史累加进去。`max_output_tokens` 应按任务类型固定（文档 768、feature 1,024、contract 1,536、milestone 2,048 的默认上限），而不是使用模型的最大值；调用参数只能缩小 profile 的输入/输出预算，不能放大。`context_packet.py` 的字节、证据文件数和令牌覆盖值同样只能缩小 profile。没有 provider tokenizer 时按 UTF-8 字节作硬上界，拿到精确令牌数后可用 `--input-tokens` 替换估算。输入包达到预算 80% 或模型返回 `context_length_exceeded` 时，先移除最低优先级证据、缩短摘要或拆分子任务；不得把旧对话和失败响应再次拼回请求。
+
+流式调用必须由 [`scripts/model_stream.py`](../scripts/model_stream.py) 的有界 SSE 解码器消费。只有 `response.completed` 且 `usage.input_tokens/output_tokens/total_tokens` 一致、输出未超 `max_output_tokens` 时才标记可复用；中途断流、解码失败、`response.failed`、上下文超限或 `response.incomplete` 只生成 metadata-only checkpoint。恢复动作固定为丢弃可选证据并从新 packet 重建，禁止续接半截文本或重试同一个超大请求。
+
 #### 生成阶段的预算算法

 证据选择必须在写入输出文件前完成，按以下顺序执行：
@@ -99,9 +114,9 @@ M0 必须冻结来源扫描和规范化规则；每个来源项至少映射到
 2. 将候选证据规范化为 `path`、`bytes`、`sha256`、`kind`、`priority`、`required`，按必需、优先级、路径排序，保证选择确定性。
 3. 逐项检查：单项证据字节预算、证据总字节预算、证据文件数，以及把该项加入 `selected` 后的完整上下文剩余空间；完整上下文按 `packet_bytes + selected_evidence_bytes` 计算，不能只计算 JSON 清单。
 4. 可选项无法容纳时不写入包，记录稳定排除码；必需项无法容纳时直接失败，不生成部分成功包。
-5. 生成最终预算元数据后再次序列化校验；若审计清单本身使包超限，从最低优先级可选项回退并以 `E5=context_remaining_bytes_insufficient` 记录。若只剩必需项仍超限，失败。
+5. 生成最终预算元数据后再次序列化校验；若审计清单或令牌估算使包超限，从最低优先级可选项回退并以 `E5=context_remaining_bytes_insufficient` 或 `E6=token_budget_exceeded` 记录。若只剩必需项仍超限，失败。

-排除原因使用稳定机器码，避免长文本侵占上下文：`E1 duplicate_path`、`E2 evidence_item_bytes_exceed_budget`、`E3 evidence_file_count_exceed_budget`、`E4 evidence_bytes_exceed_budget`、`E5 context_remaining_bytes_insufficient`。输出必须包含选中证据字节数、选中/排除文件数、证据预算、总包预算、最终包字节数和排除码；CI 同时检查 `packet_bytes <= byte_limit` 和 `packet_bytes + selected_evidence_bytes <= byte_limit`，而不是先写超限包再报告错误。
+排除原因使用稳定机器码，避免长文本侵占上下文：`E1 duplicate_path`、`E2 evidence_item_bytes_exceed_budget`、`E3 evidence_file_count_exceed_budget`、`E4 evidence_bytes_exceed_budget`、`E5 context_remaining_bytes_insufficient`、`E6 token_budget_exceeded`。输出必须包含选中证据字节数、选中/排除文件数、证据预算、总包预算、最终包字节数和排除码；CI 同时检查 `packet_bytes <= byte_limit`、`packet_bytes + selected_evidence_bytes <= byte_limit` 和 token 上限，而不是先写超限包再报告错误。

 上下文包的最小机器可读形状如下；CI 应检查字段齐全、段顺序、预算、`context_id` 一致性和引用产物存在：

@@ -262,8 +277,8 @@ online_ready
 |---|---|---|---|
 | M0 基线锁定 | A | context lock、来源/测试清单、状态枚举、责任分工 | 清单可重建；缺项 CI 失败；文档链接和基线一致 |
 | M1 运行时骨架 | A | 单 Worker、固定 tick、ABI、最小 OPFS journal、Python 启动 | create/load/step/snapshot/recover ABI 测试通过；无网加载缓存样例 |
-| M2 核心行为 | B | G/M/O、TP、坐标、补偿、kinematics、原生 golden | 受影响核心 manifest 全部 `verified`；首个 divergent tick 可定位 |
-| M3 虚拟设备与持久化 | C | HAL/PLC/IO、数字孪生、事务恢复、断网接续 | 故障注入和恢复矩阵通过；配额不足不损坏已提交版本 |
+| M2 核心行为 | B | G/M/O、TP、坐标、补偿、[K0-K5 运动学主线](linuxcnc-web-wasm-kinematics-migration-plan.md)、原生 golden | 受影响核心 manifest 全部 `verified`；每个运动学族的首个 divergent tick 可定位 |
+| M3 虚拟设备与持久化 | C | HAL/PLC/IO、K6 运动集成、数字孪生、事务恢复、断网接续 | 故障注入和恢复矩阵通过；配额不足不损坏已提交版本 |
 | M4 Web 工作流 | D | 控制台、3D、VCP/配置工具、导入导出、离线 PWA | 关键 UI 工作流在浏览器矩阵通过；键盘/触摸和刷新恢复有证据 |
 | M5 发布候选 | E | 全量覆盖、兼容/许可证报告、迁移工具、离线包 | 所有可计入条目 `accepted`，排除项可识别，发布门禁全绿 |

@@ -273,7 +288,7 @@ online_ready

 ### 7.1 合并门禁

-每个变更包至少通过：文档链接和术语检查、格式/静态检查、受影响单测、manifest 完整性检查、原生/WASM 差异测试（适用时）、离线影响场景（适用时）、`context_packet.py` 生成器测试、上下文包字段/大小检查和证据包字段检查。任何新增来源、配置、组件、G/M/O 功能或 UI 工作流没有 manifest 条目时 CI 失败。上下文包超过 8,192 tokens 或 32 KiB、出现未定义段、把旧包全文嵌入新包，均直接阻止合并。生成阶段不能产生超限包；验证阶段只能复核，不能负责裁剪。
+每个变更包至少通过：文档链接和术语检查、格式/静态检查、受影响单测、manifest 完整性检查、原生/WASM 差异测试（适用时）、离线影响场景（适用时）、`context_packet.py` 生成器测试、`validate_task_pointer.py` 启动指针检查、`validate_model_budget.py` 请求预算检查、上下文包字段/大小检查和证据包字段检查。任何新增来源、配置、组件、G/M/O 功能或 UI 工作流没有 manifest 条目时 CI 失败。上下文包超过 8,192 tokens 或 32 KiB、启动指针超过 8 KiB、模型输入加输出预留超出窗口、出现未定义段、把旧包全文嵌入新包，均直接阻止合并。生成阶段不能产生超限包；验证阶段只能复核，不能负责裁剪。

 ### 7.2 里程碑门禁

--- a/docs/linuxcnc-web-wasm-full-port-implementation.md
+++ b/docs/linuxcnc-web-wasm-full-port-implementation.md
@@ -0,0 +1,258 @@
+# LinuxCNC Web/WASM 完整仿真机床实施蓝图
+
+**文档状态**：实施规范 v1.0
+**适用基线**：LinuxCNC `2.10.0~pre0`，提交由 [`context-lock.json`](../context-lock.json) 冻结
+**用途**：把“完整移植 LinuxCNC 仿真机床”分解为可实现、可回归、可恢复和可发布的工程闭环
+**运动学主线**：[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)
+**上位路线**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)
+**覆盖依据**：[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)
+**源程序依据**：[功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)
+**通信契约**：[前端与通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)
+**执行总控**：[仿真移植总控执行手册](linuxcnc-web-wasm-integration-playbook.md)
+
+本文件是实施层的补充规范。运动学实现族、正逆解契约和 K0-K8 里程碑以[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)为专项细则。它不替代来源清单、协议 schema 或覆盖矩阵；当这些文件发生冲突时，`context-lock.json`、协议 schema 和逐文件覆盖记录优先。本文件解决的是：一个 LinuxCNC 仿真入口如何启动，经过哪些运行时层，如何产生确定性结果，如何在浏览器中恢复，以及怎样证明“完整”而不是“演示可用”。
+
+## 1. 完整移植的工程定义
+
+完整移植必须同时闭合六条链。任何一条链缺失，都只能称为部分移植或演示版本：
+
+| 闭合链 | 必须回答的问题 | 发布前证据 |
+|---|---|---|
+| 来源闭合 | LinuxCNC 文档、源码、符号、配置资源和测试是否全部登记？ | `source-index`、`manifest`、依赖闭包、零孤儿报告 |
+| 构建闭合 | 可移植代码、适配层、静态组件和 Python 运行时是否可重建？ | 编译锁、构建日志、产物 SHA-256、许可证清单 |
+| 启动闭合 | 任一纳入范围的 `configs/sim` 入口能否解析并进入 `READY` 或给出可诊断错误？ | 配置资源图、启动日志、错误文件/行号 |
+| 行为闭合 | 解释器、TP、运动、HAL、IO、PLC 和 Python 的可观察结果是否与原生 oracle 一致？ | JSONL golden、首个 divergent tick 报告、容差说明 |
+| 工作流闭合 | 编辑、MDI、运行、暂停、单步、急停、jog、home、工具、报警和恢复是否能从 UI 完成？ | 浏览器 E2E、键盘/触摸、故障和恢复场景 |
+| 交付闭合 | 离线、迁移、配额、崩溃恢复、回滚、兼容性和许可证是否可审计？ | 发布清单、离线包、迁移/回滚演练、兼容报告 |
+
+“全覆盖”只统计仿真可观察能力。真实硬件、硬实时内核和安全认证属于 `REAL-EXCLUDED`；但它们在仿真配置中产生的信号必须由数字孪生提供，不能以“不支持”跳过主轴、编码器、探针、限位、换刀、冷却或 IO 的仿真行为。
+
+## 2. 当前起点和硬门禁
+
+当前仓库的实际起点如下，不能用文档中的目标状态替代代码证据：
+
+| 项目 | 当前状态 | 实施含义 |
+|---|---|---|
+| M0 来源/上下文 | 已生成，锁定 8,026 个来源条目和 context lock | 任何来源变化先重建并审查哈希 |
+| M1 ABI 骨架 | 已有生命周期、固定 tick、快照和导入导出骨架 | 只能作为 ABI 起点，不代表 LinuxCNC 核心已接入 |
+| posemath/解释器/运动切片 | 已有仓库内适配报告和原生测试证据 | 仍需接入统一 `sim_task`、HAL 和 Worker |
+| kinematics 节点 | 旧 `M2-CORE-04` blocked，当前转入 K0 来源审计 | 锁定来源缺少声明的 `linuxcnc/unit_tests/kinematics/**`，不得静默改用其他目录 |
+| Python、完整 HAL、UI、OPFS 恢复 | 尚未完成全量闭环 | 不得以 mock、刷新后重建或单一三轴页面宣称完成 |
+
+每个实施任务开始前运行基线门禁：
+
+```bash
+python3 scripts/validate_baseline.py
+python3 scripts/validate_download_index.py
+python3 -m unittest discover -s scripts -p 'test_*.py' -v
+python3 scripts/validate_task_pointer.py
+```
+
+若锁定提交、输入目录、schema 版本或生成器版本发生变化，先创建新的 `context_id`；不能在旧 context 中覆盖索引或降低校验条件。
+
+## 3. 运行时分层和依赖规则
+
+完整仿真运行时固定为单 Dedicated Worker 单写者模型。主线程只能通过版本化协议读取状态和提交命令，不能读取 WASM 指针、修改 HAL pin 或直接写 OPFS。
+
+```text
+UI / Three.js / 编辑器
+        │ protocol.v1
+Worker: CommandRouter → TaskLedger → SimScheduler
+        │                         ├─ SimTask / rs274ngc / canonical
+        │                         ├─ TP / posemath / kinematics
+        │                         ├─ SimMotion / homing / limits
+        │                         ├─ SimHAL / components / ClassicLadder
+        │                         ├─ SimIO / digital-twin devices
+        │                         └─ PythonRuntime / remap / VCP
+        ├─ SnapshotPublisher / EventBus / TraceRecorder
+        └─ WorkspaceRuntime → WasmFS/POSIX → OPFS journal/checkpoint
+```
+
+依赖必须单向流动：
+
+1. 几何、解释器和运动核心不能依赖 DOM、OPFS、Python 或 UI。
+2. HAL 组件只能通过注册的 pin/signal/parameter 接口访问运行时；组件不得调用宿主路径、网络或动态加载。
+3. Python 只能访问白名单虚拟模块、`/workspace` 和虚拟时钟；超出能力返回稳定错误码。
+4. UI 只能消费快照、事件和流；派生显示状态不得回写 authoritative state。
+5. OPFS 只承接事务和恢复，不参与每个仿真 tick 的运动计算。
+
+WASM 核心以独立 CMake/Emscripten 目标构建。LinuxCNC 原生 `meson.build` 继续用于 oracle 和原生测试，不作为 WASM 的直接构建入口。动态库、`fork/exec`、NML/CMS 进程边界和共享内存改为静态注册、进程内对象和版本化快照。
+
+## 4. 一个仿真入口的启动闭环
+
+所有 `configs/sim/**` 入口都必须经过相同的启动状态机；配置专属差异只能来自已登记能力和资源，不得在 UI 中写隐式特例。
+
+```text
+NEW
+  → WORKSPACE_MOUNTED
+  → INI_PARSED
+  → RESOURCES_RESOLVED
+  → CORE_CREATED
+  → HAL_TWOPASS_DONE
+  → DEVICES_BOUND
+  → TASK_READY
+  → RUNNING / PAUSED / ESTOP
+  → STOPPED → DESTROYED
+```
+
+启动步骤及其产物：
+
+1. `HANDSHAKE`：协商 `context_id`、ABI/protocol/snapshot 版本和能力注册表；版本不兼容直接拒绝。
+2. `MOUNT`：将工程挂载到虚拟 `/workspace`，规范化大小写、路径和编码，拒绝 `..`、绝对宿主路径和符号链接。
+3. `PARSE_INI`：解析 section、include、变量替换、轴/关节/主轴数量、周期和入口文件；错误必须包含文件、行和字段。
+4. `RESOLVE`：构建 `.hal`、`.tbl`、`.var`、`.ngc`、`.py`、`.xml/.glade/.ui`、`.clp`、`.halscope/.halshow` 等资源图，报告缺失、循环和宿主依赖。
+5. `CREATE_CORE`：按配置静态选择 kinematics、解释器、TP、motion、IO 和工具服务，记录模块版本与 source SHA。
+6. `HAL_TWOPASS`：完成 `loadrt`、组件实例、`addf`、`setp`、`net`、`sets`、`link*` 的确定性顺序；任何未注册组件阻断启动。
+7. `BIND_DEVICES`：绑定轴、编码器、主轴、探针、限位、回零、换刀、冷却和 PLC 数字孪生，并应用故障模型。
+8. `START_TASK`：加载程序、参数、工具表和 Python/remap；运行一次零周期初始化，生成初始状态哈希。
+9. `READY`：发布完整快照、能力和资源诊断。UI 只有收到 `READY` 才能开放运行按钮。
+
+任一步骤失败时，必须撤销尚未提交的资源绑定并保留结构化诊断；不能留下半初始化会话，也不能通过“忽略失败文件”进入 `READY`。
+
+## 5. 固定 tick 和状态更新顺序
+
+`sim_step(cycles)` 是唯一改变仿真结果的入口。每个逻辑周期按下列顺序执行，顺序属于协议和 golden 的一部分：
+
+1. 读取本周期已确认的命令，按 `seq` 和 `operation_id` 去重；未确认的命令不能重复产生副作用。
+2. 执行 Task/解释器预算，产生 canonical 队列、当前行、模态和错误。
+3. 运行 TP 前瞻、blend、速度/加速度/jerk 限制，生成本周期目标轨迹。
+4. 调用 kinematics `inverse`，检查奇异姿态、轴/关节限制和 NaN/Inf。
+5. 更新 motion、homing、软/硬限位、following error、急停和 jog 状态。
+6. 按静态线程清单运行 HAL function、虚拟轴/编码器/主轴/探针/换刀和 ClassicLadder scan。
+7. 处理 IO 完成、输入等待、超时、报警和 Python 回调；回调不能绕过当前 tick。
+8. 生成事件、采样和状态哈希；先发布内存快照，再按 checkpoint/journal 策略持久化。
+
+暂停只停止后续运动和解释，不丢弃已入队 canonical；急停清空或冻结哪些队列必须由状态机明确规定。快速模式、1x、单步、暂停恢复和回放在相同逻辑终点必须得到相同状态哈希；墙钟只用于节流和让出 Worker 事件循环。
+
+## 6. 各域实施契约
+
+### 6.1 配置、工作区和启动资源
+
+实现顺序为“路径规则 → 文件 API → 解析器 → 资源图 → 启动器”。至少提供 `open/read/write/stat/readdir/rename/unlink/fsync`，并保留 LinuxCNC 相对路径和 include 语义。
+
+| 输入类型 | 处理方式 | 最小验收 |
+|---|---|---|
+| `.ini/.inc` | 兼容 section、变量、include、相对路径和循环检测 | 逐文件行号诊断、重复加载结果一致 |
+| `.hal/.comp` | 解析 twopass、实例、函数顺序和 pin 类型；组件构建期静态注册 | HAL graph 与 native 对齐 |
+| `.tbl/.var` | 工具、pocket、offset、参数和 wear 的版本化服务 | 加载、编辑、提交、恢复一致 |
+| `.ngc/.nc` | 主程序、子程序、O-word、M-code 文件和过滤器 | 相同入口解析到相同程序图 |
+| `.py` | 受控 Python runtime；能力清单和资源限额 | 正常、异常、超时、禁止 API |
+| `.xml/.glade/.ui` | 转换为 Web Component descriptor；保留 pin、属性、回调 | 样例面板可加载且权限可审计 |
+| `.clp/.halscope/.halshow` | 解析 PLC、采样、触发和回放描述 | 逻辑/波形结果可回放 |
+
+资源图必须记录 `input_sha`、解析器版本、依赖、输出能力和错误。配置加载不成功时，错误报告必须能反向定位到 manifest 条目。
+
+### 6.2 解释器、Task、TP、motion 和 kinematics
+
+移植以原生 oracle 为先：先让 native runner 输出解释器状态、canonical、每 tick 运动和错误，再接入 WASM。核心边界只允许使用固定宽度类型和稳定错误码。
+
+实施顺序：
+
+1. posemath 和数值策略：固定浮点编译选项、角度/单位换算、NaN/Inf 检查。
+2. rs274ngc：词法/语法、模态、参数、O-code、循环、补偿、G/M/O 和错误位置。
+3. canonical/TP：直线、圆弧、球面弧、样条、NURBS、前瞻、blend、exact stop 和同步运动。
+4. Task/NML 兼容：命令、状态、错误、模式转换、MDI、单步、暂停、恢复、abort 和队列清空。
+5. motion：轴/关节、jog、home、软硬限位、following error、外部偏置和故障注入。
+6. kinematics：trivkins、gantry、CoreXY、5/6 轴、Delta、机器人、foam 等静态模块；每个模块提供 `forward/inverse/limits/capabilities`。
+
+`M2-CORE-04` 当前因锁定输入缺少 `unit_tests/kinematics/**` 而 blocked。处理方式只有两种：补充并重新锁定确实存在的官方测试输入，或由契约变更明确批准替代 oracle 并登记差异；不能把 `tests/matrixkins/**` 直接伪装成原声明输入。
+
+### 6.3 HAL、组件、PLC 和数字孪生
+
+HAL 运行时必须先建立类型化对象图，再执行组件。组件来源按三类登记：可移植核心、构建期 `.comp` 组件、仿真专用数字孪生。每个组件 manifest 至少包含名称、版本、输入/输出 pin、参数、线程要求、依赖、权限、测试和状态。
+
+固定调度顺序为：`base/servo`（如配置启用）→运动反馈→主轴/编码器→通用 HAL function→PLC scan→IO 完成→采样发布。缺少实时墙钟不改变这个逻辑顺序。
+
+数字孪生必须能脚本化以下状态：主轴加减速/不到速/定向失败，编码器计数和丢脉冲，探针触发/未触发，限位/回零，换刀成功/超时/失败，冷却和润滑，模拟/数字 IO 延迟、抖动和故障。故障注入本身也是可回放输入，不能通过随机数产生不可重复结果。
+
+ClassicLadder 需要覆盖工程加载、寄存器、触点/线圈、定时器、计数器、顺序控制、HAL 绑定、扫描周期、暂停/恢复和诊断 UI；真实 Modbus transport 排除，但虚拟寄存器、延迟和错误状态必须可配置。
+
+### 6.4 Python、remap、VCP 和插件
+
+Python runtime 在 Worker 内启动，固定 Pyodide 版本、包索引和 artifact hash。桥接模块只提供 `linuxcnc`、`hal`、`gstat`、INI、工具表、虚拟时间和工作区 API；`subprocess`、`socket`、宿主线程、设备文件和任意路径必须返回稳定的能力拒绝错误。
+
+remap/filter/VCP 每次调用都记录入口、参数摘要、tick、返回值、异常、耗时和资源消耗。Python 异常必须回到解释器/Task 错误语义，不能只写 console。VCP descriptor 转换为带版本和权限的 Web Component schema，插件崩溃不得破坏核心会话。
+
+### 6.5 协议、快照、事件和持久化
+
+命令必须执行 `prepare → execute → verify → commit`；`operation_id` 幂等，回答丢失时先查账本。快照至少分为配置、解释器、Task、TP、motion、kinematics、HAL、IO、Python、工作区和恢复元数据，并带 `schema_version/context_id/simulation_tick/state_hash`。
+
+OPFS 只保存已提交工程、journal、checkpoint、日志和可删除缓存。推荐恢复流程：读取最近有效 checkpoint → 校验哈希 → 按序重放已提交 journal → 对未确认操作逐项对账 → 发布 `RECOVERED` 或明确 `RECOVERY_BLOCKED`。不能以“重新加载 INI 并从头运行”替代状态恢复。
+
+## 7. 原生 oracle 和全量回归
+
+原生 runner 与 WASM runner 必须使用同一工程输入和同一命令序列。每个样本至少输出：
+
+```json
+{
+  "context_id": "...",
+  "entry_source_id": "...",
+  "test_id": "...",
+  "tick": 1234,
+  "interpreter": {"line": 12, "modal_hash": "...", "parameters_hash": "..."},
+  "canonical": [{"kind": "straight_feed", "target": [0, 0, 0]}],
+  "motion": {"axis": [], "joint": [], "following_error": []},
+  "hal": {"pins_hash": "...", "signals_hash": "..."},
+  "io": {"spindle": {}, "tool": {}, "probe": {}},
+  "events": [],
+  "state_hash": "..."
+}
+```
+
+差异报告必须给出首个 divergent tick、字段路径、原生值、WASM 值、单位、容差、来源文件和 manifest ID。浮点容差只能用于数值字段，不能掩盖状态转换、错误码、事件顺序、当前行、工具号或 HAL 拓扑差异。
+
+每个入口至少执行以下维度：正常运行、边界数值、语法/配置错误、暂停/单步/abort、急停/限位/设备故障、导出导入、Worker 重启/OPFS 恢复、离线启动；有 UI 或插件的入口再加键盘/触摸、权限和背压维度。
+
+发布前必须满足：
+
+- `source-index`、`manifest`、依赖闭包和配置资源图无孤儿，所有条目已分配 owner/feature/domain。
+- 所有可计入条目为 `accepted`；不得残留 `planned`、`needs_owner`、无 oracle 或无测试维度条目。
+- 同一输入在至少三次运行、1x/快速/单步/恢复路径下的最终 `state_hash` 一致。
+- 所有事件按 `seq/tick` 单调发布，重放不重复产生已提交副作用。
+- 配额不足、schema 不兼容、缺失资源、禁止宿主能力和恢复无法对账均有明确错误，不静默降级。
+- 浏览器矩阵、性能、内存、离线、许可证、迁移和回滚报告齐全；性能优化不能改变 golden 结果。
+
+## 8. 分阶段实施和产物
+
+| 阶段 | 实施重点 | 必须产物 | 退出条件 |
+|---|---|---|---|
+| M0 基线闭合 | 来源、符号、配置、测试、依赖和 context lock | 索引、manifest、oracle schema、影响图 | 零孤儿、哈希可重建、缺字段会失败 |
+| M1 会话闭环 | C ABI、Worker 队列、虚拟工作区、固定 tick、最小恢复 | WASM/原生 ABI 测试、协议 schema、journal/checkpoint | create/load/step/snapshot/export/import/recover 通过 |
+| M2 核心行为 | 解释器、canonical、TP、Task、motion、kinematics、工具服务 | 每个源组的适配报告、golden、差异报告 | 受影响核心条目 `verified`；blocked 输入已处理 |
+| M3 仿真系统 | HAL、`.comp`、ClassicLadder、IO、数字孪生、Python/remap | 组件 manifest、HAL graph、故障矩阵、Python 能力报告 | 配置启动和 S1-S6 场景通过 |
+| M4 Web 工作流 | 工程、编辑器、MDI、控制台、HAL/PLC、VCP、Three.js、导入导出 | 浏览器 E2E、截图/像素、性能和恢复证据 | 所有真实 Worker 工作流通过，mock 退出 |
+| M5 发布闭合 | 全量 configs/tests/unit_tests、浏览器、离线、迁移、许可证 | 兼容报告、排除项、离线包、回滚包 | G0-G5 全绿，所有计入条目 `accepted` |
+
+每个阶段都按“输入冻结 → 失败测试 → 最小实现 → native/WASM 对照 → 故障/恢复 → 文档和 manifest → 门禁”执行。阶段间不得用“先做 UI、后补核心”绕过依赖。
+
+## 9. 实施任务的最小交付包
+
+每个子任务只能有一个主要结果，并在提交中同时更新：
+
+1. 受影响 source/feature/task/test/oracle 的 ID 和 source SHA。
+2. C ABI、协议、快照或工作区 schema 的版本和兼容策略（若有变化）。
+3. 正常、边界、错误、恢复和离线测试命令及结果路径。
+4. native/WASM 差异报告、性能/内存/配额影响和已知限制。
+5. 回滚点、未完成输入、下一任务和 `nextTask.md` 指针。
+
+示例任务标题应具体到单一结果，例如：`M3-RT-03b：限位与换刀故障注入可回放`，而不是“完善仿真设备”。任务若同时修改两个独立契约，先拆成契约任务和实现任务。
+
+## 10. 停止线和风险处置
+
+- 来源或测试输入缺失：停止并记录 `blocked`，由新的契约变更决定是否补充输入；不删样本、不改目录级状态。
+- 原生/WASM 首个差异未定位：冻结受影响源组和 golden，不进入下一层集成。
+- 协议/ABI/schema 破坏性变化：新建版本、迁移和双向测试；旧版本不能静默接受。
+- Python、组件或 VCP 需要宿主能力：改为虚拟能力或明确 `REAL-EXCLUDED`，并测试拒绝路径。
+- OPFS journal/checkpoint 损坏、配额不足或确认丢失：保留最近已提交版本，进入恢复或导出，不覆盖旧数据。
+- 非确定性、随机故障或浏览器墙钟改变结果：禁止合并，固定种子、顺序、tick 和输入后重跑。
+- 性能优化导致 golden 变化：按行为回归处理，不能以“更快”豁免差异。
+
+## 11. 当前立即执行顺序
+
+1. 按 `nextTask.md` 执行 `K0-INV-01`，处理旧 `M2-CORE-04` 的 kinematics 输入阻塞，先确认锁定提交中不存在声明路径，并保留报告。
+2. 若要采用替代 oracle，先创建可审查的契约变更和新的 context lock；否则保持 blocked，不推进 HAL 节点。
+3. 在 kinematics 契约闭合后，完成静态模块注册、`forward/inverse/limits` ABI、确定性状态哈希和失败路径测试。
+4. 继续 `M2-CORE-05` 前，先让 native runner、WASM runner 和 `sim_step` 共享同一 tick/golden schema。
+5. 只有 M2 核心条目达到 `verified`，才进入 HAL/数字孪生/OPFS 恢复；只有 M3 通过，才把 mock UI 替换成真实 Worker 工作流。
+
+本文件完成的是实施规则和证据闭环，不改变当前任务指针，也不把尚未实现的 LinuxCNC 功能标为完成。
--- a/docs/linuxcnc-web-wasm-implementation-readiness.md
+++ b/docs/linuxcnc-web-wasm-implementation-readiness.md
@@ -3,20 +3,20 @@
 **状态**：M0 已落地，M1 ABI 骨架已验证，LinuxCNC 功能移植尚未完成
 **目标**：把既有技术路线收敛成可执行的实施顺序、完整性证明和发布前置条件
 **固定基线**：LinuxCNC `2.10.0~pre0`，提交 `239dcf4284762ad7e9c65d390bc5524d855c2f8e`
-**关联文档**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)、[覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)、[源程序关联](linuxcnc-web-wasm-source-map.md)、[通信设计](linuxcnc-web-wasm-frontend-communication-design.md)、[执行策略](linuxcnc-web-wasm-execution-strategy.md)、[总控手册](linuxcnc-web-wasm-integration-playbook.md)
+**关联文档**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)、[完整移植实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)、[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)、[覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)、[源程序关联](linuxcnc-web-wasm-source-map.md)、[通信设计](linuxcnc-web-wasm-frontend-communication-design.md)、[执行策略](linuxcnc-web-wasm-execution-strategy.md)、[总控手册](linuxcnc-web-wasm-integration-playbook.md)

-本文件是开始编写程序前的单页入口。专项文档保留详细契约；本文件只固定真实基线、先后顺序、完成定义和阻断条件。
+本文件是开始编写程序和恢复任务前的单页入口。完整移植实施蓝图进一步规定启动状态机、运行时依赖、tick 顺序和各域产物；专项文档保留详细契约。本文件只固定真实基线、先后顺序、完成定义和阻断条件。

 ## 1. 现状和不可误读项

-本仓库已经具备完整设计文档，但此前没有 Web/WASM 运行时代码。当前 M0/M1 产物如下：
+本仓库已经具备完整设计文档，并已落地一组可独立验证的 Web/WASM 运行时切片；LinuxCNC 全功能运行时仍未闭合。当前 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、快照、导入导出骨架 | 工程边界可编译、可调用 |
+| `coverage/source-index.jsonl` | 8,026 个来源文件，来自 docs/src/configs/tests/unit_tests/build | 来源扫描已开始，可审计 |
+| `coverage/manifest.jsonl` | 8,026 个一对一种子条目，全部 `planned/needs_owner` | 没有来源被静默漏掉；不代表已实现 |
+| `wasm-core` | C ABI 生命周期、固定 tick、快照、导入导出，以及 posemath/解释器/运动适配切片 | 工程边界可编译、可调用；不代表完整核心闭合 |
 | `build-wasm`/`build-native` | WASM 模块生成，宿主 ABI 单测通过 | 构建链路可重跑 |

 以下能力目前都不能声明完成：rs274ngc、TP、motion、kinematics、HAL、ClassicLadder、Python/remap、OPFS、Worker、UI、Three.js、全量配置和浏览器回归。
--- a/docs/linuxcnc-web-wasm-integration-playbook.md
+++ b/docs/linuxcnc-web-wasm-integration-playbook.md
@@ -4,13 +4,15 @@
 **用途**：统一功能完整性、任务执行、依赖、测试、接续和里程碑验收
 **固定基线**：LinuxCNC `2.10.0~pre0`，以 `linuxcnc/VERSION` 和 context lock 为准
 **架构路线**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)
+**完整实施蓝图**：[完整仿真机床实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)
+**运动学主线**：[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)
 **源码目录**：[功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)
 **前端/通信**：[前端与 LinuxCNC 通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)
 **覆盖验收**：[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)
 **治理规则**：[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)
 **最小任务与上下文**：[上下文治理与最小任务目录](linuxcnc-web-wasm-context-governance.md)

-本手册是五份设计文档的总控入口。它不替代各专项文档，而是规定它们如何组合、谁负责什么、任务如何进入执行、依赖如何推进、失败如何恢复以及什么证据才能声明移植完成。
+本手册是专项设计文档的总控入口。完整实施蓝图规定单个仿真入口如何启动和推进；本手册不替代这些专项文档，而是规定它们如何组合、谁负责什么、任务如何进入执行、依赖如何推进、失败如何恢复以及什么证据才能声明移植完成。

 ## 1. 当前审计结论

@@ -19,14 +21,14 @@
 ```text
 设计基线：已建立
 源码/功能清单：`coverage/source-index.jsonl` 和 `coverage/manifest.jsonl` 已生成，全部条目仍待归并
-运行时实现：`wasm-core` ABI bootstrap 已编译，LinuxCNC 核心尚未接入
+运行时实现：`wasm-core` ABI bootstrap 及部分 posemath/解释器/运动切片已编译，LinuxCNC 全量核心尚未接入
 前端实现：未开始或尚未进入当前工作区
 全功能验收：未开始，不得声明已完成
 ```

 这是当前交付边界：后续任务从 M1/WS-1 的 ABI、原生 runner、固定 tick 和工作区契约继续；M0 清单重生成和哈希校验仍是每次基线变化的前置步骤。任何演示页面、mock Worker 或单一三轴样例都不能把项目状态提前改成“全功能完成”。

-上下文治理的可执行入口是 `scripts/context_packet.py`，测试是 `scripts/test_context_packet.py`，任务拆分和分层读取以[上下文治理与最小任务目录](linuxcnc-web-wasm-context-governance.md)为准。当前仓库没有运行时实现，但上下文生成和预算测试已经可以独立运行；后续 CI 应在任何任务证据包生成前调用该脚本。
+上下文治理的可执行入口是 `scripts/context_packet.py`、`scripts/validate_task_pointer.py`、`scripts/validate_model_budget.py` 和 `scripts/model_stream.py`，测试是 `scripts/test_context_packet.py`、`scripts/test_model_stream.py` 及对应校验器单测，任务拆分和分层读取以[上下文治理与最小任务目录](linuxcnc-web-wasm-context-governance.md)为准。模型预算校验还必须传入当前请求的 `--overhead-tokens`；连续任务从最新包重建，不累加旧对话。请求前校验输入、固定开销、输出预留和安全余量，请求后用 `validate_provider_response` 校验 provider usage；流式断开、上下文超限、usage 异常和截断响应只写 metadata-only checkpoint，不拼回下一轮。当前仓库已有可独立验证的核心切片，但尚未形成完整 LinuxCNC 运行时；上下文生成、启动指针、模型请求预算和流式恢复测试已经可以独立运行；CI 应在任何任务证据包生成或模型请求前调用相应脚本。

 ## 2. 唯一追踪链

@@ -116,7 +118,7 @@ M0 / WS-0 基线、source map、manifest、context lock
 | CORE-04 | TP/posemath/几何 | `src/emc/tp/**`、posemath | canonical、轨迹和容差报告 |
 | CORE-05 | Task/NML/状态 | `src/emc/task/**`、nml_intf、libnml | message bus 和状态快照 |
 | CORE-06 | Motion/homing/limit | `src/emc/motion/**` | jog、home、limit、following error |
-| CORE-07 | Kinematics 全集 | `src/emc/kinematics/**` | 静态模块、能力注册、姿态 golden |
+| CORE-07 | Kinematics 全集 | `src/emc/kinematics/**` | 按[K0-K8 运动学主线](linuxcnc-web-wasm-kinematics-migration-plan.md)执行；静态模块、能力注册、姿态 golden |
 | CORE-08 | Tooldata/IO 基础 | `src/emc/tooldata/**`、iotask | 工具、主轴、换刀、IO 状态 |

 ### 5.3 WS-2/WS-3/WS-4 运行时集成
@@ -145,14 +147,30 @@ M0 / WS-0 基线、source map、manifest、context lock
 | REG-04 | 浏览器/性能/视觉矩阵 | FE、COM-03 | Chromium/Firefox/Safari、P95/P99、截图/像素 |
 | REL-01 | 兼容、许可证、迁移、回滚和离线包 | 全部 REG | 发布候选证据包和签名报告 |

+### 5.5 运动学主线 K0-K8
+
+运动学不再作为 CORE-07 的单个串行任务处理。K0-K8 是从来源审计到发布闭合的硬门，详细输入、算法族和测试矩阵见[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)。
+
+| 主线阶段 | 解锁范围 | 对整体项目的门禁 |
+|---|---|---|
+| K0 | 源文件、符号、配置入口、native FK/IK 样本和缺失输入 | 未闭合时不得声明任何非 trivkins 配置可运行 |
+| K1 | C ABI、pose/joint 映射、flags、数值/迭代策略 | 未闭合时 motion 只能保留 bootstrap，不得接入全量算法 |
+| K2 | trivkins 全类型、重复轴、extra joints、corexy/rose/max/rotate | 未闭合时不得验收 axis/joint 模式、HAL 耦合或恢复 |
+| K3 | 5 轴 TRT、SCARA/PUMA/Scorbot/GenSer | 未闭合时不得验收刀尖跟随、机器人和 5 轴可视化 |
+| K4 | Delta、RotaryDelta、Tripod、Hexapod、Pentapod | 未闭合时不得验收并联机构、迭代正解和 Vismach |
+| K5 | switchkins、userk/ugenser 静态扩展和能力注册 | 未闭合时不得加载切换或用户运动学配置 |
+| K6 | TP→IK→motion→FK feedback、home/limit、IO/数字孪生 | 未闭合时 M3 运动故障和恢复场景不具备发布资格 |
+| K7 | Three.js 姿态、全配置回归和浏览器故障矩阵 | 未闭合时 M4 UI 只能作为结构原型 |
+| K8 | 兼容、迁移、许可证、来源和回滚闭合 | 未闭合时 M5 不能进入发布候选 |
+
 ## 6. 里程碑总表

 | 里程碑 | 入口条件 | 必须完成 | 退出证据 | 失败动作 |
 |---|---|---|---|---|
 | M0 基线锁定 | 版本和范围确认 | INV-01..05、状态枚举、责任人 | source/manifest/context lock 可重建，零孤儿规则生效 | 返回清单阶段，不写运行时代码 |
 | M1 运行时骨架 | M0 通过 | CORE-01/02、RT-01、FS-01、COM-01/02 最小集 | create/load/command/step/snapshot/recover、离线缓存启动 | 固定 ABI/schema，修复后重跑 M1 |
-| M2 核心行为 | M1 通过 | CORE-03..08、native/WASM runner、解释/轨迹/运动 golden | 核心 manifest `verified`，首个差异 tick 可定位 | 回退到对应核心任务，不进入 UI 全量 |
-| M3 虚拟设备和恢复 | M2 通过 | RT-02..04、FS-02/03、PY-01/02、COM-03..05 | HAL/PLC/IO/故障/配额/重启/断网矩阵通过 | 阻断仿真会话发布，保留本地证据 |
+| M2 核心行为 | M1 通过，K0 入口审计完成 | CORE-03..08、K0-K5、native/WASM runner、解释/轨迹/运动 golden | 核心 manifest `verified`，每个运动学族的首个差异 tick 可定位 | 回退到对应 K/核心任务，不进入 UI 全量 |
+| M3 虚拟设备和恢复 | M2 通过，K6 完成 | RT-02..04、FS-02/03、PY-01/02、COM-03..05、运动学数字孪生 | HAL/PLC/IO/故障/配额/重启/断网矩阵通过 | 阻断仿真会话发布，保留本地证据 |
 | M4 前端工作流 | M3 通过 | FE-01..10、COM-06、关键 UI/3D/配置工作流 | UI 条目有协议、源文件、测试、oracle 和恢复证据 | 禁止 mock 冒充完成，回退 FE/COM |
 | M5 发布候选 | M0..M4 通过 | REG-01..04、REL-01 | G0-G5 全绿、全计入条目 `accepted`、排除项可识别 | 维持候选冻结，创建修复 context 或回退 |

--- a/docs/linuxcnc-web-wasm-kinematics-migration-plan.md
+++ b/docs/linuxcnc-web-wasm-kinematics-migration-plan.md
@@ -0,0 +1,304 @@
+# LinuxCNC Web/WASM 运动学完整移植计划
+
+**文档状态**：重梳理版 v1.0
+**适用基线**：LinuxCNC `2.10.0~pre0`，以 [`context-lock.json`](../context-lock.json) 为准
+**目标**：完成所有纳入 `configs/sim/**` 的运动学类型、配置变体、正解/逆解、回零、模式切换和浏览器可视化闭环
+**上位实施**：[完整仿真机床实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)
+**源程序关联**：[功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)
+**覆盖验收**：[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)
+
+本文件将运动学从“CORE-04 的一个任务”提升为贯穿核心、运动、HAL、数字孪生、可视化和回归的主线。它不把算法按文件名简单罗列，而是要求每个类型都闭合：配置选择、参数解析、坐标/关节映射、正解、逆解、分支标志、回零、限制/奇异性、固定 tick、故障注入、native/WASM oracle、UI 姿态和恢复。
+
+## 1. 为什么运动学必须单独成线
+
+LinuxCNC 的 `KINEMATICS` 不只是一个 `forward()`/`inverse()` 函数：
+
+- `KINEMATICS_IDENTITY`、`FORWARD_ONLY`、`INVERSE_ONLY`、`BOTH` 会改变 Task、motion、jog、home 和世界/关节模式转换。
+- `coordinates=` 可以重复轴字母（如 `XYYZ`），额外关节不进入 kinematics；映射错误会让解释器正确的轨迹驱动错误的关节。
+- 正解和逆解可能有多分支，需要 `KINEMATICS_FORWARD_FLAGS`、`KINEMATICS_INVERSE_FLAGS` 保持姿态连续；并行机构和机器人还需要上一次 pose 作为迭代初值。
+- 许多配置使用 `switchkins`、HAL 实现的 CoreXY 或 GUI 专用 kinematics，不能只按 `[KINS]KINEMATICS` 的模块名判断。
+- 5 轴刀尖跟随、转台/摆头、Delta/Hexapod、SCARA/PUMA 等算法的单位、角度、奇异点和收敛策略不同；“能编译”不代表“可运行”。
+
+因此运动学主线是 M2 核心行为进入 M3 HAL/数字孪生和 M4 UI 的硬门。运动学主线未达到 `verified`，不得把任意非 trivkins 配置标为可运行。
+
+## 2. 锁定来源和类型清单
+
+### 2.1 公共接口和适配基础
+
+必须逐文件登记并保留 `source_sha`：
+
+| 来源组 | 文件 | 作用 |
+|---|---|---|
+| ABI/类型 | `src/emc/kinematics/kinematics.h` | `EmcPose`、四种 kinematics 类型、正逆解 flags、home 和 switch API |
+| 映射/通用 | `kins_util.c`、`userkfuncs.c`、`ugenserkins.c` | `coordinates` 到 joint 映射、identity 实现、用户模板 |
+| 切换 | `switchkins.c`、`switchkins.h` | 0/1/2 类型选择、last pose、迭代正解和 GUI pins |
+| 几何 | `src/libnml/posemath/**`、`src/libnml/gomath/**` | 变换、矩阵、向量、数值容差和姿态表示 |
+| 运动耦合 | `src/emc/motion/control.c`、`command.c`、`motion.c`、`homing.c` | kinematics 类型如何影响 mode、home、限位、following error 和实际位置 |
+
+### 2.2 LinuxCNC 实际运动学实现族
+
+下表是代码级实现族，不等同于配置数量。每个文件都要进入 manifest；同一算法的 `.c/.cc` 变体不能只保留一个目录状态。
+
+| 族 | 实现文件 | 几何类别 | 典型配置入口 |
+|---|---|---|---|
+| 笛卡尔/映射 | `trivkins.c`、`maxkins.c`、`rotatekins.c` | 轴与关节同构、最大轴/旋转映射、identity/both 变体 | `axis/*.ini`、`qtaxis/xyz`、`gmoccapy/*axis*` |
+| 耦合线性 | `corexykins.c`、`rosekins.c` | 线性关节耦合、双电机/特殊并联映射 | `axis/corexy/*`、`axis/rose_engine/*` |
+| 泡沫/扩展轴 | `5axiskins.c`、`trivkins` 重复轴/extra joints | XYZ 与 UVW、旋转轴、非 kins extra joints | `axis/foam/*`、9 轴/extra-joints 配置 |
+| 转台/摆头 | `trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c` | table-rotary-tilting、刀尖/偏置变换 | `axis/vismach/5axis/*`、`gmoccapy/non_trivial_kinematics/*` |
+| Delta | `lineardeltakins.c/.cc`、`lineardeltakins-common.h` | 线性 Delta 正逆解、工作空间限制 | `axis/ldelta*`、`tklinuxcnc/ldelta.ini` |
+| Rotary Delta | `rotarydeltakins.c/.cc`、`rotarydeltakins-common.h` | 旋转 Delta 几何 | `axis/rdelta.ini` |
+| Tripod/并联 | `tripodkins.c` | 三腿并联、姿态分支 | `tklinuxcnc/tripod.ini` |
+| Hexapod | `genhexkins.c`、`genhexkins.h` | 六杆并联、迭代正解、平台上下分支 | `axis/vismach/hexapod-sim/*` |
+| Pentapod | `pentakins.c/.h` | 五杆并联、平台姿态和分支 | `axis/pentapod/*` |
+| 通用串联机器人 | `genserkins.c`、`genserfuncs.c`、`genserkins.h` | DH 链、Jacobian、迭代逆/正解 | `qtaxis/non-trivial/scara` 及机器人样例 |
+| SCARA | `scarakins.c` | 平面串联、腕部旋转、分支选择 | `axis/vismach/scara/*`、`qtvcp_screens/non-trivial/scara/*` |
+| PUMA | `pumakins.c` | 6 轴串联、腕部奇异性和分支 | `axis/vismach/puma/*` |
+| Scorbot | `scorbot-kins.c` | 机器人专用几何和姿态分支 | `configs/sim` 中 Scorbot/robot 资源 |
+| 用户/示例 | `cubic.c/.h`、`userkfuncs.c`、`ugenserkins.c` | 用户参数和模板；不允许动态宿主插件 | 只在 manifest 明确登记后启用 |
+| 切换容器 | `switchkins.c` | 多算法运行时切换 | SCARA、Hexapod 和含 switchkins 的配置 |
+
+除了 `KINEMATICS` 值，还要扫描 `HALFILE` 中的 `corexy_by_hal`、`xyzab_tdr_kins`、`loadrt` 和 GUI pin；这些可能在 HAL 或用户组件层实现变换。
+
+### 2.4 K0-INV-01 闭合审计（2026-08-20）
+
+`coverage/kinematics-source-closure.report.json`（schema `v2`）是本节点的机器可读证据，并以当前 `context_id` 绑定到锁定来源。报告不只按文件名计数，而是把 source index、source-symbols、配置行和 HAL 行转成稳定 ID：
+
+| 审计面 | 结果 | 证据字段 |
+|---|---:|---|
+| `src/emc/kinematics` 全目录文件 | 38 个，其中 35 个 `.c/.cc/.h` 实现/头文件 | `source.files[*].source_id`、`extension`、`sha256` |
+| `KINEMATICS=`（`.ini` 和 `.inc`） | 268 条 | `configuration.entries[*].config_id` |
+| `loadrt`、HAL 变换、switchkins 控制 | 111 条；模板 `[KINS]KINEMATICS`、`corexy_by_hal`、`motion.switchkins-type` 分别保留 | `hal.entries[*].config_id`、`kind`、`family` |
+| 实现族 | 11 族均有源码 ID 和配置候选映射 | `families[*].source_ids`、`configuration_ids` |
+| 测试输入 | `tests/matrixkins` 6 个文件；`linuxcnc/unit_tests/kinematics` 缺失 | `tests.*`、`missing_required_test_roots` |
+| FK/IK oracle | 11 族全部 `blocked` | `families[*].oracle.reason`、`closure.oracle_blocked_families` |
+
+缺失的官方测试根目录来自锁定提交本身；报告不会把 `tests/matrixkins/**` 改名或升级为 `unit_tests/kinematics/**`。`matrixkins` 仍作为 HAL 组件/配置入口候选登记，待契约变更或补充官方输入后才能产生 native FK/IK golden。2 个 TRT `.c` 文件在现有 source-symbols 报告中是 `indexed_empty`，不是静默丢失；其 source ID、哈希和待补符号状态均保留。
+
+### 2.5 K0-INV-02 配置图与样本集（2026-08-20）
+
+`coverage/kinematics-config-graph.report.json` 将审计报告中的 262 个 `KINEMATICS` 条目和 111 个 HAL/切换条目展开为 373 个入口节点、1,491 个文件/族/资源节点和 2,774 条有向边。模板化 `loadrt [KINS]KINEMATICS` 的解析状态分为 `explicit_reference`、`directory_owner` 和 `inactive_reference`；后两类保留来源事实，但不能当作已启动配置。图的 `orphan_entry_ids` 和 `unowned_template_ids` 必须为空。
+
+`coverage/kinematics-oracle-samples.jsonl` 为 11 个实现族各登记一个固定 `fk_ik_fk_roundtrip` 样本、候选配置、输入姿态/关节、容差和精确字段。样本当前全部 `blocked`，原因仍是锁定提交没有 `linuxcnc/unit_tests/kinematics/**`；`tests/matrixkins/test.ini` 只作为 `user_static` 的配置候选，未被提升为官方 oracle。只有补充/批准输入契约后，才允许把 `execution.status` 改为可运行并生成 native golden。
+
+### 2.6 K0-ORACLE-01 runner/schema（2026-08-20）
+
+`scripts/generate_kinematics_oracle_report.py` 在固定 `PATH/HOME/LANG/LC_ALL/TZ/PYTHONHASHSEED` 环境中运行 `build-native/sim_kinematics_test` 作为 native smoke，并为 11 个样本输出 `coverage/kinematics-oracle.report.json`。`coverage/kinematics-golden-schema.json`（`linuxcnc-web-wasm/kinematics-golden.v1`）要求 `status/error_code/kinematics_type/branch_id/flags/current_tick/config_hash/axis_joint_mapping` 等字段；缺字段不会通过比较。当前 native smoke 为 `passed`，但 11 个样本均为 `blocked`，错误码为 `MISSING_OFFICIAL_ORACLE`，没有伪造数值 golden。
+
+### 2.7 K1-CONTRACT-01 ABI contract（2026-08-20）
+
+`coverage/kinematics-abi-contract.json` 从 `sim_kinematics.h`、`wasm-core/CMakeLists.txt` 和固定数值策略生成。它锁定 ABI version 1、8 个公开函数、结果/类型/mode 枚举、3 个结构体字段列表、`SIM_KIN_ERR_*` 错误码、`-ffp-contract=off`/`-fno-fast-math`、非有限值拒绝、100000 最大迭代和 FNV-1a-64 state hash；缺失 Emscripten export 会使 contract `blocked`。当前 contract `verified`，native/WASM 构建及 8 个 CTest 均通过。
+
+`coverage/kinematics-mapping-contract.json` 进一步锁定 ASCII case-fold、重复轴 first-wins、extra-joint 数量、home 零位、inclusive limits、forward/inverse 映射和 state hash 输入字段；`sim_kinematics_test` 已覆盖 `XYYZ`、越界和 home 样本。
+
+`coverage/kinematics-numeric-policy.json` 固定 `-ffp-contract=off`、禁用 fast-math、角度单位、100000 迭代上限、1e-12 奇异阈值、1e-9 golden 容差和 exact 字段；NaN/Inf、负容差、超迭代、奇异和越界都列入边界矩阵。
+
+### 2.3 当前 WASM 雏形的真实边界
+
+当前 `wasm-core/include/sim_kinematics.h`/`sim_kinematics.c` 只能作为 K1 之前的实验切片，不能作为完整实现证据：
+
+| 已存在 | 尚未闭合 |
+|---|---|
+| `trivkins`、`XYZAC-TRT`、`XYZBC-TRT`、`XYZBCW` 的有限正逆解和基础 joint limit 检查 | LinuxCNC 全部实现族：CoreXY、Rose、5axiskins 完整模式、Delta/RotaryDelta、Tripod、Hexapod、Pentapod、GenSer、SCARA、PUMA、Scorbot、switchkins 和用户静态扩展 |
+| 基础 `coordinates` 字符串和重复关节填充 | `KINEMATICS_TYPE` 四种语义、extra joints、完整轴 bitmap、world/joint mode 约束和 home 语义 |
+| 有限性检查、少量奇异性检查和 FNV 状态 hash | `fflags/iflags` 分支状态、last-pose/seed、residual、iterations、branch_id、确定性迭代策略和恢复字段 |
+| C API 单元样例 | LinuxCNC native FK/IK oracle、每个配置入口的 golden、HAL 实现等价性和 UI/Vismach 姿态证据 |
+
+另外，现有 `sim_kinematics.c` 尚未加入 `wasm-core/CMakeLists.txt` 的 `sim_core`/Emscripten module，`sim_kinematics_test.c` 也未进入 CTest；因此当前 `ctest` 的 7/7 通过不包含运动学验证。K1 的第一项集成工作必须先修复构建和测试注册，再谈算法族扩展。
+
+因此 K0/K1 不能只围绕现有 `sim_kinematics_*` 函数补测试；必须先完成统一契约，再按 K2-K5 族逐步替换或扩展实现。现有切片的错误码和字段若与统一 ABI 冲突，应通过版本化契约迁移，不得在旧 ABI 上堆叠不可兼容的类型。
+
+## 3. 统一运动学契约
+
+### 3.1 输入、输出和状态
+
+WASM 内部使用固定宽度、明确大小的结构，TypeScript 不接触 C 结构体布局。逻辑契约如下：
+
+```text
+KinematicsRequest {
+  kind: FORWARD | INVERSE | HOME | CHECK
+  joints[N] / pose{ x,y,z,a,b,c,u,v,w }
+  fflags: uint64
+  iflags: uint64
+  seed_pose: optional pose       # 迭代正解初值
+  config_hash: bytes32
+  simulation_tick: uint64
+}
+
+KinematicsResult {
+  status: OK | INVALID_INPUT | OUT_OF_RANGE | SINGULAR | NO_SOLUTION |
+          NOT_CONVERGED | UNSUPPORTED | NUMERIC_ERROR
+  joints[N] / pose
+  fflags: uint64
+  iflags: uint64
+  residual: float64
+  iterations: uint32
+  branch_id: uint32
+  state_hash: bytes32
+}
+```
+
+必须固定以下语义：
+
+1. `forward(joints)` 返回世界 pose，并更新适用的 `iflags`；`inverse(pose)` 返回关节，并更新适用的 `fflags`。
+2. flags 是会话状态的一部分，必须进入快照、golden 和恢复账本；不能每次调用清零来掩盖分支变化。
+3. `home()` 产生已知的世界 pose、joint 和 flags；不能只把所有关节设为零。
+4. `KINEMATICS_FORWARD_ONLY`、`INVERSE_ONLY` 的 mode 转换限制要与 LinuxCNC 一致；不支持的调用返回 `UNSUPPORTED`，不能返回伪造 pose。
+5. 所有输入输出先检查有限性、维数、单位和配置 hash；NaN/Inf、数组越界、未知轴字母和未知类型在进入算法前拒绝。
+
+### 3.2 坐标、关节和 extra joints
+
+`coordinates` 解析为轴索引到 joint 编号的稳定映射，并记录重复轴 bitmap。运动学 joint 数量与 `EMCMOT_MAX_JOINTS`、`NO_OF_KINS_JOINTS`、extra joints 的边界必须分开表示：
+
+- kinematics 只接收前 `NO_OF_KINS_JOINTS` 个关节；extra joints 由 motion/Task 管理，不得误传给算法。
+- `XYYZ`、`XYZY` 等重复坐标必须在配置加载时生成映射 golden，并在 joint/world 模式切换时复用。
+- 旋转轴的角度单位、绕轴方向、回绕策略和连续性要逐类型登记；不能用统一的线性限位代码代替。
+- UI 显示的 axis pose、joint pose、commanded/actual pose 必须注明坐标系和来源 tick。
+
+### 3.3 正逆解数值策略
+
+解析解与迭代解使用同一个数值政策：
+
+- Emscripten/native 固定编译选项、舍入模式和 `sin/cos/sqrt/atan2` 包装；算法不得调用墙钟或未锁定随机数。
+- 解析算法返回工作空间、关节限位、姿态范围和分支错误，而不是将超界结果钳位后返回 `OK`。
+- 迭代算法固定初值来源、最大迭代次数、收敛残差、步长/阻尼、奇异阈值和失败码；每次结果记录 `iterations/residual/branch_id`。
+- 对正逆解只使用定义好的几何容差；状态、分支、错误码和事件顺序必须精确一致。
+- 迭代正解（Hexapod、通用串联等）在相邻 tick 使用上一次有效 pose，但恢复后必须从 checkpoint 中恢复该 seed。
+
+## 4. 按算法族的实施要求
+
+### 4.1 笛卡尔和耦合线性族
+
+先完成 `trivkins` 的 identity/both/inverse-only/forward-only、坐标重复映射和 max/rotate 变体，再完成 `corexykins`、`rosekins` 的矩阵映射。每一类需要：
+
+- 正逆解矩阵和符号方向的单元向量测试；
+- 重复轴、extra joints、关节限位、回零和 joint/world 模式测试；
+- HAL 实现的 `corexy_by_hal` 与 kinematics 模块实现的对照，证明同一轨迹在两条链上等价；
+- 快速/1x/暂停恢复后的关节和世界 pose hash 一致。
+
+当前 K2 耦合切片已完成 CoreXY、Rose、MaxKins 和 RotateKins 的统一实现。CoreXY 复现 LinuxCNC 的半和/半差公式，并分别登记 `corexy_by_kins.ini` 与 `corexy_by_hal.ini`，HAL 组件路径保持为独立入口；Rose inverse 保存上一象限和累计圈数，跨 2→3 象限得到连续角度和稳定 branch；MaxKins 保留 pivot/B/C/U/V/W 修正公式并覆盖真实 `max5kins.ini` 的 `pivot-length=0`；RotateKins 覆盖负 C 旋转方向和 90°边界。锁定 LinuxCNC 没有 shipped 的 rotatekins `.ini`，因此新增的 `linuxcnc/configs/sim/axis/rotate/rotatekins.ini` 明确标为 workspace-derived fixture，不冒充官方配置或 oracle。`coverage/coupled-kinematics.report.json` 使用相同样本运行 native 与 WASM，并比较规范化 JSON 和 state hash；由于 `linuxcnc/unit_tests/kinematics` 不在锁定源中，报告状态仍为 partial/blocked，不生成伪造官方 golden。
+
+`K2-HAL-01` 已在同一契约上接入静态 `corexy_by_hal`。SimHAL 注册组件的 8 个 float pin 和 servo-thread function，周期内执行 `.comp` 的 `alpha/beta` 命令矩阵与 `j0/j1` 反馈矩阵；HAL 配置中的 `j0home/j1home` 路由在变换前保留 Cartesian home 语义，并与 `corexykins` 的 motor-joint home 明确区分。`coverage/corexy-hal.report.json` 对配置连接、公式、native/WASM 输出和 oracle 阻塞状态做确定性检查；完整 HAL 命令解析、其它组件和真实 unit-test oracle 仍属于后续节点。
+
+`K3-5AXIS-01` 已接入 `5axiskins` 的 XYZBCW spherical pivot 链。真实 `bridgemill/5axis.ini` 使用 `coordinates=xyzbcwy` 和七个 joints，重复 Y 由 first-wins 映射并在 inverse 后同步 suffix；pivot length 250、B/C 角度和 W 工具运动均进入 FK/IK 与 state hash。缺少 XYZBCW 任一必需字母返回 configuration error；`coverage/fiveaxis-kinematics.report.json` 对配置、源公式、重复轴、边界和 native/WASM 样本做确定性记录，官方 unit-test oracle 仍 blocked。
+
+`K3-TRT-01` 已接入 `xyzac-trt-kins` 与 `xyzbc-trt-kins` 共用的 `trtfuncs.c` 姿态链。`table-rotary-tilting/xyzac-trt.ini` 与 `xyzbc-trt.ini` 的 `sparm=identityfirst`、五关节、tool/offset HAL pins 均登记；XYZAC 保持 C→A 顺序，XYZBC 保持 C→B 顺序，offset 与 tool length 进入固定解析式。B=90 的配置边界显式返回 singular，native/WASM 样本和 hash 见 `coverage/trt-kinematics.report.json`；switchkins 运行时切换容器留到 K5，不在本节点伪装完成。
+
+`K3-ROBOT-01` 已接入 SCARA、PUMA 和 Scorbot 专用解析式。SCARA 使用 D1-D6、C 总姿态和 elbow 分支；PUMA 使用 A2/A3/D3/D4/D6、完整旋转矩阵/RPY 转换以及 shoulder/elbow/wrist 分支和 wrist singular 检查；Scorbot 使用固定 L0/L1/L2 链和受控点 RZ 逆解。SCARA 与 PUMA 取自 shipped Vismach 配置，Scorbot 因锁定源没有 shipped INI 使用明确标注的 workspace-derived fixture。PUMA 等复杂三角函数的 native/WASM state hash 在 `1e-9` golden 容差上规范化，避免后端 libm 末位差异成为伪状态分叉；所有不可达/奇异边界和官方 oracle 状态见 `coverage/robot-kinematics.report.json`。
+
+`K3-GENSER-01` 已接入六关节 Craig DH 链和固定零初值的阻尼数值 Jacobian inverse。DH `A/ALPHA/D` 数组、alpha 弧度与 joint 度数转换、有限差分步长、阻尼、最大迭代次数、residual 和不收敛错误均进入配置/报告；melfa 与 puma560 的真实 `genserkins` 配置作为候选，样本在 native/WASM 逐字一致。此节点不把动态 `switchkins` 或用户库放行到浏览器，官方 unit-test oracle 仍 blocked，详见 `coverage/genser-kinematics.report.json`。
+
+`K4-DELTA-01` 已接入 linear/rotary Delta 的统一 forward/inverse/mapping 路径。线性 Delta 使用锁定 `lineardeltakins-common.h` 的 120 度塔架与杆长解析二次式；旋转 Delta 使用锁定 `rotarydeltakins-common.h` 的平台/大腿/小腿/足端几何。两者均固定 XYZ 到前三个 kinematics joints 的映射，A/B/C/U/V/W 透传，额外 joints 不进入算法；默认根保持 LinuxCNC 的平台根，`SIM_KIN_DELTA_ALTERNATE_ROOT` bit 0 使 alternate root、`branch_id` 和 state hash 可观察。真实 `ldelta.ini`、`ldelta_demo.ini`、`tklinuxcnc/ldelta.ini`、`rdelta.ini` 均登记；nominal/alternate root、工作空间无解、关节限位和 rotary `z=0` 奇异边界在 native/WASM 逐字对照。配置引用的 HAL 文件在锁定工作区缺失，作为 resource gap 保留，不能升级为配置 smoke 或数值 golden；官方 `linuxcnc/unit_tests/kinematics/**` 同样缺失，全部 Delta oracle 明确 blocked，详见 `coverage/delta-kinematics.report.json`。
+
+### 4.2 5 轴转台/摆头族
+
+`5axiskins`、`xyzac-trt-kins`、`xyzbc-trt-kins` 必须共享但不能混用各自的旋转顺序、刀尖点和 offset 语义。验收至少包括：
+
+- A/B/C 旋转顺序、正负方向、角度单位和回绕；
+- table-rotary 与 tool-rotary 的姿态链；
+- `identityfirst` 参数、刀长/刀尖偏置、G43/G43.1/G49 与逆解；
+- 旋转轴接近 0/180/360 度、万向节/姿态奇异和无解报警；
+- impeller、table-rotary-tilting、dual-rotary 的真实 `configs/sim` 入口和 Vismach 姿态。
+
+### 4.3 Delta、Tripod、Hexapod、Pentapod
+
+并联机构不能只测“一个可达姿态”。每种机构需要工作空间边界、腿长/关节范围、平台上下分支、奇异面和迭代初值测试：
+
+- Delta：塔架几何、臂长、平台平移边界、负根/无根和线性/旋转变体；
+- Tripod：三腿约束、姿态分支、回零和连续轨迹；
+- Hexapod：六杆长度、平台上下姿态、迭代正解、last-pose 和 GUI pins；
+- Pentapod：五杆约束、平台姿态、不可达/奇异区域和 `pentapod.var` 参数。
+
+每次迭代必须输出 residual 和迭代次数。相同 seed、输入和 tick 必须得到相同分支；越过分支边界时要产生可解释的 `SINGULAR` 或 `NO_SOLUTION` 事件，不能突然跳姿态。
+
+### 4.4 通用串联机器人族
+
+`genserkins` 以 DH 链、Jacobian 和迭代求解为核心；`scarakins`、`pumakins`、`scorbot-kins` 是专用参数化实现。实施顺序：
+
+1. 统一 link 参数、角度单位、joint offset、正方向和关节范围。
+2. 先用 FK 生成 pose oracle，再用 FK→IK→FK round-trip 验证每一个分支。
+3. 对 Jacobian 条件数、阻尼、步长、初值和最大迭代建立配置字段，全部进入快照。
+4. 覆盖 elbow-up/down、腕部翻转、SCARA 平面无解、PUMA wrist singularity 和 Scorbot 专用姿态。
+5. UI 轨迹显示必须消费 kinematics 输出的姿态，不能用线性 axis 拼接替代机器人 FK。
+
+### 4.5 Switchkins 和用户扩展
+
+`switchkins` 不是动态加载的放行口，而是静态注册的最多三种实现容器。每个 `switchkins_type` 必须有：
+
+- 类型、坐标要求、最大 joint 数、是否允许重复轴、是否迭代正解的 manifest；
+- 切换前后同步点、flags/lastpose 初始化和 GUI pin；
+- 非法类型、缺失实现、切换中运动、恢复后重建和回滚测试。
+
+`userkfuncs`、`ugenserkins` 和 `.so/.so` 类宿主动态模块不能直接加载。可移植用户运动学必须在构建期编译为静态 WASM 模块，提供相同 ABI、版本和 capability；不满足时返回 `UNSUPPORTED_USER_KINS` 并阻断配置启动。
+
+## 5. 运动学主线任务和里程碑
+
+M0/M1 的基线和会话骨架保持不变；从原 `M2-CORE-04` 起，采用以下 K 系列主线。K 系列任务完成后才能解锁对应的 M3/M4 工作流。
+
+| 里程碑 | 任务 | 结果 | 依赖 | 退出门槛 |
+|---|---|---|---|---|
+| K0 清单与 oracle | `K0-INV-01` 源文件/符号索引；`K0-INV-02` 配置入口图；`K0-ORACLE-01` native FK/IK/golden schema | 完整类型、参数和配置清单 | M0 | 所有 kinematics 文件和入口有 source/feature/test/oracle；缺失输入显式 blocked |
+| K1 ABI 与数值 | `K1-CONTRACT-01` C ABI；`K1-CONTRACT-02` flags/pose/映射；`K1-NUM-01` 浮点/迭代政策 | `sim_kinematics.h`、错误码、状态 hash | K0、M1 | 同输入三次字节和 hash 一致；非法/NaN/Inf/越界全有测试 |
+| K2 笛卡尔/耦合 | `K2-TRIV-01` trivkins 全类型；`K2-TRIV-02` 重复轴/extra joints；`K2-COUPLED-01` corexy/rose/max/rotate；`K2-HAL-01` HAL 等价链 | identity、both、耦合线性运动学 | K1 | 轴/关节模式、home、限位、HAL 和恢复 golden 全绿 |
+| K3 5 轴串联 | `K3-5AXIS-01` 5axiskins；`K3-TRT-01` xyzac/xyzbc/trt；`K3-ROBOT-01` SCARA/PUMA/Scorbot；`K3-GENSER-01` DH/Jacobian | 5 轴、转台/摆头和串联机器人 | K2、posemath | FK/IK round-trip、分支、奇异、刀尖/刀长和真实配置入口通过 |
+| K4 并联机构 | `K4-DELTA-01` linear/rotary Delta；`K4-TRIPOD-01` tripod；`K4-HEX-01` genhex；`K4-PENTA-01` pentapod | 全部并联正逆解和迭代恢复 | K1、K2 | 工作空间边界、无解、奇异、分支、lastpose、GUI pins 和故障注入通过 |
+| K5 切换/扩展 | `K5-SWITCH-01` switchkins；`K5-USER-01` 静态 userk/ugenser；`K5-CFG-01` 参数和能力注册 | 可切换和构建期扩展模型 | K3、K4 | 非法切换、缺模块、恢复、版本和权限错误明确；无动态宿主加载 |
+| K6 运动集成 | `K6-MOTION-01` TP→IK→motion；`K6-MOTION-02` FK feedback；`K6-HOME-01` home/limit；`K6-IO-01` spindle/tool/probe | 运动学与 Task/HAL/IO/数字孪生闭环 | K2-K5 | `configs/sim` 运动学入口可启动、运行、暂停、急停、恢复 |
+| K7 UI/回归 | `K7-VIS-01` 姿态/关节/刀尖渲染；`K7-REG-01` 全配置；`K7-REG-02` 浏览器故障矩阵 | 可视化和全量回归 | K6、M3/M4 | 轨迹、姿态、joint/world、报警、回放和多浏览器证据齐全 |
+| K8 发布闭合 | `K8-REL-01` 兼容报告；`K8-REL-02` 迁移/回滚；`K8-REL-03` 许可证/来源闭包 | 运动学纳入完整仿真机床发布 | K0-K7 | 受影响条目全部 `accepted`，无孤儿、无未解释差异、无静默降级 |
+
+`K4-TRIPOD-01` 已完成：`tripodkins.c` 的点顶点三杆并联机构已接入统一 forward/inverse/mapping，使用真实 `linuxcnc/configs/sim/tklinuxcnc/tripod.ini` 和 `linuxcnc/lib/hallib/tripodsim.hal` 验证 XYZ/AD-BD-CD 映射、above/below 根分支、三角不等式无解、基面奇异、关节限位、退化基座和固定零迭代；native/WASM JSON 与 state hash 一致，官方 oracle 因锁定来源缺少 `linuxcnc/unit_tests/kinematics/**` 继续显式 blocked。证据见 `coverage/tripod-kinematics.report.json`。
+
+`K4-HEX-01` 已完成：`genhexkins.c` 的六腿 Stewart 平台已接入统一 forward/inverse/mapping，使用真实 `linuxcnc/configs/sim/axis/vismach/hexapod-sim/hexapod.ini` 与 `kinematics.hal` 验证六腿闭式逆解、Newton 6x6 正解、确定性初始种子、alternate seed、非正 strut、迭代上限、最大误差、奇异 Jacobian、限位、HAL GUI/迭代 pin 和 native/WASM state hash；官方 oracle 继续显式 blocked。证据见 `coverage/genhex-kinematics.report.json`。
+
+每个 K 里程碑都必须同时更新 `coverage/manifest.jsonl`、source map、golden 索引、任务指针和证据摘要。算法代码通过单测但没有配置入口或 UI 姿态证据时，不能推进到下一个里程碑。
+
+## 6. 运动学测试矩阵
+
+每个实现族至少有以下测试层；参数和样本由 K0 清单生成，不允许只挑“容易收敛”的点：
+
+| 层 | 样本 | 必测内容 |
+|---|---|---|
+| 纯函数 | 合法 pose/joint、边界、随机种子固定的网格 | FK、IK、FK→IK→FK、IK→FK→IK、flags 和 residual |
+| 几何边界 | 轴/关节最小最大、工作空间边缘、旋转回绕 | limit、无解、奇异、分支连续性 |
+| 配置 | 每个非 trivkins `configs/sim` 入口及所有 `trivkins` 变体 | 参数、坐标、HALFILE、tool/var、资源图和启动错误 |
+| 运动 | G0/G1/G2/G3、5 轴刀尖、jog、home、暂停、abort | TP→IK→motion、反馈、following error、最终姿态 |
+| 故障 | 探针、限位、主轴/换刀、迭代不收敛、Python 异常 | 报警、停止、恢复、状态 hash 和事件顺序 |
+| 持久化 | checkpoint、journal、刷新、Worker 重启、离线 | flags、lastpose、seed、工具和姿态恢复一致 |
+| 浏览器 | Chromium/Firefox/Safari 计划矩阵、窄屏/触摸 | 3D 非空、姿态无跳变、背压、错误可见 |
+
+### 6.1 Golden 和容差
+
+native runner 为每个样本保存输入 hash、配置 hash、算法版本、pose/joint、flags、residual、iterations、branch、错误和最终 state hash。WASM 只允许在已登记的浮点字段使用容差；以下字段必须精确：
+
+```text
+status / error_code / kinematics_type / branch_id
+flags / current_tick / event_order / config_hash
+axis-to-joint mapping / home result presence / state transition
+```
+
+差异报告必须包含首个 divergent tick、字段路径、原生值、WASM 值、容差、source_id 和可重放命令。迭代不收敛不得被提高最大迭代次数或放宽容差“修绿”；应记录算法参数和失败原因。
+
+## 7. 与整体仿真机床的接合顺序
+
+运动学主线不是独立库，接合顺序固定如下：
+
+1. K1 ABI 完成后，`sim_motion` 只通过 `KinematicsRegistry` 调用，不再硬编码 trivkins。
+2. K2 完成后，解释器/TP 的 canonical 轨迹接入 axis/joint 变换，HAL 反馈接入 FK。
+3. K3/K4 完成后，数字孪生为每种机床提供真实 joint/pose 反馈、限位、回零和故障；Vismach/Three.js 使用同一 FK 结果。
+4. K5 完成后，Python/remap/VCP 获得只读 kinematics 状态和受控切换命令；切换必须经过 Task 同步点。
+5. K6 完成后，OPFS checkpoint 保存 kinematics type、参数、flags、lastpose、seed 和 joint/pose 状态。
+6. K7 完成后，UI 同时显示世界坐标、关节坐标、机床姿态、刀尖和限制原因；不能把 axis 数值当成所有机床的刀具姿态。
+
+## 8. 当前执行和停止线
+
+当前 `M2-CORE-04` 的 `unit_tests/kinematics/**` 缺失仍然是 K0 的输入审计事项，不自动改成实现任务。立即顺序为：
+
+1. `K0-INV-01` 确认锁定提交的 kinematics 文件、符号和测试路径，生成缺失输入报告。
+2. `K0-INV-02` 从 `configs/sim`、`tests/matrixkins` 和实际 kinematics 配置生成入口图；这些可以作为配置 oracle，但不能冒充缺失的官方 unit test。
+3. `K0-ORACLE-01` 在原生 runner 中建立 FK/IK JSONL schema 和最小 trivkins/corexy/非平凡样本。
+4. 经审查决定是否创建新的输入契约/context lock；未决定前保持 blocked，不跳到 HAL 节点。
+5. K1 ABI 和数值政策完成后，再按 K2→K5 算法族推进；K6 以前不开放全量 UI 运动学声明。
+
+以下条件必须停止并回到对应里程碑：输入源或配置入口遗漏；正逆解首次差异未定位；分支/flags/lastpose 未进入快照；算法依赖墙钟或随机数；用伪造 pose、钳位越界值、放宽容差或刷新重建掩盖失败；用户运动学需要未登记的动态宿主库。
+
+完成 K8 后，运动学才能从“核心切片”升级为“仿真机床完整能力”，并作为整个 LinuxCNC Web/WASM 发布的必要条件。
--- a/docs/linuxcnc-web-wasm-simulation-coverage.md
+++ b/docs/linuxcnc-web-wasm-simulation-coverage.md
@@ -151,7 +151,7 @@
 | 补偿 | cutter radius、tool length、dynamic tool length、additional tool offset、wear、螺距误差 | `SIM-CORE` |
 | 主轴同步 | threading、G33/G33.1、rigid tapping、CSS、gear、orient、multiple spindle | `SIM-DEVICE` |
 | 控制环 | PID、feed/velocity/position loop、encoder、stepgen、adaptive feed | `SIM-CORE` |
-| 运动学模块 | `trivkins`、`5axiskins`、`corexykins`、`cubic`、`genhexkins`、`genserkins`、`lineardelta`、`maxkins`、`pentakins`、`rosekins`、`rotarydelta`、`rotatekins`、`scarakins`、`scorbot`、`tripod`、`xyzac-trt`、`xyzbc-trt`、`switchkins`、`ugenser/userkfuncs` | `SIM-CORE` |
+| 运动学模块 | `trivkins`、`5axiskins`、`corexykins`、`cubic`、`genhexkins`、`genserkins`、`lineardelta`、`maxkins`、`pentakins`、`rosekins`、`rotarydelta`、`rotatekins`、`scarakins`、`scorbot`、`tripod`、`xyzac-trt`、`xyzbc-trt`、`switchkins`、`ugenser/userkfuncs` | `SIM-CORE`；实现族、正逆解、分支/奇异性和 K0-K8 门禁见[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md) |
 | DH/机器人 | DH 参数、PUMA、SCARA、六足、Delta、Pentapod、Scorbot 和自定义静态 kinematics | `SIM-CORE` |
 | 用户 kinematics | 构建期静态 WASM ABI、热切换由仿真状态机完成 | `SIM-ADAPTER` |
 | 坐标/姿态显示 | joints、axes、pose、forward/inverse、tool orientation 和 singularity 错误 | `WEB-EQUIV` |
--- a/docs/linuxcnc-web-wasm-source-map.md
+++ b/docs/linuxcnc-web-wasm-source-map.md
@@ -44,7 +44,7 @@
 | Worker 协议与固定 tick 边界 | `wasm-core/include/sim_protocol.h`、`wasm-core/src/sim_protocol.c`、`web/worker/sim-session.mjs`、`web/worker/sim-worker.mjs` | 版本化 envelope、单调 seq/tick、会话状态机和错误映射；WASM 核心只暴露受控 C ABI | `wasm-core/tests/sim_protocol_test.c`、`web/worker/test_wasm_session.mjs`、`scripts/test_protocol.py` |
 | RTAPI、OS 接口和时钟 | `linuxcnc/src/rtapi/**`；`linuxcnc/src/libnml/os_intf/timer.cc`、`_timer.c`、`sem.cc`、`shm.cc`；`linuxcnc/src/emc/linuxcnc.h` | 固定逻辑时钟、虚拟同步原语和受控内存；内核实时、CPU 绑定和设备访问标记为 `REAL-EXCLUDED` | `linuxcnc/tests/lowlevel/**`、`linuxcnc/tests/rtapi-shmem/**`（可移植部分） |
 | Motion、回零和限位 | `linuxcnc/src/emc/motion/motion.c`、`control.c`、`command.c`、`homing.c`、`emcmotglb.c`、`emcmotutil.c`、`simple_tp.c`、`motion_struct.h`、`homing.h` | `sim_motion` 状态机；虚拟编码器、开关、跟随误差和故障注入 | `linuxcnc/tests/hard-limits/**`、`linuxcnc/tests/abort/**`、`linuxcnc/tests/limit3/**` |
-| Kinematics | `linuxcnc/src/emc/kinematics/*kins.c`、`*kins.cc`、`kins_util.c`、`genserfuncs.c`、`trtfuncs.c`、`switchkins.c`；关键文件包括 `trivkins.c`、`5axiskins.c`、`genhexkins.c`、`genserkins.c`、`lineardeltakins.c`、`rotarydeltakins.c`、`corexykins.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c` | 静态 WASM 模块和 manifest 注册；不使用宿主动态库 | `linuxcnc/configs/sim/axis/gantry/**`、`linuxcnc/configs/sim/axis/foam/**`、`linuxcnc/configs/sim/axis/ldelta*`、机器人样例；运动学单测 |
+| Kinematics | `linuxcnc/src/emc/kinematics/*kins.c`、`*kins.cc`、`kins_util.c`、`genserfuncs.c`、`trtfuncs.c`、`switchkins.c`；关键文件包括 `trivkins.c`、`5axiskins.c`、`genhexkins.c`、`genserkins.c`、`lineardeltakins.c`、`rotarydeltakins.c`、`corexykins.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c` | 静态 WASM 模块和 manifest 注册；不使用宿主动态库；按[K0-K8 运动学主线](linuxcnc-web-wasm-kinematics-migration-plan.md)闭合正逆解、flags、分支、奇异性和恢复 | `linuxcnc/configs/sim/axis/gantry/**`、`linuxcnc/configs/sim/axis/foam/**`、`linuxcnc/configs/sim/axis/ldelta*`、机器人样例；运动学单测和 native FK/IK golden |
 | Posemath 和几何 | `linuxcnc/src/libnml/posemath/posemath.cc`、`posemath.h`、`gomath.c`、`gomath.h`、`sincos.c`、`gotypes.h` | 原样编译或等价 ABI；固定浮点编译选项 | posemath 相关单测、TP/kinematics golden |
 | Tooldata、工具表和数据库 | `linuxcnc/src/emc/tooldata/tooldata_common.cc`、`tooldata_nml.cc`、`tooldata_db.cc`、`tooldata_mmap.cc`、`tool_mmap_read.cc`、`tooldata.hh` | 内存工具服务 + OPFS 事务；兼容 pocket、offset、wear 和数据库迁移 | `linuxcnc/tests/mdi-queue/**`、`linuxcnc/configs/sim/**/*.tbl` |
 | IO、换刀、主轴和冷却 | `linuxcnc/src/emc/iotask/ioControl.cc`、`ioControl_v2.cc`；`linuxcnc/src/emc/tooldata/**` | 虚拟 IO、主轴、换刀、探针和故障模型；真实协议排除 | `linuxcnc/configs/sim/axis/iocontrolv2/**`、`linuxcnc/configs/sim/axis/lathe_multispindle/**`、换刀测试 |
--- a/docs/linuxcnc-web-wasm-technical-roadmap.md
+++ b/docs/linuxcnc-web-wasm-technical-roadmap.md
@@ -6,12 +6,14 @@
 **范围**：只做仿真，不连接真实机床，不通过网络控制硬件
 **兼容目标**：以 LinuxCNC 仿真模式为行为基线，覆盖全部仿真功能并给出浏览器内等价实现
 **执行治理**：[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)
+**完整实施蓝图**：[完整仿真机床实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)
+**运动学主线**：[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)
 **逐项验收**：[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)
 **源码关联**：[仿真功能与源程序关联目录](linuxcnc-web-wasm-source-map.md)
 **前端与通信**：[前端与 LinuxCNC 通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)
 **总控执行**：[仿真移植总控执行手册](linuxcnc-web-wasm-integration-playbook.md)

-本路线定义架构、范围、风险和阶段 A-E；任务上下文预算、提交格式、断网接续、里程碑退出条件和发布门禁统一由[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)约束；功能到 LinuxCNC 实际源文件、配置和测试的关联以[源程序关联目录](linuxcnc-web-wasm-source-map.md)为入口；浏览器 UI、Worker 协议、状态契约、前端任务和 FE-M0..M5 里程碑以[前端与通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)为准；端到端依赖、任务目录、场景验收和当前实施状态以[总控执行手册](linuxcnc-web-wasm-integration-playbook.md)为准。
+本路线定义架构、范围、风险和阶段 A-E；具体启动状态机、固定 tick 顺序、资源闭包和阶段产物以[完整仿真机床实施蓝图](linuxcnc-web-wasm-full-port-implementation.md)为准；任务上下文预算、提交格式、断网接续、里程碑退出条件和发布门禁统一由[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)约束；功能到 LinuxCNC 实际源文件、配置和测试的关联以[源程序关联目录](linuxcnc-web-wasm-source-map.md)为入口；浏览器 UI、Worker 协议、状态契约、前端任务和 FE-M0..M5 里程碑以[前端与通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)为准；端到端依赖、任务目录、场景验收和当前实施状态以[总控执行手册](linuxcnc-web-wasm-integration-playbook.md)为准。

 ## 1. 摘要

@@ -413,7 +415,7 @@ cmake --build build-wasm

 ## 9. 分阶段实施路线

-本节的阶段 A-E 映射到执行策略中的 M0-M5；阶段退出条件、任务边界和返工规则以[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)第 4、6、7 节为准。
+本节的阶段 A-E 映射到执行策略中的 M0-M5；其中阶段 B 的运动学具体拆分为 K0-K8，阶段退出条件、任务边界和返工规则以[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)第 4、6、7 节和[运动学完整移植计划](linuxcnc-web-wasm-kinematics-migration-plan.md)为准。

 ### 阶段 A：全量清单和运行时骨架

@@ -424,7 +426,7 @@ cmake --build build-wasm

 ### 阶段 B：核心解释和运动全覆盖

- 移植全部 G/M/O、remap、参数、坐标系、补偿、TP、motion 和全部内置 kinematics。
+- 移植全部 G/M/O、remap、参数、坐标系、补偿、TP、motion 和全部内置 kinematics；运动学必须按 K0 来源/oracle、K1 ABI、K2 笛卡尔耦合、K3 5 轴/串联、K4 并联、K5 switch/user、K6 运动集成顺序推进。
 - 完成 mill、lathe、gantry、robot、delta、pentapod、foam、plasma、laser 和 probe 虚拟机床模型。

 ### 阶段 C：HAL、PLC、IO 和虚拟机床部件
--- a/docs/task-history.md
+++ b/docs/task-history.md
@@ -0,0 +1,46 @@
+# 任务证据索引
+
+本文件是按需读取的历史索引，不是启动上下文。完整日志和大型 JSONL 产物只通过路径、大小和 SHA-256 追溯；不要把它们复制回 `nextTask.md` 或新的 context packet。
+
+当前指针：`nextTask.md`；当前 context：`linuxcnc-2.10.0-pre0-wasm-m1-py-c1`（与 `context-lock.json` 一致）。
+
+## 已验证节点
+
+| 节点 | 结果摘要 | 主要产物 |
+|---|---|---|
+| `BOOTSTRAP-M0-01` | 基线、下载索引、ABI bootstrap 和上下文包测试通过 | `coverage/source-index.jsonl`, `coverage/manifest.jsonl` |
+| `INV-01a..d` | 文档能力、源码符号、配置资源、测试入口索引确定性生成 | `coverage/document-capabilities.jsonl`, `coverage/source-symbols.jsonl`, `coverage/config-resources.jsonl`, `coverage/test-entries.jsonl` |
+| `INV-02a..b` | 规范化 source ID、依赖闭包和 unresolved/orphan 报告生成 | `coverage/normalized-sources.jsonl`, `coverage/dependency-closure.jsonl` |
+| `INV-03a` | native runner、golden schema 和严格 oracle 通过 | `scripts/native_runner.py`, `coverage/golden-schema.json` |
+| `M1-CORE-01` | 最小 protocol、Worker session 和真实 WASM smoke 通过 | `wasm-core/src/sim_protocol.c`, `web/worker/sim-session.mjs` |
+| `M1-CORE-02` | 事件容量、回放、快照完整性和序列约束通过 | `wasm-core/src/sim_event.c`, `web/worker/replay.mjs` |
+| `M1-FS-01` | workspace journal/recovery prepare/commit/abort 和损坏记录阻断通过 | `web/workspace/journal.mjs`, `web/workspace/recovery.mjs` |
+| `M1-RT-01` | runtime error/capability mapping fail-closed 通过 | `web/worker/error-map.mjs`, `web/worker/capabilities.mjs` |
+| `M1-RT-02` | 当前最近验证点；报告和脚本单测通过 | `coverage/runtime-mapping.report.json` |
+| `M2-CORE-01` | posemath/TP adapter、固定浮点、segment error boundary 和 state hash 通过 | `coverage/posemath-runtime.report.json` |
+| `M2-CORE-02` | 固定 ASCII 数值解析、G/M 模态、canonical 输出和失败边界通过 | `coverage/interpreter-runtime.report.json` |
+| `M2-CORE-03` | 固定容量 motion queue、连续性、fixed tick 和 canonical state 通过 | `coverage/motion-runtime.report.json` |
+| `M2-CORE-04` | blocked：锁定任务声明的 `linuxcnc/unit_tests/kinematics/**` 不存在 | `nextTask.md` |
+| `K0-INV-01` | 35 个实现/头文件、262 个去重 KINEMATICS 入口、111 个 HAL/切换入口和 11 个实现族已登记；所有族因官方 unit-test 根缺失显式 blocked | `coverage/kinematics-source-closure.report.json` |
+| `K0-INV-02` | 262 个去重后的 KINEMATICS 条目与 111 个 HAL/切换条目闭合为 373 个入口节点、2,774 条边；11 个固定 FK/IK 样本定义全部保留 blocked | `coverage/kinematics-config-graph.report.json`, `coverage/kinematics-oracle-samples.jsonl` |
+| `K0-ORACLE-01` | native kinematics smoke 通过；11 个样本严格按 golden schema 输出并因缺失官方 oracle 全部 blocked，无伪造 golden | `coverage/kinematics-oracle.report.json`, `coverage/kinematics-golden-schema.json` |
+| `K1-CONTRACT-01` | sim_kinematics ABI、错误码、结构体、导出集合和数值策略生成 contract 并验证；native/WASM/CTest 通过 | `coverage/kinematics-abi-contract.json` |
+| `K1-CONTRACT-02` | flags、pose、duplicate-axis、home、limits、axis-to-joint mapping 和 state hash 行为已登记并由 native CTest 覆盖 | `coverage/kinematics-mapping-contract.json` |
+| `K1-NUM-01` | 浮点编译、角度单位、迭代上限、容差、exact 字段和六类边界错误已固定 | `coverage/kinematics-numeric-policy.json` |
+| `K2-TRIV-01` | trivkins 四种 mode、coordinates case-fold、XYZ/XYZABCUVW、重复轴和 extra-joint 行为已接入现有 slice；245 个真实配置候选已映射，官方 oracle 仍 blocked | `coverage/trivkins-integration.report.json` |
+| `K2-TRIV-02` | 明确并实现 kinematics joint 前缀与 extra-joint 分离；重复轴 first-wins、joint_count mismatch、home、limit、state hash native/WASM 回归通过 | `coverage/kinematics-mapping-contract.json`, `wasm-core/tests/sim_kinematics_test.c` |
+| `K2-COUPLED-01` | CoreXY、Rose、MaxKins、RotateKins 统一接入；三项 shipped 配置加一个明确标注的 rotatekins 工作区派生候选、FK/IK round-trip、CoreXY HAL/kins 入口区分、Rose quadrant/revolution continuity、Max pivot 和 Rotate 90°边界、native/WASM JSON 与 state hash 对照通过；官方 oracle 继续显式 blocked | `coverage/coupled-kinematics.report.json`, `wasm-core/src/sim_kinematics.c` |
+| `K2-HAL-01` | 静态 `corexy_by_hal` 注册到 SimHAL；命令/反馈 8-pin 矩阵、servo tick 调度、alpha/beta 方向、Cartesian home 信号与 `corexykins` 入口区别由 native/WASM 对照通过；官方 oracle 继续显式 blocked | `coverage/corexy-hal.report.json`, `coverage/hal-runtime.report.json`, `wasm-core/src/sim_hal.c` |
+| `K3-5AXIS-01` | `5axiskins` 接入统一 XYZBCW spherical pivot 变换；bridgemill 真实配置、`xyzbcwy` 重复 Y 映射、pivot length、FK/IK round-trip、缺必需坐标边界和 native/WASM state hash 对照通过；官方 oracle 继续显式 blocked | `coverage/fiveaxis-kinematics.report.json`, `wasm-core/src/sim_kinematics.c` |
+| `K3-TRT-01` | XYZAC/XYZBC TRT 统一接入；table-rotary-tilting 两个真实 `identityfirst` 配置、旋转顺序和 offset 参数、FK/IK round-trip、B=90 奇异边界、native/WASM state hash 对照通过；switchkins 动态切换和官方 oracle 保持后续/blocked | `coverage/trt-kinematics.report.json`, `wasm-core/src/sim_kinematics.c` |
+| `K3-ROBOT-01` | SCARA、PUMA、Scorbot 统一接入；scara/puma shipped 配置加 scorbot 工作区派生候选、几何参数、FK/IK 分支 round-trip、不可达/奇异边界和 native/WASM 对照通过；state hash 使用 1e-9 浮点规范化，官方 oracle 继续显式 blocked | `coverage/robot-kinematics.report.json`, `wasm-core/src/sim_kinematics.c` |
+| `K3-GENSER-01` | Genser DH 六链 forward 与固定零初值阻尼 Jacobian inverse 接入；melfa/puma560 真实 DH 配置、迭代 residual/iteration、固定上限不收敛、非有限 DH 边界和 native/WASM 对照通过；官方 oracle 继续显式 blocked | `coverage/genser-kinematics.report.json`, `wasm-core/src/sim_kinematics.c` |
+| `K4-DELTA-01` | Linear/rotary Delta 统一 forward/inverse/mapping；四个真实配置候选、默认/alternate root、工作空间无解、关节限位、rotary z=0 奇异、固定零迭代和 native/WASM state hash 对照通过；缺失 HAL 资源与官方 oracle 均显式 blocked | `coverage/delta-kinematics.report.json`, `wasm-core/src/sim_kinematics.c`, `scripts/generate_delta_kinematics_report.py` |
+| `K4-TRIPOD-01` | Point-vertex tripod 统一 forward/inverse/mapping；真实 `tripod.ini`/`tripodsim.hal`、XYZ/AD-BD-CD 映射、above/below 根分支、无解/基面奇异/限位/退化几何边界、固定零迭代和 native/WASM state hash 对照通过；官方 oracle 因锁定来源缺少 `linuxcnc/unit_tests/kinematics/**` 继续 blocked | `coverage/tripod-kinematics.report.json`, `wasm-core/src/sim_kinematics.c`, `scripts/generate_tripod_kinematics_report.py` |
+| `K4-HEX-01` | Genhex 六腿 Stewart 平台统一 forward/inverse/mapping；真实 `hexapod.ini`/`kinematics.hal`、六腿闭式逆解、Newton 6x6 正解、alternate seed、非正 strut、迭代上限、最大误差、奇异 Jacobian、限位、HAL GUI/迭代 pin 和 native/WASM state hash 对照通过；官方 oracle 因锁定来源缺少 `linuxcnc/unit_tests/kinematics/**` 继续 blocked | `coverage/genhex-kinematics.report.json`, `wasm-core/src/sim_kinematics.c`, `scripts/generate_genhex_kinematics_report.py` |
+
+## 追溯规则
+
+- 需要精确命令时读取对应提交或 CI 产物，不把完整 stdout/stderr 粘贴进任务指针。
+- 需要验证哈希时读取 `context-lock.json` 和相应 `coverage/*.report.json`；二进制和大型 JSONL 默认不进入模型上下文。
+- 新交接只替换当前节点摘要；旧摘要保留在本索引或版本历史中，不能累积到指针文件。