新增 OPFS session readiness SDK helper

text14.txt

@@ -1638,3 +1638,69 @@ project_release_gate=ok
 若本批验证通过并提交，后续可以继续做低风险可维护性推进：为 project release gate 增加短文档索引或
 CI 入口说明；或者在真实 LinuxCNC host runtime 可用前，保持 blocked runtime family 不 promotion，
 只维护 guard、docs 和 workflow/API 边界。
+
+二十、2026-06-16 继续执行记录：OPFS machine session readiness SDK helper
+
+本轮按“功能实质性推进为主”继续推进，新增可直接复用的 OPFS/session readiness helper。该 helper
+允许外部 SDK/UI 调用方在真正加载 machine session 到 WASM 前，结构化检查 persisted INI、参数文件、
+工具表、可选 G-code 和可选 session snapshot 是否存在且 snapshot envelope 有效。
+
+完成内容：
+
+- 新增 `wasm-port/runtime/opfs/machine-session-readiness.js`；
+- 新增 `readMachineSessionReadiness(machineId, options)`；
+- helper 返回：
+  - `machineId`；
+  - `ready`；
+  - `phase`；
+  - `paths`；
+  - `checks`；
+  - `snapshotCheck`；
+  - `snapshot`；
+  - `missing`；
+  - `errors`；
+- 支持默认 machine file paths；
+- 支持显式 `iniOpfsPath`、`parameterOpfsPath`、`toolTableOpfsPath`；
+- 支持 `gcodeFilename`、`gcodeOpfsPath` 和 `gcodeRequired`；
+- 支持 `sessionId` 与 `snapshotFilename`，并复用现有 `loadMachineSessionSnapshot()` 做 snapshot
+  envelope/machine id 校验；
+- `wasm-port/runtime/sdk/src/index.js` re-export `readMachineSessionReadiness()`；
+- `wasm-port/tests/opfs/node/verify_file_service.mjs` 覆盖 ready session、missing session、
+  snapshot check、G-code check 与 invalid OPFS path；
+- `wasm-port/tests/sdk/node/verify_sdk_surface.mjs` 覆盖 SDK export；
+- `wasm-port/runtime/sdk/README.md` 记录新 SDK helper；
+- `wasm-port/docs/opfs-session-persistence.md` 记录 readiness workflow；
+- `wasm-port/tests/docs/node/verify_opfs_session_docs.mjs` 覆盖 docs drift；
+- `PROJECT_COMPLETION_TRACKER.md` 同步 OPFS/session 与 SDK/API surface 状态；
+- 未新增控制按钮；
+- 未执行 action-plan；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未运行 opt-in runtime probes；
+- 未 promotion blocked runtime family；
+- 未改变 LinuxCNC interpreter、tool、parameter、planner、kinematics、remap 或 LinuxCNC-owned
+  runtime semantics。
+
+已通过的定向验证：
+
+```bash
+git diff --check
+wasm-port/tests/opfs/node/verify_file_service.sh
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/docs/node/verify_opfs_session_docs.sh
+```
+
+关键输出：
+
+```text
+opfs_file_service_node_smoke=ok
+sdk_surface_node_smoke=ok
+opfs_session_docs_node_smoke=ok
+```
+
+下一步工作计划：
+
+继续以实质能力推进为主。下一批建议把 `readMachineSessionReadiness()` 接入 INI panel/session
+workflow 或 external shell handoff view-model，让 UI 在加载 session 前显示结构化 ready/blocked
+原因；仍保持只读，不新增控制按钮，不解析 G-code，不扩大 LinuxCNC 语义边界。