diff --git a/PROJECT_COMPLETION_TRACKER.md b/PROJECT_COMPLETION_TRACKER.md index 9231939..8ba5dfc 100644 --- a/PROJECT_COMPLETION_TRACKER.md +++ b/PROJECT_COMPLETION_TRACKER.md @@ -9,7 +9,7 @@ turn-by-turn continuation notes and next-batch execution records. ## Current Status - Active continuation file: `text14.txt` -- Latest completed batch: OPFS/session persistence release-gate docs +- Latest completed batch: sim-config coverage release-gate docs - Latest relevant commit: use `git log -1 --oneline` after each committed batch - Working tree at tracker creation: clean - Required policy: LinuxCNC remains the only CNC semantic source @@ -38,7 +38,7 @@ The project is complete for the current scope when all of the following are true | LinuxCNC semantic boundary | Stable | JS/browser remains glue, staging, OPFS, WASM/browser boundary, docs, and tests only. | | Vendor/source guard | Stable | `verify_vendor_sync.sh` and standalone semantic guard are required every batch. | | Interpreter WASM smoke | Stable | `interp_wasm_node_smoke=ok`. | -| Sim config inventory | Stable with skips | `executed=28`, `passed=28`, `skipped=131`, `unexpected_fail=0`. | +| Sim config inventory | Stable with skips | `executed=28`, `passed=28`, `skipped=131`, `unexpected_fail=0`; `docs/sim-configs-coverage-handoff.md` records the release-gate baseline. | | Native nc_files baseline | Stable | Last recorded Layer 1: `total 107`, `pass 101`, `expected_fail 6`, `unexpected_fail 0`. | | Native sim configs baseline | Stable | Last recorded Layer 2: `total 159`, `pass 151`, `expected_fail 8`, `unexpected_fail 0`. | | OPFS/session persistence | In progress | Browser smoke passes, SDK re-exports OPFS/session helpers, and `docs/opfs-session-persistence.md` defines the project-level release gate. | @@ -46,7 +46,7 @@ The project is complete for the current scope when all of the following are true | Browser/UI workflow | In progress | Workflow overview embedding mount DOM closure is complete; current focus is SDK/docs/release gate consolidation. | | Workflow overview embedding | In progress | Report/display/render, DOM contract/readiness/renderer, mount result/display/render, mount DOM contract/readiness/renderer/wrapper exist. | | Host/runtime boundary proof | In progress | Host smoke passes; runtime families below remain blocked. | -| Documentation/release gate | In progress | OPFS/session release gate is documented and smoke-tested; sim-config coverage and final README/docs pass still pending. | +| Documentation/release gate | In progress | OPFS/session and sim-config release gates are documented and smoke-tested; final README/docs pass still pending. | ## Blocked Runtime Families @@ -74,7 +74,7 @@ Execute these in order unless a later user request explicitly changes priority. Current next task: -- Consolidate sim-config coverage/release-gate docs and machine-readable skip reason handoff. +- Consolidate host/runtime boundary reports and final release-gate documentation. Then complete the closure: @@ -148,11 +148,14 @@ Work items: - `NON_MAIN_CLASS` - `UPSTREAM_DEMO` - Promote only configs with LinuxCNC-owned proof. +- Add short release handoff for current inventory baseline. Done via `docs/sim-configs-coverage-handoff.md`. +- Add docs smoke for inventory baseline and skip reason map. Done via `tests/docs/node/verify_sim_configs_coverage_docs.sh`. Completion criteria: - No skipped config lacks a documented reason. - No blocked runtime family is falsely promoted. +- `sim_configs_coverage_docs_node_smoke=ok` is included in the host aggregate gate. ### 5. Host/Runtime Boundary Reports diff --git a/text14.txt b/text14.txt index 72a8439..ec737ac 100644 --- a/text14.txt +++ b/text14.txt @@ -1121,3 +1121,135 @@ sim-config coverage handoff 文档/测试,明确 `ASSET_ONLY`、`L4_PYTHON_REM `L4_USER_M_PROCESS`、`NON_MAIN_CLASS`、`UPSTREAM_DEMO` 等 skip reasons 与当前 inventory 输出之间的对应关系,并把 release gate 中的 `sim_configs_wasm_node_inventory_*` 输出作为 机器可审计基线;仍不 promotion blocked runtime family,不扩大 CNC 语义边界。 + +十四、2026-06-15 继续执行记录:sim-config coverage release-gate docs + +本轮按 `text14.txt` 执行,继续推进 sim-config coverage/release-gate 文档收口。新增短版 +sim-config coverage handoff 文档与 docs smoke,明确 skip reason、inventory 输出、artifact 路径、 +blocked runtime family policy 与 release gate 的对应关系。 + +完成内容: + +- 新增 `wasm-port/docs/sim-configs-coverage-handoff.md`; +- 文档记录当前 Node/WASM inventory gate: + `SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh`; +- 文档固定当前 machine-readable baseline: + - `sim_configs_wasm_node_inventory_executed=28`; + - `sim_configs_wasm_node_inventory_passed=28`; + - `sim_configs_wasm_node_inventory_skipped=131`; + - `sim_configs_wasm_node_inventory_unexpected_fail=0`; + - `sim_configs_wasm_node_inventory_skip_ASSET_ONLY=65`; + - `sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53`; + - `sim_configs_wasm_node_inventory_skip_L4_TOOL_DB=1`; + - `sim_configs_wasm_node_inventory_skip_L4_USER_M_PROCESS=1`; + - `sim_configs_wasm_node_inventory_skip_NON_MAIN_CLASS=10`; + - `sim_configs_wasm_node_inventory_skip_UPSTREAM_DEMO=1`; +- 文档记录关键 generated artifacts: + - `summary.tsv`; + - `skip-summary.tsv`; + - `boundary-summary.tsv`; + - `blocked-dependency-summary.tsv`; + - `full-process-boundary-summary.tsv`; + - `python-remap-boundary-summary.tsv`; + - `runtime-boundary-promotion-blockers.tsv`; + - `runtime-boundary-host-readiness-rollup.tsv`; + - `runtime-boundary-opt-in-probe-dispatch-rollup.tsv`; +- 文档明确 artifact reason 与 shell metric suffix 的映射: + - `ASSET-ONLY` -> `ASSET_ONLY`; + - `L4-PYTHON-REMAP` -> `L4_PYTHON_REMAP`; + - `L4-TOOL-DB` -> `L4_TOOL_DB`; + - `L4-USER-M-PROCESS` -> `L4_USER_M_PROCESS`; + - `NON_MAIN_CLASS` -> `NON_MAIN_CLASS`; + - `UPSTREAM-DEMO` -> `UPSTREAM_DEMO`; +- 文档记录 release promotion policy: + - 必须有 LinuxCNC-owned runtime proof; + - native proof 先通过; + - Node/WASM proof 后通过; + - browser/host proof 最后通过; + - standalone CNC semantics guard 仍通过; + - generated inventory artifacts 与 docs 一致; +- 文档重申不得从 JS glue promotion: + - `L4-PYTHON-REMAP`; + - `L4-TOOL-DB`; + - `L4-USER-M-PROCESS`; +- 文档记录 sim-config coverage release gate 与 host aggregate 必须输出; +- 文档记录 blocked runtime opt-in probes 仍非当前 release gate; +- 新增 `wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.mjs`; +- 新增 `wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh`; +- docs smoke 覆盖: + - handoff 文档存在; + - inventory baseline 输出; + - skip reason map; + - artifact path; + - standalone CNC semantics guard; + - blocked runtime family; + - matrix/completion-plan/tracker/host gate 交叉引用; + - 若 `skip-summary.tsv` 已存在,则校验当前 skip reason counts; +- `wasm-port/README.md` 增加 `docs/sim-configs-coverage-handoff.md` 项目级入口; +- `wasm-port/tests/host/verify_host_smokes.sh` 纳入 + `wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh`; +- `PROJECT_COMPLETION_TRACKER.md` 同步当前完成批次与下一步 host/runtime boundary reports; +- 未新增控制按钮; +- 未执行 action-plan; +- 未解析 G-code; +- 未解释 canonical events; +- 未新增 JS CNC 语义; +- 未 promotion blocked runtime family; +- 未改变 LinuxCNC interpreter、tool、parameter、planner、kinematics、remap 或 LinuxCNC-owned + runtime semantics。 + +验证已通过: + +```bash +git diff --check +wasm-port/tools/verify_vendor_sync.sh +wasm-port/tools/verify_no_standalone_cnc_semantics.sh +SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh +wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh +wasm-port/tests/docs/node/verify_opfs_session_docs.sh +wasm-port/tests/sdk/node/verify_sdk_surface.sh +wasm-port/tests/ui/node/verify_ui_node_smokes.sh +SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh +SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh +wasm-port/tests/host/verify_host_smokes.sh +``` + +关键输出: + +```text +sim_configs_coverage_docs_node_smoke=ok +opfs_session_docs_node_smoke=ok +sdk_surface_node_smoke=ok +ini_panel_ui_shell_node_smoke=ok +ini_panel_launch_api_manifest_node_smoke=ok +ini_panel_shell_integration_manifest_node_smoke=ok +ini_panel_entry_docs_node_smoke=ok +ui_node_smokes=ok +browser_ini_opfs_smoke=ok +browser_ini_control_page_smoke=ok +browser_ini_launch_smoke=ok +browser_ini_workflow_overview_smoke=ok +browser_ini_shell_integration_workflow_smoke=ok +vendor sync up to date +standalone CNC semantics guard complete +interp_wasm_node_smoke=ok +sim_configs_wasm_node_inventory_executed=28 +sim_configs_wasm_node_inventory_passed=28 +sim_configs_wasm_node_inventory_skipped=131 +sim_configs_wasm_node_inventory_unexpected_fail=0 +sim_configs_wasm_node_inventory_skip_ASSET_ONLY=65 +sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53 +sim_configs_wasm_node_inventory_skip_L4_TOOL_DB=1 +sim_configs_wasm_node_inventory_skip_L4_USER_M_PROCESS=1 +sim_configs_wasm_node_inventory_skip_NON_MAIN_CLASS=10 +sim_configs_wasm_node_inventory_skip_UPSTREAM_DEMO=1 +host_wasm_opfs_browser_smokes=ok +``` + +下一步工作计划: + +继续推进 host/runtime boundary reports 与最终 release-gate 文档收口。下一批建议新增或收敛 +host/runtime boundary handoff 文档/测试,聚合 blocked runtime family 的 host readiness、 +promotion blockers、opt-in probe dispatch/skip evidence、native evidence acceptance gate,以及 +当前 host 为什么保持 `blocked_missing_host_runtime`;仍不运行 opt-in runtime probes,不 promotion +`L4-USER-M-PROCESS`、`L4-TOOL-DB`、`L4-PYTHON-REMAP`。 diff --git a/wasm-port/README.md b/wasm-port/README.md index d086719..876394f 100644 --- a/wasm-port/README.md +++ b/wasm-port/README.md @@ -132,6 +132,8 @@ Directory intent: Project-level OPFS/session persistence and release-gate handoff is documented in `docs/opfs-session-persistence.md`. +Sim-config inventory coverage and release-gate handoff is documented in +`docs/sim-configs-coverage-handoff.md`. The presence of this directory means the port is managed independently of the native LinuxCNC tree even though LinuxCNC remains the semantic source of truth. diff --git a/wasm-port/docs/sim-configs-coverage-handoff.md b/wasm-port/docs/sim-configs-coverage-handoff.md new file mode 100644 index 0000000..77f0e3a --- /dev/null +++ b/wasm-port/docs/sim-configs-coverage-handoff.md @@ -0,0 +1,122 @@ +# Sim-config coverage release handoff + +This document is the short release-gate handoff for +`linuxcnc/configs/sim` coverage in the LinuxCNC WASM/browser port. It points to +the detailed matrix, fixes the current machine-readable inventory baseline, and +records which skipped rows remain blocked instead of promoted. + +Detailed references: + +- `docs/sim-configs-coverage-matrix.md` +- `docs/sim-configs-completion-plan.md` +- `docs/full-process-boundary-design.md` +- `tests/wasm/node/verify_sim_configs_inventory_wasm.mjs` + +## Current inventory baseline + +The current Node/WASM inventory gate is: + +```bash +SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh +``` + +Required output: + +```text +sim_configs_wasm_node_inventory_executed=28 +sim_configs_wasm_node_inventory_passed=28 +sim_configs_wasm_node_inventory_skipped=131 +sim_configs_wasm_node_inventory_unexpected_fail=0 +sim_configs_wasm_node_inventory_skip_ASSET_ONLY=65 +sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53 +sim_configs_wasm_node_inventory_skip_L4_TOOL_DB=1 +sim_configs_wasm_node_inventory_skip_L4_USER_M_PROCESS=1 +sim_configs_wasm_node_inventory_skip_NON_MAIN_CLASS=10 +sim_configs_wasm_node_inventory_skip_UPSTREAM_DEMO=1 +sim_configs_wasm_node_inventory=ok +``` + +The generated artifact baseline is: + +- `build/wasm/sim-configs-inventory/summary.tsv` +- `build/wasm/sim-configs-inventory/skip-summary.tsv` +- `build/wasm/sim-configs-inventory/boundary-summary.tsv` +- `build/wasm/sim-configs-inventory/blocked-dependency-summary.tsv` +- `build/wasm/sim-configs-inventory/full-process-boundary-summary.tsv` +- `build/wasm/sim-configs-inventory/python-remap-boundary-summary.tsv` +- `build/wasm/sim-configs-inventory/runtime-boundary-promotion-blockers.tsv` +- `build/wasm/sim-configs-inventory/runtime-boundary-host-readiness-rollup.tsv` +- `build/wasm/sim-configs-inventory/runtime-boundary-opt-in-probe-dispatch-rollup.tsv` + +## Skip reason map + +The TSV artifacts use hyphenated reason names. The shell output uses +underscore-safe metric names. Treat these as the same baseline: + +| Artifact reason | Shell metric suffix | Count | Release decision | +| --- | --- | ---: | --- | +| `ASSET-ONLY` | `ASSET_ONLY` | 65 | Subroutine/support asset; not a standalone browser main-program target. | +| `L4-PYTHON-REMAP` | `L4_PYTHON_REMAP` | 53 | Keep inventory-only until a LinuxCNC-owned Python-remap runtime proof exists. | +| `L4-TOOL-DB` | `L4_TOOL_DB` | 1 | Keep blocked until a LinuxCNC-owned tool database process/protocol proof exists. | +| `L4-USER-M-PROCESS` | `L4_USER_M_PROCESS` | 1 | Keep blocked until a LinuxCNC-owned external user-M process state proof exists. | +| `NON_MAIN_CLASS` | `NON_MAIN_CLASS` | 10 | Covered by class representative or macro/load policy, not direct standalone promotion. | +| `UPSTREAM-DEMO` | `UPSTREAM_DEMO` | 1 | Preserved upstream demo edge; do not force pass. | + +## Promotion policy + +Rows may only move from skip/inventory to promoted coverage when all of these +are true: + +1. The row has a LinuxCNC-owned runtime proof for the behavior being promoted. +2. Native proof passes first. +3. Node/WASM proof passes after native proof. +4. Browser/host proof passes after Node/WASM proof. +5. `verify_no_standalone_cnc_semantics.sh` still passes. +6. Generated inventory artifacts and docs agree on the new status. + +Do not promote these runtime families from JavaScript glue alone: + +- `L4-PYTHON-REMAP` +- `L4-TOOL-DB` +- `L4-USER-M-PROCESS` + +## Release gate + +Use this gate when changing sim-config coverage, promotion state, or inventory +documentation: + +```bash +git diff --check +wasm-port/tools/verify_vendor_sync.sh +wasm-port/tools/verify_no_standalone_cnc_semantics.sh +SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh +wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh +wasm-port/tests/host/verify_host_smokes.sh +``` + +The host aggregate must continue to include: + +```text +sim_configs_wasm_node_inventory_executed=28 +sim_configs_wasm_node_inventory_passed=28 +sim_configs_wasm_node_inventory_skipped=131 +sim_configs_wasm_node_inventory_unexpected_fail=0 +opfs_session_docs_node_smoke=ok +sim_configs_coverage_docs_node_smoke=ok +host_wasm_opfs_browser_smokes=ok +``` + +## Blocked runtime probes + +The opt-in runtime probes remain disabled on this host unless the required +LinuxCNC runtime processes are available: + +```bash +ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh +ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh +ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh +``` + +These commands are proof gates for future work, not part of the current +release gate. The current inventory must continue to record the corresponding +families as blocked. diff --git a/wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.mjs b/wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.mjs new file mode 100644 index 0000000..c04f633 --- /dev/null +++ b/wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.mjs @@ -0,0 +1,89 @@ +import assert from "node:assert/strict"; +import { existsSync, readFileSync } from "node:fs"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const root = resolve(__dirname, "../../.."); + +function literalRegExp(text) { + return new RegExp(text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")); +} + +function parseTsv(text) { + const [headerLine, ...lines] = text.trim().split(/\r?\n/); + const headers = headerLine.split("\t"); + return lines.map((line) => { + const cells = line.split("\t"); + return Object.fromEntries(headers.map((header, index) => [header, cells[index] ?? ""])); + }); +} + +const docText = readFileSync(resolve(root, "docs/sim-configs-coverage-handoff.md"), "utf8"); +const matrixText = readFileSync(resolve(root, "docs/sim-configs-coverage-matrix.md"), "utf8"); +const completionPlanText = readFileSync(resolve(root, "docs/sim-configs-completion-plan.md"), "utf8"); +const inventoryTestText = readFileSync( + resolve(root, "tests/wasm/node/verify_sim_configs_inventory_wasm.mjs"), + "utf8", +); +const hostSmokeText = readFileSync(resolve(root, "tests/host/verify_host_smokes.sh"), "utf8"); +const trackerText = readFileSync(resolve(root, "../PROJECT_COMPLETION_TRACKER.md"), "utf8"); + +for (const phrase of [ + "Sim-config coverage release handoff", + "sim_configs_wasm_node_inventory_executed=28", + "sim_configs_wasm_node_inventory_passed=28", + "sim_configs_wasm_node_inventory_skipped=131", + "sim_configs_wasm_node_inventory_unexpected_fail=0", + "sim_configs_wasm_node_inventory_skip_ASSET_ONLY=65", + "sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53", + "sim_configs_wasm_node_inventory_skip_L4_TOOL_DB=1", + "sim_configs_wasm_node_inventory_skip_L4_USER_M_PROCESS=1", + "sim_configs_wasm_node_inventory_skip_NON_MAIN_CLASS=10", + "sim_configs_wasm_node_inventory_skip_UPSTREAM_DEMO=1", + "build/wasm/sim-configs-inventory/skip-summary.tsv", + "build/wasm/sim-configs-inventory/blocked-dependency-summary.tsv", + "verify_no_standalone_cnc_semantics.sh", + "verify_sim_configs_coverage_docs.sh", + "L4-PYTHON-REMAP", + "L4-TOOL-DB", + "L4-USER-M-PROCESS", +]) { + assert.match(docText, literalRegExp(phrase)); +} + +for (const reason of [ + "ASSET-ONLY", + "L4-PYTHON-REMAP", + "L4-TOOL-DB", + "L4-USER-M-PROCESS", + "NON_MAIN_CLASS", + "UPSTREAM-DEMO", +]) { + assert.match(matrixText, literalRegExp(reason)); + assert.match(completionPlanText, literalRegExp(reason)); + assert.match(docText, literalRegExp(reason)); +} + +assert.match(inventoryTestText, /sim_configs_wasm_node_inventory_skip_/); +assert.match(hostSmokeText, /verify_sim_configs_inventory_wasm\.sh/); +assert.match(hostSmokeText, /verify_sim_configs_coverage_docs\.sh/); +assert.match(trackerText, /sim-config coverage/); + +const skipSummaryPath = resolve(root, "build/wasm/sim-configs-inventory/skip-summary.tsv"); +if (existsSync(skipSummaryPath)) { + const rows = parseTsv(readFileSync(skipSummaryPath, "utf8")); + assert.deepEqual( + Object.fromEntries(rows.map((row) => [row.skip_or_block_reason, Number(row.count)])), + { + "ASSET-ONLY": 65, + "L4-PYTHON-REMAP": 53, + "L4-TOOL-DB": 1, + "L4-USER-M-PROCESS": 1, + NON_MAIN_CLASS: 10, + "UPSTREAM-DEMO": 1, + }, + ); +} + +console.log("sim_configs_coverage_docs_node_smoke=ok"); diff --git a/wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh b/wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh new file mode 100755 index 0000000..d14620e --- /dev/null +++ b/wasm-port/tests/docs/node/verify_sim_configs_coverage_docs.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)" + +node "$ROOT_DIR/tests/docs/node/verify_sim_configs_coverage_docs.mjs" diff --git a/wasm-port/tests/host/verify_host_smokes.sh b/wasm-port/tests/host/verify_host_smokes.sh index 1a1d440..c13cd1a 100755 --- a/wasm-port/tests/host/verify_host_smokes.sh +++ b/wasm-port/tests/host/verify_host_smokes.sh @@ -15,6 +15,7 @@ SKIP_TP_BUILD=1 "$ROOT_DIR/tests/wasm/node/verify_tp_wasm.sh" "$ROOT_DIR/tests/opfs/node/verify_file_service.sh" "$ROOT_DIR/tests/sdk/node/verify_sdk_surface.sh" "$ROOT_DIR/tests/docs/node/verify_opfs_session_docs.sh" +"$ROOT_DIR/tests/docs/node/verify_sim_configs_coverage_docs.sh" "$ROOT_DIR/tests/ui/node/verify_ui_node_smokes.sh" SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_ini_panel_browser.sh" SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 "$ROOT_DIR/tests/browser/verify_interp_browser.sh"