187 lines
8.0 KiB
Markdown
187 lines
8.0 KiB
Markdown
# 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:
|
|
|
|
```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/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
|
|
```
|
|
|
|
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.
|