# 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 `text14.txt` are historical context. Current continuation records are in `../text15.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, `createProjectReleaseGateExecutionManifest()` to package each gate command, expected output, observed-output evidence, and passed/unknown status, and `createProjectReleaseReadinessReport()` for a machine-readable release readiness report covering the same manifest, execution 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, execution manifest, result matrix, and action plan to be ready, so stale release JSON cannot pass the executable artifact gate. `createProjectReleaseReadinessArtifactValidationSummaryViewModel()` turns the validation into stable dashboard rows without reinterpreting artifact fields. `createProjectReleaseReadinessArtifactValidationActionPlan()` turns a blocked artifact validation into the project release gate and artifact validation commands to run next, plus the missing evidence rows. `createProjectReleaseReadinessArtifactJsonWorkflow()` is the one-call non-throwing JSON text workflow for dashboards that need parse, validation, summary, and action-plan output from the readiness artifact. `loadProjectReleaseReadinessArtifactUrlWorkflow()` provides the same SDK-side workflow from an artifact URL and caller-provided fetch implementation, including fetch status and next-command output. `createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel()` turns that SDK URL workflow into stable dashboard rows and status text. `createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()` turns blocked URL workflows into ordered input, fetch, and command actions for CI tooling. 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. That URL workflow includes a validation summary view-model and can be summarized with `getWorkflowOverviewReleaseReadinessArtifactUrlWorkflowSummaryViewModel()`. 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: ```bash wasm-port/tests/host/verify_project_release_gate.sh ``` It executes the same minimum release validation commands: ```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_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/sdk/node/verify_project_release_artifact_url_workflow.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: ```text project_release_readiness_artifact=... project_release_readiness_artifact_node_smoke=ok ``` A passing aggregate ends with: ```text host_wasm_opfs_browser_smokes=ok project_release_gate=ok ``` ## Expected baseline outputs The current sim-config inventory release baseline is: ```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 ``` The expected docs and SDK smoke outputs include: ```text 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 project_release_artifact_url_workflow_node_smoke=ok ``` The expected browser INI panel smoke outputs include: ```text 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.