[WSLC] Encapsulate backend errors in a typed enum for the Rust SDK

[Soham Das (SohamDas2021)]

📖 Description

---

Summary

WSLc built every failure as a free-text ScriptResponse via ScriptResponse::error, which leaves failure_phase at its None default. Since mxc_engine::dispatch::map_spawn_error discriminates on exactly that field, all 54 WSLc error sites reached the Rust SDK as an opaque backend_error — a caller could only tell a missing WSL host from a rejected policy by parsing the message.

This adds wslc_common::error::WslcError, mirroring the existing windows_sandbox_lifecycle::error::OneShotError pattern, and routes the WSLc error sites through it:

Variant	Phase	SDK code
Unavailable	BackendUnavailable	backend_unavailable
Rejected	Rejected	policy_validation
Sdk / Host	LaunchFailed	backend_error
Runtime	PostLaunchFailed	backend_error

map_spawn_error gains the Rejected → policy_validation arm. No new ErrorCode variants, so the closed cross-surface set (Rust → engine → C ABI → C#) is untouched and the parity gate is unaffected.

No user-visible message changes.Display reproduces each message verbatim; a unit test transcribes main's old sdk_error body as an oracle and asserts byte-identical rendering. The only behavioral change is that failure_phase now carries a real value instead of None — nothing in tests/, sdk/, or scripts/ asserts on it, and the only production readers are map_spawn_error and telemetry's classify_failure (total over the enum).

Validation

• cargo fmt --all -- --check, cargo clippy -p wslc_common -p mxc_engine --all-targets -- -D warnings — clean
• cargo test --workspace — 3,912 passed / 0 failed
• wslc_common with link-wslcsdk — 188/188, including 4 new error::tests
• Live WSLc E2E on a WSL2 host (run_wslc_all_tests.ps1): 54/57 state-aware + 24/25 one-shot — byte-identical to a pristine main baseline built and run on the same host. All 110 PASS/FAIL lines match exactly.

The 3 E2E failures are pre-existing on main and are not caused by this PR: they come from the WSLc network.proxy gate in config_parser.rs (a file this PR does not touch), fail during config parsing before any WSLc dispatch, and are fixed by #1042. Once #1042 lands and this rebases onto it, the suite is 57/57 + 25/25.

Closes#794

📋 Issue Type

• Bug fix
• Feature
• Task

---

GitHub Actions runs the PR validation build automatically. The ADO pipeline
(MXC-PR-Build) is the Azure version of the PR pipeline, kept in parity with the GitHub
Actions build; it runs on merge to main, and Microsoft reviewers with write access can trigger it
on a PR with /azp run. See docs/pull-requests.md.

If the dependency-feed-check check fails on a new dependency, the crate must be added to
the feed before the PR can pass. See docs/pull-requests.md
for the steps.

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Adds typed WSLc failure classification so Rust SDK callers can distinguish unavailable backends and rejected policies.

Changes:

• Introduces WslcError with lifecycle-phase mapping.
• Migrates WSLc error construction while preserving messages.
• Maps rejected spawn failures to policy validation errors.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/core/mxc_engine/src/dispatch.rs	Maps rejected failures to PolicyValidation.
src/backends/wslc/common/src/error.rs	Defines typed WSLc errors.
src/backends/wslc/common/src/lib.rs	Exposes the error module.
src/backends/wslc/common/src/container_steps.rs	Converts shared helper failures.
src/backends/wslc/common/src/wsl_container_runner.rs	Converts one-shot runner failures.

Suppressed comments (1)

src/backends/wslc/common/src/error.rs:67

• Sdk and Host do not always occur during launch. wait_for_process calls sdk_error for WslcGetProcessExitEvent/WslcGetProcessExitCode after the container process is live, and StartedContainer::wait_for_exit maps a COM-entry failure to Host; those failures are therefore incorrectly reported as LaunchFailed instead of PostLaunchFailed. Split launch-time and runtime SDK/host errors, or carry the phase at construction.

 // The SDK call or host bring-up failed; generally worth retrying.
WslcError::Sdk { .. } | WslcError::Host(_) => FailurePhase::LaunchFailed,
// The container was up but the run broke.
WslcError::Runtime(_) => FailurePhase::PostLaunchFailed,

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Soham Das (SohamDas2021)]

Folded into #843

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

src/backends/wslc/common/src/container_steps.rs:676

• This phase is dropped on the state-aware path. load_sdk_checked is called by wslc/daemon/src/session_manager.rs:357, but that file's sr_err converts the response to anyhow!(resp.error_message) and every such failure becomes WorkerError::Backend/ErrKind::Backend. Consequently a missing SDK or prerequisite still reaches run_state_aware_json as backend_error, so the advertised typed distinction only works for one-shot/streaming. Preserve this classification through WorkerError, ErrKind, and map_daemon_error rather than erasing it at the daemon boundary.

 let sdk = WslcSdk::load().map_err(|e| WslcError::Unavailable(e).into_response())?;
let mut missing = WslcComponentFlags::WSLC_COMPONENT_FLAG_NONE;
let hr = sdk.WslcGetMissingComponents(&mut missing);
if hr != S_OK {
return Err(sdk_error("WslcGetMissingComponents failed", hr, ""));
}
if missing.any_missing() {
return Err(WslcError::Unavailable(wslc_prerequisite_error(missing)).into_response());

src/backends/wslc/common/src/error.rs:67

• Classifying by error source rather than lifecycle point makes several new phases incorrect. For example, wait_for_process calls sdk_error for WslcGetProcessExitEvent and WslcGetProcessExitCode after the process exists (wsl_container_runner.rs:1106,1198), while adjacent wait failures correctly use Runtime; state-aware exec has the same pattern in container_steps.rs:945,1035. Those SDK failures are now reported as LaunchFailed instead of PostLaunchFailed. Split SDK errors into launch/runtime variants (or pass the phase at construction) and classify each call site according to whether process creation already succeeded.

 // The SDK call or host bring-up failed; generally worth retrying.
WslcError::Sdk { .. } | WslcError::Host(_) => FailurePhase::LaunchFailed,
// The container was up but the run broke.
WslcError::Runtime(_) => FailurePhase::PostLaunchFailed,