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, createProjectReleaseGateActionPlan() to derive pending gate commands, the next command, display rows, and a shell script from that matrix, and createProjectReleaseReadinessReport() for a machine-readable release readiness report covering the same manifest, result matrix, action plan, 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(). Artifact validation requires the embedded gate manifest, result matrix, and action plan to be ready, so stale release JSON cannot pass the executable artifact gate. 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.