381 lines
16 KiB
Markdown
381 lines
16 KiB
Markdown
# 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、产物路径和哈希追溯。
|