cnc_wams/wasm-port/docs/project-release-handoff.md

Project release handoff

This is the short project-level handoff for the current LinuxCNC WASM/browser port scope. It points a new maintainer to the supported workflow surfaces, the required release gates, and the boundaries that must remain blocked until real LinuxCNC-owned runtime proof exists.

Start here

Use these documents as the current handoff set:

• README.md for the workspace layout and release validation commands.
• docs/panel-entry.md for browser/UI entry points and shell handoff helpers.
• runtime/sdk/README.md for stable SDK imports from runtime/sdk/src/index.js.
• docs/opfs-session-persistence.md for OPFS/session persistence scope.
• docs/sim-configs-coverage-handoff.md for sim-config inventory status.
• docs/host-runtime-boundary-handoff.md for blocked runtime families.
• docs/source-reuse-map.md and docs/drift-report.md for LinuxCNC source reuse and non-drift rules.
• ../PROJECT_COMPLETION_TRACKER.md for project-level acceptance tracking.

Old turn logs text1.txt through text13.txt are historical context. Current continuation records are in ../text14.txt.

Supported current workflows

• INI panel launch, edit/run page, read-only control page, workflow overview, and external shell handoff are exposed from runtime/ui/ini-panel/.
• External shells should use the read-only helpers documented in docs/panel-entry.md, including workflow overview embedding mount DOM contract/readiness/renderer/wrapper helpers.
• SDK callers should import stable helpers from runtime/sdk/src/index.js, including createIniPanelShellApiSurfaceInventory() for API discovery and createIniPanelShellSessionReadinessWorkflowReport() when they need machine-readable session readiness phase and missing reasons. The workflow overview exposes the API surface inventory as a read-only summary row.
• CI dashboards and external SDK callers can use createProjectReleaseGateManifest() to discover required gate commands and expected smoke outputs, createProjectReleaseGateResultMatrix() to map observed outputs onto passed/unknown gate rows, and createProjectReleaseReadinessReport() for a machine-readable release readiness report covering the same manifest, result matrix, sim-config inventory baseline, and blocked runtime families. createProjectReleaseReadinessSummaryViewModel() turns that report into stable status text and rows for dashboards. The report helper is evidence driven and only reports ready: true when the caller supplies release gate evidence such as project_release_gate=ok. The project release gate writes the same report to build/project-release-readiness.json and validates it with verify_project_release_readiness_artifact.sh. External tools can load that artifact with parseProjectReleaseReadinessArtifactJson() and validate it with createProjectReleaseReadinessArtifactValidation(). Browser shells can also pass the JSON to linuxCncIniPanelWorkflowOverviewApi.validateWorkflowOverviewReleaseReadinessArtifactJson() through the workflow overview iframe and receive stable validation rows. They can also call linuxCncIniPanelWorkflowOverviewApi.loadWorkflowOverviewReleaseReadinessArtifactUrl() to fetch the artifact URL, validate it, and optionally mount the resulting read-only render state. When the outer shell needs DOM output, the workflow overview iframe also exposes display, render-state, DOM readiness, renderer, and mount helpers for the same release readiness artifact validation.
• OPFS/session callers can use createMachineSessionPersistenceSummary() or linuxCncIniPanelApi.getMachineSessionPersistenceSummary() to inspect machine files, session snapshot, session readiness, session load, readonly status, and shell handoff readiness as stable rows. Shell handoff workflow summaries can include that report as the persistence-summary row beside the API surface inventory row, and launch/workflow-overview APIs expose the same helper for external shells. The summary also has display and render-state helpers for caller-owned DOM.
• OPFS/session persistence is host-side storage glue. Parameter and tool-table behavior still comes from the LinuxCNC-backed interpreter SDK calls.
• Sim-config inventory promotion remains evidence-driven and must keep unexpected_fail=0.

Required release gates

Run the single project release gate before claiming the current scope is release-ready:

wasm-port/tests/host/verify_project_release_gate.sh

It executes the same minimum release validation commands:

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_interp_wasm.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_ini_panel_browser.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_release_artifact_url_workflow_browser.sh
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
wasm-port/tests/host/verify_host_smokes.sh

The host aggregate gate includes SDK, OPFS, docs, UI Node, WASM Node, and browser smoke coverage. The project release gate then writes and verifies a machine-readable release readiness artifact:

project_release_readiness_artifact=...
project_release_readiness_artifact_node_smoke=ok

A passing aggregate ends with:

host_wasm_opfs_browser_smokes=ok
project_release_gate=ok

Expected baseline outputs

The current sim-config inventory release baseline is:

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

The expected docs and SDK smoke outputs include:

project_release_handoff_docs_node_smoke=ok
opfs_session_docs_node_smoke=ok
sim_configs_coverage_docs_node_smoke=ok
host_runtime_boundary_docs_node_smoke=ok
sdk_surface_node_smoke=ok

The expected browser INI panel smoke outputs include:

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
browser_release_artifact_url_workflow_smoke=ok

Blocked runtime families

These runtime families remain blocked:

• L4-USER-M-PROCESS
• L4-TOOL-DB
• L4-PYTHON-REMAP

Do not promote them from skipped/blocked state without LinuxCNC-owned native runtime proof followed by Node/WASM and browser/host validation. The opt-in runtime probes are documented in docs/host-runtime-boundary-handoff.md; they must not be run on hosts that do not provide the required LinuxCNC runtime.

Acceptance checklist

• git diff --check passes.
• Vendor sync and standalone CNC semantic guards pass.
• Interpreter WASM Node smoke passes.
• Sim-config inventory has unexpected_fail=0.
• UI Node smoke passes.
• Browser INI panel smoke passes.
• Release artifact URL browser workflow smoke passes.
• Host aggregate smoke passes.
• verify_project_release_gate.sh passes.
• SDK exports match runtime/sdk/README.md.
• docs/panel-entry.md documents the external shell workflow surface.
• OPFS/session, sim-config coverage, host/runtime boundary, source reuse, and drift docs all point to the current validation gates.
• Blocked runtime families remain documented and are not falsely promoted.

Next maintainer rule

Add new CNC behavior only by reusing vendored LinuxCNC source or a documented runtime-edge adapter. JavaScript may stage files, mount UI state, manage OPFS, load WASM modules, and call C ABI functions; it must not implement G-code, tool, parameter, planner, kinematics, remap, or canonical motion semantics.