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/nextTask.md
+++ b/nextTask.md
@@ -1,380 +1,79 @@
-# LinuxCNC Web/WASM 任务接续入口
+# LinuxCNC Web/WASM 任务接续指针

-**用途**：恢复工作时唯一的任务指针，固定“从哪个节点开始”和“完成后进入哪个节点”
-**更新时间**：2026-08-20
-**Context ID**：`linuxcnc-2.10.0-pre0-wasm-m0-c1`
-**当前里程碑**：M0 基线锁定
-**里程碑状态**：进行中，尚未通过 M0 退出门禁
+这是恢复工作的唯一入口。它必须保持为小型、无历史的任务指针；完整日志、源码和旧交接记录均按路径按需读取。

-> 每次开始工作先读本文件。不要根据聊天记录、目录数量或演示结果推测当前任务。专项范围以文档为准，任务位置以本文件为准。
-
-## 1. 接续记录
+## Current

 ```yaml
-handoff_version: 1
-context_id: linuxcnc-2.10.0-pre0-wasm-m0-c1
-milestone: M0
-last_verified_checkpoint: M1-RT-02-r01
-current_task:
-  id: M2-CORE-01
-  status: ready
-  title: posemath/TP 原生核心接入
-  owner: WS-0
-  profile: feature
-next_task:
-  id: M2-CORE-02
+pointer_version: 3
+updated: 2026-08-21
+context_id: linuxcnc-2.10.0-pre0-wasm-m1-py-c1
+milestone: K4
+last_verified_checkpoint: K4-HEX-01-r01
+task:
+  id: K4-PENTA-01
  status: pending
-  title: rs274ngc interpreter slice
+  title: pentapod integration
+  owner: WS-0
+  profile: feature
+next:
+  id: K5-SWITCH-01
+  status: pending
+  title: switchkins integration
  owner: WS-0
  profile: feature
 ```

-`BOOTSTRAP-M0-01` 只表示以下前置产物已验证，不表示 M0 完成：
+## Read

- `context-lock.json` 已锁定 LinuxCNC 提交和当前工具链。
- `coverage/source-index.jsonl` 与 `coverage/manifest.jsonl` 已生成 8,014 个文件级种子条目。
- `wasm-core` bootstrap ABI 可生成 WASM，宿主 ABI 单测通过。
- 基线、下载索引和上下文包测试通过。
+启动只读取本文件的 `Current`、`Task` 和 `Verify`。随后读取 `context-lock.json` 的摘要和当前任务列出的直接输入；不要自动加载路线图、覆盖矩阵、完整日志或 `coverage/*.jsonl`。需要历史时按需读取 [`docs/task-history.md`](docs/task-history.md)，需要完整产物时使用其中的路径、大小和哈希。

-文档能力、源码符号、配置资源、测试入口、规范化关联键、依赖闭包、原生 runner 契约、Worker 最小协议、事件回放、workspace journal、错误/能力映射、Python runtime 边界和 HAL 周期组件边界已完成；M0 仍缺少影响图，M2 从 posemath/TP 原生核心接入开始。因此当前任务从 `M2-CORE-01` 继续，不能把 bootstrap 当成 M2 完成功能。
-
-## 2. 开始工作时的读取顺序
-
-1. 本文件：确认 `context_id`、`current_task.id`、状态和最近验证点。
-2. [`context-lock.json`](context-lock.json)：确认源码提交、索引哈希、schema 和工具链没有漂移。
-3. [`docs/linuxcnc-web-wasm-context-governance.md`](docs/linuxcnc-web-wasm-context-governance.md)：读取当前任务行、最小任务契约和上下文预算。
-4. [`docs/linuxcnc-web-wasm-implementation-readiness.md`](docs/linuxcnc-web-wasm-implementation-readiness.md)：读取完整性定义、M0/M1 退出条件和实施顺序。
-5. [`docs/linuxcnc-web-wasm-source-map.md`](docs/linuxcnc-web-wasm-source-map.md)：只读取当前任务涉及的来源规则。
-
-开始修改前运行：
+基线门禁（开始修改前必须通过）：

 ```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
 ```

