继续完成 web-rtcp-5axis-sim-plan

结论：完成 LinuxCNC kinematics WASM ABI 覆盖，并将 web-rtcp-5axis-sim-plan 的 RTCP frame/boundary adapter 接到 xyzac-trt kinematics SDK；Node、build、browser smoke 验证通过。
2026-06-21 16:44:29 +08:00
parent a6eda3fbff
commit 626bcfe8e3
101 changed files with 101586 additions and 770 deletions
--- a/textbak/text25.txt
+++ b/textbak/text25.txt
@@ -0,0 +1,691 @@
+项目接续文件：L4-PYTHON-REMAP OPFS/WASM runtime milestone 执行计划
+
+生成时间：2026-06-19 CST
+
+本文件接替 `text24.txt`，整理当前完成情况，并明确下一步：
+
+```text
+剩余 hard block 先做 L4-PYTHON-REMAP；
+L4-USER-M-PROCESS 放在 Python remap lifecycle proof 之后。
+```
+
+重要边界：
+
+```text
+本文件是单独 hard-block runtime milestone 的执行计划。
+不是 virtual HAL 新功能计划，也不是直接批量 promotion 计划。
+
+当前禁止事项：
+- 不用 JavaScript 重写 Python remap / prolog / epilog CNC 语义；
+- 不把 Python runtime 可 import 当成 remap pass；
+- 不把 NGC-only subroutine asset 当 standalone main program；
+- 不一次性解锁全部 53 个 L4-PYTHON-REMAP rows；
+- 不因为 native probe 通过就自动改 promotion_allowed；
+- L4-USER-M-PROCESS 仍不做 arbitrary external process execution。
+```
+
+一、当前完成情况快照
+
+1. virtual HAL 已接入 Web 数控仿真。
+
+已通过真实 browser simulation smoke：
+
+```bash
+SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
+```
+
+输出：
+
+```text
+browser_real_simulation_page_smoke=ok
+```
+
+当前 virtual HAL 覆盖范围：
+
+- browser HAL pin/signal/param state；
+- virtual `halcmd` command workflow；
+- ESTOP / power / home / jog / spindle / coolant state；
+- motion controller matrix；
+- virtual HAL session save/restore；
+- browser diagnostics / release evidence。
+
+边界不变：
+
+- G-code / interpreter / planner / canonical motion 语义仍来自 LinuxCNC-backed WASM；
+- virtual HAL 不提供 Linux kernel hard-realtime ABI；
+- virtual HAL 不提供外部硬件驱动 ABI 或 native HAL module ABI；
+- virtual HAL 不解锁 Python remap、external user-M process。
+
+2. L4-TOOL-DB proof 已完成接入，但仍要按 promotion lock 规则处理。
+
+已通过聚合 proof：
+
+```bash
+wasm-port/tests/host/verify_tool_db_process_proof.sh
+```
+
+输出：
+
+```text
+tool_db_process_port_sdk=ok
+tool_db_store_opfs=ok
+tool_db_process_port_wasm=ok
+browser_tool_db_process_smoke=ok
+tool_db_process_proof=ok
+```
+
+已通过 native opt-in DB_PROGRAM protocol probe：
+
+```bash
+ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
+```
+
+关键输出：
+
+```text
+tool_db_protocol_version=v2.1
+tool_db_get_all_count=10
+tool_db_put_tool_update_state_ok=1
+tool_db_load_spindle_state_ok=1
+tool_db_unload_spindle_state_ok=1
+tool_db_persistence_state_ok=1
+tool_db_runtime_probe_status=runtime_protocol_probe_passed
+```
+
+结论：
+
+```text
+L4-TOOL-DB 的 native / SDK / OPFS / WASM / browser proof chain 已经成立。
+后续不应再把主要精力放在 Tool DB runtime substrate 上，除非是 promotion lock
+收尾或 gate drift 修复。
+```
+
+3. 当前 sim-config inventory 快照。
+
+当前 `wasm-port/build/wasm/sim-configs-inventory/summary.tsv` 统计：
+
+```text
+total=159
+pass=29
+skip=130
+fail=0
+```
+
+当前 `skip-summary.tsv`：
+
+```text
+ASSET-ONLY=65
+L4-PYTHON-REMAP=53
+L4-USER-M-PROCESS=1
+NON_MAIN_CLASS=10
+UPSTREAM-DEMO=1
+```
+
+注意：
+
+```text
+这里已经不是 text24.txt 中的旧 baseline：
+executed=28 passed=28 skipped=131 unexpected_fail=0。
+
+当前可见 generated inventory 已是：
+PASS=29 SKIP=130 FAIL=0。
+后续文件和 gate 必须以当前 artifact 为准，不能沿用过期 baseline。
+```
+
+4. 当前剩余 hard block。
+
+主要剩余：
+
+```text
+L4-PYTHON-REMAP: 53
+L4-USER-M-PROCESS: 1
+```
+
+推荐顺序：
+
+```text
+1. L4-PYTHON-REMAP
+2. L4-USER-M-PROCESS
+```
+
+理由：
+
+- `L4-PYTHON-REMAP` 覆盖面最大，解决后可复用到 53 个 rows；
+- Tool DB milestone 已经建立 Python/WASM Worker、runtime port、browser proof、OPFS/diagnostics 的可复用模式；
+- `L4-USER-M-PROCESS` 只有 1 个 row，且浏览器不能支持 arbitrary external process，只能做受控 state-transition proof；
+- 先做 Python remap lifecycle substrate，能为后续 user-M 的受控 runtime proof 提供更成熟的边界模型。
+
+二、L4-PYTHON-REMAP 当前已有基础
+
+已有 machine-readable artifacts：
+
+```text
+wasm-port/build/wasm/sim-configs-inventory/python-remap-boundary-summary.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-family-summary.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-runtime-contract.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-runtime-gates.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-alignment.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-readiness.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-state-plan.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-fixture-plan.tsv
+wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-probe-gate.tsv
+```
+
+当前选定最小 fixture：
+
+```text
+family=axis/remap/stop-lookahead/nc_files
+fixture_id=stop_lookahead_python_runtime_lifecycle
+fixture_scope=no_python_callables_no_ngc_only_subpaths
+```
+
+原因：
+
+- 适合作为 Python runtime lifecycle proof；
+- 范围比 tool-change、five-axis、完整 remap family 更窄；
+- 已有 source/runtime readiness artifacts；
+- 可先证明 Python path、toplevel、module import、callable lookup、generator lifecycle、
+  remap phase dispatch 等生命周期边界。
+
+当前 fixture modules：
+
+```text
+axis/remap/stop-lookahead/python/remap.py
+axis/remap/stop-lookahead/python/toplevel.py
+```
+
+当前 runtime phases：
+
+```text
+initialize_python
+apply_ini_python_path
+execute_toplevel
+callable_lookup
+pycall_dispatch
+callable_invoke
+remap_phase_dispatch
+generator_finish
+execute_python_runtime
+reload_on_change
+```
+
+三、当前 native probe 状态
+
+默认 probe：
+
+```bash
+wasm-port/tests/native/probe_python_remap_runtime.sh
+```
+
+关键输出：
+
+```text
+python_remap_runtime_fixture_family=axis/remap/stop-lookahead/nc_files
+python_remap_runtime_fixture_id=stop_lookahead_python_runtime_lifecycle
+python_remap_runtime_requirements=python3:1,linuxcnc:1
+python_remap_missing_requirements=-
+python_remap_source_proof_ready=1
+python_remap_runtime_ready=1
+python_remap_execution_enabled=0
+python_remap_promotion_allowed=0
+python_remap_runtime_probe_status=ready_disabled_by_default
+```
+
+显式 opt-in native lifecycle probe：
+
+```bash
+ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
+```
+
+关键输出：
+
+```text
+python_remap_lifecycle_execute_finish_source_value=2
+python_remap_lifecycle_ini_path_prepend=python
+python_remap_lifecycle_ini_toplevel=python/toplevel.py
+python_remap_lifecycle_interpreter_sentinel_ok=1
+python_remap_lifecycle_toplevel_imported=1
+python_remap_lifecycle_remap_imported=1
+python_remap_lifecycle_callable_lookup_ok=1
+python_remap_lifecycle_generator_returned=1
+python_remap_lifecycle_generator_first_yield=2
+python_remap_lifecycle_generator_finish_ok=1
+python_remap_runtime_lifecycle_probe_ok=1
+python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
+```
+
+结论：
+
+```text
+L4-PYTHON-REMAP 已不是“从零设计”。
+native stop-lookahead lifecycle proof 已能通过；
+下一步是把这个 native pass evidence 接入 WASM/Worker proof、browser diagnostics、
+release artifact 和 promotion lock 后置 gate。
+```
+
+四、目标
+
+本 milestone 的目标不是直接让 53 个 `L4-PYTHON-REMAP` rows 全部 PASS。
+
+目标是证明：
+
+```text
+LinuxCNC-owned Python remap lifecycle + configured Python modules +
+interpreter state binding 可以在 native / WASM / browser proof chain 中成立。
+```
+
+第一目标 fixture：
+
+```text
+axis/remap/stop-lookahead/nc_files
+ini=axis/remap/stop-lookahead/demo.ini
+blocked=L4-PYTHON-REMAP
+modules=python/remap.py,python/toplevel.py
+```
+
+必须证明：
+
+- INI `[PYTHON]PATH_PREPEND=python` 被执行；
+- INI `[PYTHON]TOPLEVEL=python/toplevel.py` 被执行；
+- configured Python module 可 import；
+- callable lookup 来自 LinuxCNC Python remap lifecycle；
+- generator remap lifecycle 可开始、yield、finish；
+- interpreter sentinel / state binding 可观测；
+- diagnostics 明确 `promotion_allowed=0`，直到完整 native + WASM + browser + manual lock review 完成。
+
+五、Phase 1：把 native lifecycle pass evidence 接入 artifacts
+
+当前 native opt-in probe 已通过，但 generated artifact 里仍有历史状态：
+
+```text
+python-remap-native-runtime-probe-gate.tsv
+gate_status=ready_to_implement_lifecycle_probe
+proof_status=pending
+promotion_allowed=0
+```
+
+下一批应先做：
+
+1. 让 inventory/report layer 可读取 native probe stdout：
+
+```text
+wasm-port/build/native/python-remap-runtime/python_lifecycle.stdout.log
+```
+
+2. 生成 native pass evidence contract：
+
+```text
+python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
+python_remap_lifecycle_toplevel_imported=1
+python_remap_lifecycle_remap_imported=1
+python_remap_lifecycle_callable_lookup_ok=1
+python_remap_lifecycle_generator_finish_ok=1
+python_remap_runtime_lifecycle_probe_ok=1
+```
+
+3. 更新/新增 machine-readable artifacts：
+
+```text
+python-remap-native-runtime-probe-gate.tsv
+runtime-boundary-native-evidence-acceptance-gate.tsv
+runtime-boundary-post-native-pass-gates.tsv
+native-runtime-probe-pass-evidence-contract.tsv
+runtime-probe-gate-alignment.tsv
+```
+
+4. 仍保持：
+
+```text
+execution_enabled=0
+promotion_allowed=0
+manual_lock_update_required=1
+```
+
+验收命令：
+
+```bash
+ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_interp_browser.sh
+```
+
+六、Phase 2：定义 PythonRemapRuntimePort
+
+建议新增：
+
+```text
+wasm-port/runtime/sdk/src/python-remap-runtime-port.js
+wasm-port/runtime/sdk/src/python-remap-browser-worker-adapter.js
+wasm-port/runtime/workers/python-remap-worker.js
+wasm-port/tests/sdk/node/verify_python_remap_runtime_port.mjs
+wasm-port/tests/wasm/node/verify_python_remap_runtime_port_wasm.mjs
+wasm-port/tests/browser/verify_python_remap_runtime_browser.sh
+wasm-port/tests/browser/python_remap_runtime_browser_smoke.html
+```
+
+建议 API：
+
+```text
+createLinuxCncPythonRemapRuntimePort({
+  fixtureFamily,
+  iniPath,
+  pythonPathPrepend,
+  topLevelPath,
+  sourceFiles,
+  runtimeMode,
+  runtimeAdapter,
+})
+
+start()
+applyIniPythonPath()
+executeTopLevel()
+importModule(modulePath)
+lookupCallable(callableName)
+invokeGenerator(callableName, args)
+runLifecyclePlan(plan)
+exportTranscript()
+exportDiagnostics()
+close()
+```
+
+最小 lifecycle plan：
+
+```text
+1. initialize_python
+2. apply_ini_python_path
+3. execute_toplevel
+4. import python/remap.py
+5. lookup configured callable
+6. invoke generator
+7. observe first yield
+8. finish generator
+9. export interpreter sentinel/state
+10. export diagnostics
+```
+
+必须保持：
+
+```text
+executionEnabled=false
+promotionAllowed=false
+bulkPromotionAllowed=false
+```
+
+不允许：
+
+- JS 直接实现 remap callable 结果；
+- JS 构造 interpreter state 假装 Python remap pass；
+- 只用 fixture transcript 假装 runtime pass；
+- 跳过 `toplevel.py`；
+- 跳过 configured Python module import；
+- 把 Python module import success 当作 full remap lifecycle success。
+
+七、Phase 3：WASM/Worker runtime
+
+推荐复用 Tool DB milestone 的 runtime pattern：
+
+```text
+Browser/Node worker + Python/WASM provider + LinuxCNC-specific lifecycle shim
+```
+
+Worker 职责：
+
+- 加载 Python runtime provider；
+- 设置 INI 声明的 Python path；
+- 执行 `python/toplevel.py`；
+- import `python/remap.py`；
+- 通过受控 adapter 调用 lifecycle fixture；
+- 记录 transcript；
+- 导出 diagnostics。
+
+允许的 shim：
+
+```text
+minimal LinuxCNC Python remap integration shim
+```
+
+shim 只能覆盖 stop-lookahead fixture 必需的 integration surface，例如：
+
+- interpreter sentinel；
+- callable lookup bridge；
+- generator invocation bridge；
+- remap phase observations；
+- diagnostics state capture。
+
+shim 不允许承载：
+
+- generic interpreter semantics；
+- G-code parsing；
+- planner / canonical motion；
+- full tool-change semantics；
+- arbitrary Python UI process；
+- arbitrary external process。
+
+八、Phase 4：browser diagnostics proof
+
+新增 browser diagnostics 字段建议：
+
+```text
+python_remap_runtime_mode=browser-python-wasm-worker
+fixture_family=axis/remap/stop-lookahead/nc_files
+ini_path=axis/remap/stop-lookahead/demo.ini
+python_path_prepend=python
+toplevel=python/toplevel.py
+modules=python/remap.py,python/toplevel.py
+lifecycle_transcript_ready=true
+callable_lookup_ready=true
+generator_lifecycle_ready=true
+interpreter_state_binding_ready=true
+ngc_only_subroutine_promoted=false
+bulk_family_promotion_allowed=false
+promotion_allowed=0
+```
+
+browser gate 必须证明：
+
+- 页面/API 可读取 Python remap lifecycle diagnostics；
+- diagnostics 来源绑定 LinuxCNC config/source；
+- diagnostics 明确不是 JS-owned CNC semantics；
+- saved artifact 可进入 release URL / ini-panel workflow；
+- `L4-PYTHON-REMAP` 仍在 manual promotion lock 下。
+
+建议命令：
+
+```bash
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_python_remap_runtime_browser.sh
+```
+
+九、Phase 5：release artifact / promotion lock
+
+在 native + WASM + browser proof 全部通过前，release artifact 只能显示：
+
+```text
+L4-PYTHON-REMAP locked
+python_remap_native_lifecycle_ready=<0|1>
+python_remap_wasm_lifecycle_ready=<0|1>
+python_remap_browser_lifecycle_ready=<0|1>
+promotion_allowed=0
+```
+
+三层 proof 都 ready 后，仍不能自动批量解锁 53 rows。
+
+下一步只能考虑单独 review：
+
+```text
+axis/remap/stop-lookahead/nc_files: SKIP L4-PYTHON-REMAP -> PASS
+```
+
+并且必须证明：
+
+- 对应 row 不是 NGC-only subroutine；
+- 对应 INI / Python modules / remap declarations 都已 vendored；
+- native pass 与 WASM/browser lifecycle proof 对齐；
+- Python runtime 没有绕过 LinuxCNC interpreter lifecycle；
+- `promotion_allowed` 的变更是显式人工 review，不是 gate 自动推断。
+
+十、L4-USER-M-PROCESS 暂缓原则
+
+`L4-USER-M-PROCESS` 当前代表 row：
+
+```text
+axis/vismach/millturn/example.ngc
+```
+
+核心阻塞：
+
+```text
+M128 / M129 Tcl scripts
+HAL pin state updates
+kinstype guard
+ini.[xyz].* soft-limit state transitions
+```
+
+暂缓原因：
+
+- 浏览器不能支持 arbitrary executable spawn；
+- 浏览器不能通用执行 native Tcl process；
+- 不能模拟 host HAL daemon unrestricted side effects；
+- 成功只覆盖 1 个 row；
+- 更适合在 Python remap lifecycle / runtime diagnostics pattern 稳定后，做受控 state-transition proof。
+
+后续做法只允许：
+
+```text
+LinuxCNC-owned user-M state transition boundary
+```
+
+不允许：
+
+```text
+browser arbitrary external process execution
+```
+
+十一、下一批最小执行建议
+
+优先做一批小而可验收的改动：
+
+1. 固化 native Python remap lifecycle pass evidence。
+
+```bash
+ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
+```
+
+2. 让 generated inventory / release artifact 能识别：
+
+```text
+python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
+```
+
+3. 新增 `PythonRemapRuntimePort` contract-only SDK 层。
+
+4. 新增 Node contract test：
+
+```text
+wasm-port/tests/sdk/node/verify_python_remap_runtime_port.mjs
+```
+
+5. 暂不改 baseline，不改 53 rows。
+
+首批验收命令：
+
+```bash
+git diff --check
+ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
+```
+
+十二、结论
+
+当前状态可以概括为：
+
+```text
+virtual HAL 已接入 Web 仿真；
+L4-TOOL-DB proof chain 已成立；
+当前 generated inventory 为 PASS=29 / SKIP=130 / FAIL=0；
+剩余主要 hard block 是 L4-PYTHON-REMAP=53 和 L4-USER-M-PROCESS=1；
+下一步先做 L4-PYTHON-REMAP；
+首个 fixture 是 axis/remap/stop-lookahead/nc_files；
+native opt-in lifecycle probe 已通过；
+下一批应把 native pass evidence 接入 artifacts，并建立 PythonRemapRuntimePort
+的 WASM/browser proof chain；
+promotion_allowed 继续保持 0，直到完整 proof + manual lock review。
+```
+
+十三、2026-06-19 接续执行记录：L4-PYTHON-REMAP 仿真系统接入收尾
+
+本轮结论：
+
+```text
+L4-PYTHON-REMAP 的 native / SDK / WASM / browser proof chain 已接入；
+真实数控仿真页 runtime/ui/simulation 现在也暴露 Python remap runtime 状态；
+release artifact / URL workflow 能识别 python-remap-runtime-proof=ready；
+53 个 L4-PYTHON-REMAP inventory rows 仍保持 SKIP/manual promotion lock，
+不做批量 PASS，不启用 execution，不允许 promotion_allowed。
+```
+
+新增/补齐的仿真接入点：
+
+```text
+wasm-port/runtime/ui/simulation/simulation-app.js
+- createPythonRemapSimulationRuntimeStatus()
+- renderPythonRemapRuntimeStatus()
+- runRealBrowserSimulation() state.pythonRemapRuntime
+
+wasm-port/runtime/ui/simulation/index.html
+- Machine State 面板显示 L4-PYTHON-REMAP fixture/runtime/lifecycle/promotion 状态
+- window.linuxCncRealSimulationApi.getPythonRemapRuntimeStatus()
+- exportDiagnosticsArtifact().pythonRemapRuntime
+
+wasm-port/tests/browser/real_simulation_page_smoke.html
+- 验证 DOM / API / diagnostics artifact 的 Python remap runtime 状态
+```
+
+本轮验证：
+
+```bash
+wasm-port/tests/native/probe_python_remap_runtime.sh
+ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
+wasm-port/tests/sdk/node/verify_python_remap_runtime_port.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_python_remap_runtime_port_wasm.sh
+wasm-port/tests/browser/verify_python_remap_runtime_browser.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
+wasm-port/tests/browser/verify_release_artifact_url_workflow_browser.sh
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
+wasm-port/tests/sdk/node/verify_project_release_artifact_url_workflow.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+wasm-port/tools/verify_no_standalone_cnc_semantics.sh
+git diff --check
+```
+
+关键验证结果：
+
+```text
+python_remap_runtime_probe_status=ready_disabled_by_default
+python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
+python_remap_runtime_lifecycle_probe_ok=1
+python_remap_lifecycle_generator_first_yield=2
+python_remap_execution_enabled=0
+python_remap_promotion_allowed=0
+browser_python_remap_runtime_smoke=ok
+browser_real_simulation_page_smoke=ok
+browser_release_artifact_url_workflow_smoke=ok
+sim_configs_wasm_node_inventory_executed=29
+sim_configs_wasm_node_inventory_passed=29
+sim_configs_wasm_node_inventory_skipped=130
+sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53
+sim_configs_wasm_node_inventory_unexpected_fail=0
+standalone CNC semantics guard complete
+```
+
+仍保持的边界：
+
+```text
+executionEnabled=false
+promotionAllowed=false
+bulkPromotionAllowed=false
+ngcOnlySubroutinePromoted=false
+jsCncSemantics=false
+```