Initial LinuxCNC WebAssembly workspace snapshot

2026-08-20 18:21:15 +08:00
commit 5dd614c335
92 changed files with 200203 additions and 0 deletions
--- a/nextTask.md
+++ b/nextTask.md
@@ -0,0 +1,380 @@
+# LinuxCNC Web/WASM 任务接续入口
+
+**用途**：恢复工作时唯一的任务指针，固定“从哪个节点开始”和“完成后进入哪个节点”
+**更新时间**：2026-08-20
+**Context ID**：`linuxcnc-2.10.0-pre0-wasm-m0-c1`
+**当前里程碑**：M0 基线锁定
+**里程碑状态**：进行中，尚未通过 M0 退出门禁
+
+> 每次开始工作先读本文件。不要根据聊天记录、目录数量或演示结果推测当前任务。专项范围以文档为准，任务位置以本文件为准。
+
+## 1. 接续记录
+
+```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
+  status: pending
+  title: rs274ngc interpreter slice
+  owner: WS-0
+  profile: feature
+```
+
+`BOOTSTRAP-M0-01` 只表示以下前置产物已验证，不表示 M0 完成：
+
+- `context-lock.json` 已锁定 LinuxCNC 提交和当前工具链。
+- `coverage/source-index.jsonl` 与 `coverage/manifest.jsonl` 已生成 8,014 个文件级种子条目。
+- `wasm-core` bootstrap ABI 可生成 WASM，宿主 ABI 单测通过。
+- 基线、下载索引和上下文包测试通过。
+
+文档能力、源码符号、配置资源、测试入口、规范化关联键、依赖闭包、原生 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
+```
+
+任一命令失败时先修复或建立新的 context lock，不开始当前节点。
+
+## 3. 当前任务：M2-CORE-01
+
+**目标**：接入 LinuxCNC posemath 与 TP 的可移植原生核心切片，固定浮点、状态和 golden 对照入口。
+
+**直接输入**：
+
+- `linuxcnc/src/libnml/posemath/**`
+- `linuxcnc/src/emc/tp/**`
+- `linuxcnc/unit_tests/tp/**`
+- `context-lock.json`
+
+**必须产出**：
+
+- `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
+
+posemath/TP 切片必须固定 IEEE-754 浮点编译选项、输入 NaN/Inf/退化几何错误、单位与姿态序列化；原生参考结果和 WASM 结果通过相同 golden 字段与容差比较。
+
+**非目标**：
+
+- 不接入 Pyodide、全量 LinuxCNC 核心或 UI；这些在后续 M1/M2/M4 节点实施。
+- 不把文档标题直接标记为 `accepted`。
+- 不接入 rs274ngc、TP、全量 LinuxCNC HAL 组件或 UI 工作流。
+
+**完成条件**：
+
+1. 相同输入连续生成两次，输出字节完全一致。
+2. 相同 pose/segment 输入连续运行产生相同 canonical JSON 和状态哈希。
+3. NaN/Inf、退化 segment、越界速度和未知运动类型都有明确阻断结果。
+4. 生成器和失败路径有自动测试。
+5. `context-lock.json` 登记新索引的数量和 SHA-256；基线校验器验证该摘要。
+6. 本文件按第 5 节完成节点切换。
+
+建议验收命令：
+
+```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/validate_baseline.py
+  baseline=valid
+python3 scripts/validate_download_index.py
+  download_index=valid
+python3 -m unittest discover -s scripts -p 'test_*.py' -v
+  30 tests passed
+```
+
+- `coverage/dependency-closure.jsonl`：37,160 条边，SHA-256 `39ab6b831f4eb53347dbb509855ca05bc557e25abc5d76837c45ce037a3e44a9`
+- 报告：35,685 条已解析、1,475 条明确 unresolved/missing、74 条重复边、28,897 个无连接孤儿节点；未删除任何缺失引用。
+
+### INV-03a-r01（2026-08-20）
+
+```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、产物路径和哈希追溯。