-任一命令失败时先修复或建立新的 context lock，不开始当前节点。
+生成 context packet 后，在实际模型调用前运行 `python3 scripts/validate_model_budget.py packet.json --context-window <window> --overhead-tokens <current-request-overhead>`；`--overhead-tokens` 只统计本次固定提示、工具 schema 和当前状态摘要，连续执行不得把上一轮对话累加进去。流式请求必须由 `scripts/model_stream.py` 消费；只有 `response.completed` 的 provider usage 通过 `validate_provider_response` 才能继续。断流、context overflow、usage 异常和 `length`/`max_tokens`/`max_output_tokens` 截断只保存 metadata-only checkpoint，并从更小的 packet 重新开始。

-## 3. 当前任务：M2-CORE-01
+## Task

-**目标**：接入 LinuxCNC posemath 与 TP 的可移植原生核心切片，固定浮点、状态和 golden 对照入口。
+**目标**：完成 pentapod 五腿并联运动学的统一 forward/inverse/mapping 集成。

-**直接输入**：
+**直接输入**：`coverage/genhex-kinematics.report.json`、`coverage/kinematics-source-closure.report.json`、`linuxcnc/src/emc/kinematics/pentakins.c`、`linuxcnc/src/emc/kinematics/pentakins.h`、`linuxcnc/configs/sim/axis/vismach/hexapod-sim/hexapod.ini`、`wasm-core/src/sim_kinematics.c`、`context-lock.json`。

- `linuxcnc/src/libnml/posemath/**`
- `linuxcnc/src/emc/tp/**`
- `linuxcnc/unit_tests/tp/**`
- `context-lock.json`
+**必须产出**：pentapod 真实/派生配置样本、五腿 FK/IK 与姿态约束、迭代收敛/不收敛/奇异/限位边界、native/WASM 对照和 blocked oracle 清单；更新迁移计划、manifest 和任务历史。

-**必须产出**：
+**完成条件**：配置候选；工作空间边界、姿态约束、奇异/无解、迭代上限、关节限位和 state hash 稳定；官方 oracle 缺失继续显式 blocked。

- `wasm-core/include/sim_posemath.h`
- `wasm-core/src/sim_posemath.c`
- `wasm-core/tests/sim_posemath_test.c`
- `coverage/posemath-runtime.report.json`
- 生成数量、输入摘要和输出 SHA-256
+**非目标**：本任务不批准替代 oracle 契约、不实现完整运动学 ABI、不接入 UI 运行时和 Python、不把配置 smoke 当作数值 golden。

-posemath/TP 切片必须固定 IEEE-754 浮点编译选项、输入 NaN/Inf/退化几何错误、单位与姿态序列化；原生参考结果和 WASM 结果通过相同 golden 字段与容差比较。
+**回滚点**：删除本任务新增 pentapod runner/golden 扩展，保留 `K4-HEX-01` 报告和 `M2-CORE-04` blocked 证据，并恢复本指针。

-**非目标**：
+## Next

- 不接入 Pyodide、全量 LinuxCNC 核心或 UI；这些在后续 M1/M2/M4 节点实施。
- 不把文档标题直接标记为 `accepted`。
- 不接入 rs274ngc、TP、全量 LinuxCNC HAL 组件或 UI 工作流。
+完成本任务后，在同一变更中把 `next` 提升为 `Current.task`，更新 `last_verified_checkpoint` 和最近证据摘要，并重新运行 `Read` 中的门禁。不得跳过未完成依赖；同一时刻只允许一个 current task。

