Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/backends/wslc/wslc-state-aware.md
Original file line number Diff line number Diff line change
Expand Up @@ -703,6 +703,10 @@ reported, so a phase failure reaches the SDK with the same code that
create-and-run execution returns for the same host condition. A caller branches on the code
without matching the message.

When a WSLc SDK call fails, including in an exec that has already started, the
error envelope also carries the SDK function name in `operation`, and its HRESULT
in `nativeCode` when the call returned one.

`ErrKind` is additive: a kind a client does not recognize decodes to
`ErrKind::Unknown` and maps to `backend_error`, so a daemon from a newer
install degrades to the previous behavior instead of failing the decode. Adding
Expand All @@ -727,8 +731,8 @@ success for a request it only partly honoured β€” a sandbox that is quietly not
what was asked for. A refusal the caller can see is better.

Upgrading an install that may have a live daemon therefore means stopping the
old one first. `PROTOCOL_VERSION` is **9** as of the addition of exec stdin
(the `stdin` flag on `exec` and the `exec_stdin` request).
old one first. `PROTOCOL_VERSION` is **10** as of the addition of optional WSLc
SDK failure detail to lifecycle error responses and exec error frames.

## Daemon idle-timeout env overrides

Expand Down
8 changes: 5 additions & 3 deletions docs/development/architecture/container-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -685,9 +685,11 @@ The three optional named fields carry structured failure detail. `operation` and
| `nativeCode` | The underlying platform status as a string. An HRESULT such as `0x80070490` on Windows; the field is platform-neutral, so another backend can carry an errno or equivalent. |
| `remediation` | An actionable "how to fix it" hint, when the failure has one. |

**Availability.** These fields are currently populated only by **IsolationSession
state-aware** operations. Other backends may adopt them β€” treat all three as optional on
every backend, and branch program logic on `code` first.
**Availability.** IsolationSession container lifecycle operations may populate all
three fields. WSLc container lifecycle operations populate `operation` for failures
reported by the WSLc SDK and `nativeCode` when the SDK supplies an HRESULT. Other
backends may adopt them β€” treat all three as optional on every backend, and branch
program logic on `code` first.

**Stability.** Unlike `code`, which is a closed and versioned enum, the *values* of `operation` and `nativeCode` are **best-effort diagnostics and may change without a schema version bump**. They are derived from the underlying platform API β€” for IsolationSession, from the projected WinRT class and method names β€” which MXC does not own and cannot version. Consumers should aggregate on them for telemetry and log them for diagnosis, but branch program logic on `code`, and should not treat a particular `operation` value as a guarantee. (MXC's own end-to-end tests do pin exact values; that is deliberate β€” they verify MXC's mapping, and move with it in the same change.)

Expand Down
Loading
Loading