-**完成条件**：
-
-1. 相同输入连续生成两次，输出字节完全一致。
-2. 相同 pose/segment 输入连续运行产生相同 canonical JSON 和状态哈希。
-3. NaN/Inf、退化 segment、越界速度和未知运动类型都有明确阻断结果。
-4. 生成器和失败路径有自动测试。
-5. `context-lock.json` 登记新索引的数量和 SHA-256；基线校验器验证该摘要。
-6. 本文件按第 5 节完成节点切换。
-
-建议验收命令：
+## Verify

 ```bash
-cmake --build build-native
-ctest --test-dir build-native --output-on-failure
-python3 scripts/test_posemath_runtime.py -v
-python3 scripts/test_protocol.py -v
-python3 scripts/validate_baseline.py
-sha256sum coverage/test-entries.jsonl
-```
-
-**回滚点**：删除本任务新增的生成器、测试和能力索引，恢复开始任务前的 `context-lock.json` 与本文件；不得改写已有 source index 和 manifest 种子来掩盖失败。
-
-## 4. 下一个任务：M2-CORE-02
-
-**进入条件**：`M2-CORE-01` 的全部完成条件通过，并在本文件记录验证命令、结果和产物哈希。
-
-**目标**：rs274ngc interpreter slice。
-
-**预期产出**：
-
- `linuxcnc/src/emc/rs274ngc/**`
- `linuxcnc/unit_tests/interp/**`
- `wasm-core/src/sim_interpreter.c`
-
-**完成后候选节点**：`M2-CORE-03`（canonical/motion queue）。
-
-## 5. 节点切换规则
-
-当前任务完成后，必须在同一个变更中更新本文件：
-
-1. 把 `last_verified_checkpoint` 更新为已完成任务 ID 和修订号，例如 `INV-01a-r01`。
-2. 在“已验证证据”中追加日期、精确命令、结果、产物路径、字节数和 SHA-256。
-3. 将原 `next_task` 原样提升为新的 `current_task`，状态改为 `ready`。
-4. 从 [`docs/linuxcnc-web-wasm-context-governance.md`](docs/linuxcnc-web-wasm-context-governance.md) 选择它的直接后继作为新的 `next_task`；不能跨过未完成依赖。
-5. 更新 `context-lock.json` 中受影响索引的哈希；如源码、工具链或 schema 改变，创建新 `context_id`，不能覆盖原基线含义。
-6. 重新运行第 2 节的基线命令。失败时不切换节点。
-
-同一时刻只能有一个 `current_task`。`next_task` 不得提前标为 `in_progress`，并行工作必须在独立任务包中登记，不能修改本文件的主接续链。
-
-## 6. 已验证证据
-
-### BOOTSTRAP-M0-01（2026-08-20）
-
-```text
-python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
-python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  24 tests passed
-scripts/build-wasm.sh
-  WASM module generated; native sim_api_test 1/1 passed
-```
-
-关键产物：
-
- `coverage/source-index.jsonl`：7,992 行，SHA-256 `b7d12bf83ca238db889dcaa00c6d157203b6e1bb0f4d33ae0e4fa8cc2e2e8288`
- `coverage/manifest.jsonl`：7,992 行，SHA-256 `dd90d52665725547a368b11779b180d06d416fe1b4f6695b6a120c76a81061cd`
- `build-wasm/linuxcnc-sim-core.js` 和 `.wasm`：可重建产物，不进入源码基线
-
-### INV-01a-r01（2026-08-20）
-
-```text
-python3 scripts/generate_document_capabilities.py
-  document_capabilities=2868
-python3 scripts/test_document_capabilities.py -v
-  4 tests passed
-连续生成两次
-  SHA-256 完全一致
-```
-
- `coverage/document-capabilities.jsonl`：2,868 行，1,286,866 字节，SHA-256 `adf5e8ffda82ac872dbd8246c4359ac94d2cab5cb11500d4663459bf1d03c787`
- 报告保留 2 个缺失的生成型 include 和 1 个空文档；没有重复 ID。
-
-### INV-01b-r01（2026-08-20）
-
-```text
-python3 scripts/generate_source_symbols.py
-  source_symbols=23983
-python3 scripts/test_source_symbols.py -v
-  3 tests passed
-```
-
- `coverage/source-symbols.jsonl`：23,983 行，SHA-256 `5fc72e6a268d2220b6335f7f6834c925f13c5c35461fa399a400e6621958875a`
- 覆盖 C/C++、Python 和 HAL `.comp` 声明；解析失败和无符号文件保留在报告中。
-
-### INV-01c-r01（2026-08-20）
-
-```text
-python3 scripts/generate_config_resources.py
-  config_resources=16093
-python3 scripts/test_config_resources.py -v
-  3 tests passed
-```
-
- 覆盖 233 个仿真 INI 入口，生成 16,093 条资源边。
- `coverage/config-resources.jsonl` SHA-256 `d4d02cb13f2f9cb58404630d4de8ac0226e02075166fe30f2b03a6abca4be5bc`
- 报告保留 997 个 missing 引用和 91 个 unresolved/宿主变量路径。
-
-### INV-01d-r01（2026-08-20）
-
-```text
-python3 scripts/generate_test_entries.py
-  test_entries=321 sha256=86449838257a7aab7c9219e641a14d4493208b35d8c0cc092d1fa149352c7c37
-python3 scripts/test_test_entries.py -v
-  3 tests passed
-python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
-python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  24 tests passed
-```
-
- `coverage/test-entries.jsonl`：321 条，SHA-256 `86449838257a7aab7c9219e641a14d4493208b35d8c0cc092d1fa149352c7c37`
- `coverage/test-entries.report.json`：214 shell、86 oracle、12 stream、1 Python、3 Meson build、5 unit source；24 条 `REAL-EXCLUDED`、65 条 `needs_review`。
- 所有入口 ID 唯一，连续生成输出字节一致；硬件/实时依赖未被删除或伪装成可移植。
-
-### INV-02a-r01（2026-08-20）
-
-```text
-python3 scripts/normalize_sources.py
-  normalized_sources=51257 sha256=b377df306f47d84b6cb42509c061c7ce8848c675b32899ab0004fe36a7df35ff
-python3 scripts/test_normalize_sources.py -v
-  3 tests passed
-```
-
- `coverage/normalized-sources.jsonl`：51,257 条，SHA-256 `64892fb51228f856c15fe31a55a5a619809013aa5db7325ad8dac390c5205edd`
- `coverage/normalized-sources.report.json`：51,257 个唯一规范化 ID；3 个重复原始资源 ID 以 `~dupN` 保留，0 个哈希冲突，0 个非预期缺失路径。
-
-### INV-02a-r02（2026-08-20）
-
-```text
 python3 scripts/generate_source_inventory.py
-  source_index=8003 manifest_seed=8003
-python3 scripts/normalize_sources.py
-  normalized_sources=51268 sha256=a9bb2d50952c52b3f3d1bd50e7dc7654cb3831f28ff8147d9c1fc493ebbe80cb
-```
-
- 新增 `wasm-core/**` 与 `web/**` 实现文件已登记；`coverage/normalized-sources.jsonl` 当前为 51,268 条。
-
-### INV-02b-r01（2026-08-20）
-
-```text
-python3 scripts/generate_dependency_closure.py
-  dependency_edges=37160 sha256=39ab6b831f4eb53347dbb509855ca05bc557e25abc5d76837c45ce037a3e44a9
-python3 scripts/test_dependency_closure.py -v
-  3 tests passed
+python3 scripts/generate_kinematics_closure_report.py
+python3 scripts/generate_kinematics_config_graph.py
+python3 scripts/generate_kinematics_oracle_report.py
+cmake --build build-native && ctest --test-dir build-native --output-on-failure
 python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
+python3 scripts/validate_task_pointer.py
 python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  30 tests passed
+find linuxcnc/src/emc/kinematics -maxdepth 1 -type f -print | sort
+rg -n --glob '*.ini' --glob '*.hal' --glob '*.py' 'KINEMATICS|loadrt .*kins|switchkins|corexy_by_hal' linuxcnc/configs/sim linuxcnc/tests
 ```

- `coverage/dependency-closure.jsonl`：37,160 条边，SHA-256 `39ab6b831f4eb53347dbb509855ca05bc557e25abc5d76837c45ce037a3e44a9`
- 报告：35,685 条已解析、1,475 条明确 unresolved/missing、74 条重复边、28,897 个无连接孤儿节点；未删除任何缺失引用。
+最近证据：`coverage/genhex-kinematics.report.json` 已验证真实 hexapod-sim 配置、六腿闭式逆解、Newton 6x6 正解、alternate seed、迭代/奇异/限位边界、native/WASM 字节一致和 state hash 一致；缺失 `linuxcnc/unit_tests/kinematics/**` 官方 oracle 继续显式 blocked。下一任务处理 `pentakins.c` 五腿并联约束。

-### INV-03a-r01（2026-08-20）
+## Stop

-```text
-python3 scripts/native_runner.py --self-test
-  native_runner=self-test status=passed
-python3 scripts/test_native_runner.py -v
-  3 tests passed
-python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
-python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  33 tests passed
-bash scripts/build-wasm.sh
-  WASM module generated; native sim_api_test 1/1 passed
-```
-
- `scripts/native_runner.py`：固定 `PATH/HOME/LANG/TZ/PYTHONHASHSEED`，固定 cwd，输出退出码、输出摘要、artifact 哈希和严格 oracle 状态。
- `coverage/golden-schema.json` SHA-256 `5513535b9480d7100ef3ef59ac933c4040bd7198dc419693a7ee68098171c423`
- `coverage/native-runner.report.json` SHA-256 `6f2105f154d12b99f4e1cd4af3cdb5df4a462f3665f1447d5959384be5d4fae2`
- `REAL-EXCLUDED` 和 `needs_review` 默认阻断；缺失/错误 golden 不会被当作通过。
-
-### M1-CORE-01-r01（2026-08-20）
-
-```text
-bash scripts/build-wasm.sh
-  WASM module generated; native sim_api_test 1/1 and sim_protocol_test 1/1 passed
-python3 scripts/test_protocol.py -v
-  5 tests passed
-node web/worker/test_sim_session.mjs
-  sim_session=passed
-node web/worker/test_wasm_session.mjs
-  wasm_session=passed tick=11
-python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
-python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  38 tests passed
-```
-
- `wasm-core/include/sim_protocol.h` / `sim_protocol.c`：schema 1、严格递增 seq、非递减 tick、生命周期状态机和 side-effect `operation_id` 校验。
- `web/worker/sim-session.mjs` / `sim-worker.mjs`：HELLO/CAPABILITIES、SESSION_ATTACH/READY、LOAD_WORKSPACE、SIM_STEP、SNAPSHOT_REQUEST、DESTROY envelope；默认拒绝上下文/序列/路径错误。
- WASM 导出新增 `_sim_protocol_*`、`_malloc`/`_free`；真实模块 Node smoke 验证固定 tick 与错误缺号。
-
-### M1-CORE-02-r01（2026-08-20）
-
-```text
-bash scripts/build-wasm.sh
-  WASM module generated; native sim_api_test 1/1, sim_protocol_test 1/1, sim_event_test 1/1 passed
-ctest --test-dir build-native --output-on-failure
-  3 tests passed
-node web/worker/test_replay.mjs
-  replay=passed cursor=3 tick=9
-node web/worker/test_wasm_session.mjs
-  wasm_session=passed tick=11
-python3 scripts/test_protocol.py -v
-  6 tests passed
-python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
-python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  39 tests passed
-```
-
- `wasm-core/include/sim_event.h` / `sim_event.c`：固定 256 条事件容量、严格 seq/tick、FNV-1a payload hash、容量查询、导出/导入和损坏长度拒绝。
- `web/worker/replay.mjs`：`event-log.v1`、`snapshot.v1`、base snapshot 链、内容哈希和终点回放校验；缺号、错误基线和篡改快照均阻断。
- `coverage/source-index.jsonl`：8,008 行，SHA-256 `59c6b71419a56cee47337946f5089314d172cecac725db7632636d9dc2f05fa1`
- `coverage/manifest.jsonl`：8,008 行，SHA-256 `780fc1d9260b1fbd4f946fc93c106b3c50df9b5ce065a50d40bcf9405fba0aeb`
- `coverage/document-capabilities.jsonl`：2,868 行，SHA-256 `fa5140bd4995224406381e4190e76bf81f64bd24dbf93a2fd10421c45aee4316`
- `coverage/normalized-sources.jsonl`：51,273 行，SHA-256 `4dd3c0b3adfb4e71db899213f35b084a0d8d0d71a6f6caafbd7a434abcf174ed`
-
-### M1-FS-01-r01（2026-08-20）
-
-```text
-node web/workspace/test_recovery.mjs
-  workspace_recovery=passed commit=1
-python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
-python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  39 tests passed
-bash scripts/build-wasm.sh
-  WASM module generated; native sim_api_test 1/1, sim_protocol_test 1/1, sim_event_test 1/1 passed
-node web/worker/test_replay.mjs
-  replay=passed cursor=3 tick=9
-node web/worker/test_wasm_session.mjs
-  wasm_session=passed tick=11
-```
-
- `web/workspace/journal.mjs` / `recovery.mjs`：`prepare/commit/abort` append-only records、规范化路径、data/content hash、半提交忽略、损坏 commit 阻断和恢复状态 hash。
- `coverage/workspace-recovery.report.json` SHA-256 `88dd1d851d487730edc6beb034a934ba1c19346312ed3cd4d4893c7259c431de`
- `coverage/source-index.jsonl` 当前 8,011 行；`coverage/normalized-sources.jsonl` 当前 51,276 行，哈希已登记在 context lock。
-
-### M1-RT-01-r01（2026-08-20）
-
-```text
-node web/worker/test_runtime_mapping.mjs
-  runtime_mapping=passed errors=18 exclusions=3
-python3 scripts/validate_baseline.py
-  baseline=valid
-python3 scripts/validate_download_index.py
-  download_index=valid
-python3 -m unittest discover -s scripts -p 'test_*.py' -v
-  39 tests passed
-bash scripts/build-wasm.sh
-  WASM module generated; native sim_api_test 1/1, sim_protocol_test 1/1, sim_event_test 1/1 passed
-```
-
- `web/worker/error-map.mjs`：18 个核心/协议/事件错误码统一到 code、message_key、category、retryable、operation_id、simulation_tick、source。
- `web/worker/capabilities.mjs`：10 个 limits、10 个受控命令、3 个 `REAL-EXCLUDED` 替代策略；未知项和超限值 fail-closed。
- `coverage/runtime-mapping.report.json` SHA-256 `f4be10828fda8201ff9e69de95bc68e5def42fc7206a851b37474c21b4da0a17`
-
-## 7. 停止条件
-
-出现以下任一情况时停止当前任务并记录阻断，不自行跳到下一个节点：
-
- `linuxcnc` 提交不再是 context lock 中的提交。
- 当前任务需要修改 ABI、协议或 manifest schema，但没有迁移方案。
- 必需输入缺失、索引无法确定性生成或来源存在无法解释的孤儿项。
- 为完成文档索引需要同时实现运行时功能。
- 验证失败只能通过删除样本、降低检查或标记 `REAL-EXCLUDED` 才能通过。
-
-本文件只保存当前节点、下一节点和最近可验证证据，不复制完整历史。更早的任务历史通过 context packet、产物路径和哈希追溯。
+若 LinuxCNC 提交偏离 lock、必需输入缺失、需要未审查的 ABI/protocol/manifest schema 变化、索引无法确定性生成，或测试只能靠删样本/降低检查/伪装 `REAL-EXCLUDED` 才通过，立即记录为 blocked，不跳到下一个节点。