Skip to content
Merged
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
20 changes: 13 additions & 7 deletions docs/isolation-session/state-aware-rust.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,22 +14,24 @@ concurrency story, and error mapping.
- The Rust layer of state-aware IsolationSession in `wxc-exec.exe`, behind
the `--features isolation_session` Cargo feature. The published v0.9
surface requires no runtime experimental opt-in.
- The wire format consumed by `wxc-exec.exe` for state-aware requests
(top-level `phase` discriminator, `sandboxId`,
`isolationSession.provision` typed configuration).
- The exact state-aware phase contracts. Raw SDK and FFI JSON carries the
top-level `phase` discriminator and `sandboxId`; direct `wxc-exec.exe`
calls supply those routing values through `--operation` and
`--sandbox-id`.
- Mapping from the OS-side service's HRESULTs to the wire-format `MxcError`
codes.

### In-process callers reach the same lifecycle

The Rust SDK (`mxc-sdk`) and the C ABI over it (`mxc_ffi`), each with an
`isolation_session` feature, take the same phases and the same request JSON as
`wxc-exec`; only the entry point differs.
`isolation_session` feature, use the raw exact envelope containing `phase` and,
for non-provision operations, `sandboxId`. The executor uses the same exact
phase contracts after taking those routing values from CLI arguments.

| Phase | `wxc-exec` | In-process |
|---|---|---|
| provision / start / stop / deprovision | `wxc-exec --config …` | `mxc_sdk::run_state_aware_json`, `mxc_state_aware` |
| exec, attached to the caller's stdio | `wxc-exec --config …` | `mxc_sdk::exec_attached`, `mxc_state_aware_exec_attached` |
| provision / start / stop / deprovision | `wxc-exec --operation <phase> [--sandbox-id <id>] --config …` | `mxc_sdk::run_state_aware_json`, `mxc_state_aware` |
| exec, attached to the caller's stdio | `wxc-exec --operation exec --sandbox-id <id> --config …` | `mxc_sdk::exec_attached`, `mxc_state_aware_exec_attached` |
| exec, caller drives the pipes | *(no CLI equivalent)* | `mxc_sdk::exec_sandbox`, `mxc_state_aware_exec` |

Requirements on an in-process caller:
Expand Down Expand Up @@ -368,6 +370,10 @@ whole section for every backend. See the matrix notes above.

### Fields valid in state-aware only

These are fields in the raw exact SDK/FFI envelope. Direct `wxc-exec` calls
remove `phase` and `sandboxId` from the JSON payload and pass them as
`--operation` and `--sandbox-id`.

- `phase` — the discriminator. Required for state-aware; absent for one-shot.
- `sandboxId` — required for non-provision phases.
- `isolationSession.provision` — optional provision configuration;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -147,13 +147,15 @@ the helpers.

## Wire contract

The wire envelope is a TypeScript discriminated union over `phase`, JSON-serialised.
The Rust executor parses the same shape through its exact version/phase contract
and adapts it into a typed operation plus common runtime fields (reference §9.1).
The only `Record<string, unknown>` in the contract is
`ErrorEnvelope.details` — the escape hatch for backend-specific structured failure
information. Backend-neutral failure detail travels in the error envelope's named
fields (`operation`, `nativeCode`, `remediation`) instead.
The raw SDK/FFI wire envelope is a TypeScript discriminated union over `phase`,
JSON-serialised. Direct executor calls instead supply `phase` and `sandboxId`
as `--operation` and `--sandbox-id`; their JSON contains only the selected
phase's exact payload. Rust normalizes both transports into a typed operation
plus common runtime fields (reference §9.1). The only
`Record<string, unknown>` in the contract is `ErrorEnvelope.details` — the
escape hatch for backend-specific structured failure information.
Backend-neutral failure detail travels in the error envelope's named fields
(`operation`, `nativeCode`, `remediation`) instead.

```typescript
interface OneShotRequest {
Expand Down
123 changes: 82 additions & 41 deletions docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -597,12 +597,12 @@ omits it.

## 7. Wire contract

The wire contract is a typed, JSON-serialised envelope shared by the TypeScript SDK,
`mxc_ffi`, and the executor CLI. The SDK passes the envelope to `mxc_ffi`; direct CLI
callers can provide the same envelope through `--config-base64`. Rust parses both paths
into the same request types (§9.1). The only open content is at the leaves of
`ErrorEnvelope.details`; every other field, including the error envelope's named
structured fields, is statically typed.
The raw exact wire contract is a typed, JSON-serialised envelope shared by the
TypeScript SDK and `mxc_ffi`. Direct executor calls carry lifecycle routing in CLI
arguments while retaining the same phase-specific exact contracts internally. Rust
normalizes both paths into the same request types (§9.1). The only open content is at
Comment thread
MGudgin marked this conversation as resolved.
Resolved
the leaves of `ErrorEnvelope.details`; every other field, including the error
envelope's named structured fields, is statically typed.

### 7.1 Request envelope

Expand Down Expand Up @@ -682,6 +682,30 @@ State-aware-only fields:
| `phase` | `Phase` member | Yes | Discriminator. Absence means a one-shot request. |
| `process` | `ProcessConfig` | Required for `exec`; absent otherwise. | Cross-backend execution fields. |

#### `wxc-exec` lifecycle transport

Raw exact SDK and FFI calls retain `phase` and `sandboxId` in JSON. Direct
`wxc-exec` lifecycle calls instead remove those routing fields from the supplied JSON
and pass them as command-line arguments:

Comment thread
MGudgin marked this conversation as resolved.
Resolved
```text
wxc-exec.exe policy.json --operation provision
wxc-exec.exe policy.json --operation start --sandbox-id iso:abc
wxc-exec.exe policy.json --operation exec --sandbox-id iso:abc -- command arg
wxc-exec.exe policy.json --operation stop --sandbox-id iso:abc
wxc-exec.exe policy.json --operation deprovision --sandbox-id iso:abc
```

Provision JSON still contains `containment`; later operations route from the
`--sandbox-id` prefix. Supplying `phase` or `sandboxId` in CLI JSON is rejected rather
than overriding the command-line routing. Without `--operation`, `wxc-exec` accepts
only one-shot JSON.

`--operation` cannot be combined with delete or maintenance routing, including
`--delete`, its `--containername` option, setup modes, probing, force-reclaim, or
audit modes. Lifecycle identity comes only from `--sandbox-id`; conflicting options
are rejected rather than ignored.

Cross-cutting fields available to state-aware (state-aware-only at top level — backends
declare which phases honor them, see §10.3):

Expand Down Expand Up @@ -740,9 +764,9 @@ the executor CLI represents the same outcomes through stdout, stderr, and its ex

| Phase / outcome | stdout | stderr |
|---|---|---|
| Non-exec (provision, start, stop, deprovision), success or failure | Single JSON envelope (`{result}` or `{error}`) | MXC diagnostic output (when `--debug`); empty otherwise |
| Exec, dispatch succeeded | Script's stdout | Script's stderr; MXC diagnostic also lands here when `--debug` is passed |
| Exec, dispatch failed | Single JSON envelope (`{error}`) | MXC diagnostic output (when `--debug`); empty otherwise |
| Non-exec (provision, start, stop, deprovision), success or failure | Single JSON envelope (`{result}` or `{error}`) | Buffered MXC diagnostics and warnings, when produced; may be empty |
| Exec, dispatch succeeded | Script's stdout | Script's stderr plus buffered MXC diagnostics and warnings, when produced |
| Exec, dispatch failed | Single JSON envelope (`{error}`) | Buffered MXC diagnostics and warnings, when produced; may be empty |

`stdout` is authoritative: for non-exec phases it carries exactly one envelope; for exec
it carries either the script's output (success) or exactly one envelope (failure).
Expand All @@ -751,28 +775,27 @@ state-aware mode so `stdout` remains parseable without sentinels. (One-shot disp
keeps its existing `stdout` logger behaviour — the stricter routing applies to
state-aware only.)

Configuration parse-phase failures that occur **after** the request is
discriminated as state-aware (i.e. the `phase` field was recognized) follow the
state-aware contract: the typed `{error}` envelope is the only primary output,
while the human-readable actionable parse diagnostic is written only to
configured auxiliary sinks (`--log-file` and the Windows diagnostic console). It
is not duplicated to the logger's primary console/buffer output, so such a parse
failure does not add stderr noise even with `--debug`. Dispatch-time failures,
including typed per-backend configuration errors, use the same auxiliary-only
diagnostic routing before the executor emits their typed `{error}` envelope.

CLI failures that occur **before** discrimination is possible — malformed base64,
non-UTF-8 bytes, or JSON so malformed that the `phase` field cannot be read —
cannot be attributed to the state-aware path. The diagnostic is written to the
primary output (stderr) and **no**
`{error}` envelope is emitted. Callers that require an envelope even for
unparseable input should validate that the payload is well-formed JSON before
invoking `wxc-exec`.

For exec specifically, MXC diagnostic output mixes with the script's own stderr when
`--debug` is passed. This is a small amount of pre- and post-dispatch noise; consumers
wanting clean separation should use `--log-file <path>` instead, which routes diagnostic
output to a file and leaves stderr as pure script content.
When `--operation` is present, the executor selects the lifecycle contract before
reading or decoding the configuration source. Every failure from that point onward —
an unreadable file, malformed base64, non-UTF-8 bytes, malformed JSON, an invalid
version, exact-contract rejection, or dispatch failure — emits a typed `{error}`
envelope as the only primary output. The human-readable diagnostic is written only to
the buffered diagnostic channel and may be flushed to stderr; configured auxiliary
sinks (`--log-file` and the Windows diagnostic console) may receive the same
diagnostic. The rejection is recorded through the same `ConfigRejected` audit path.
Diagnostics are never duplicated to stdout, and lifecycle stderr is not gated on
`--debug`.

Without `--operation`, `wxc-exec` accepts only one-shot requests. Input-source and
pre-parse failures on that path retain the legacy primary diagnostic on stderr and do
not emit a lifecycle envelope. Raw SDK and FFI lifecycle calls do not use this CLI
stream protocol; they return their status and error data through their binding result
surfaces.

For exec specifically, buffered MXC diagnostic output may mix with the script's own
stderr whether or not `--debug` is passed; `--debug` may cause additional diagnostics.
`--log-file <path>` preserves a file copy but does not suppress the stderr flush.
Consumers should treat stdout as the protocol channel and stderr as informational.

**Envelope shape:**

Expand Down Expand Up @@ -850,9 +873,11 @@ codes.

### 7.4 Worked example: IsolationSession end-to-end

A complete state-aware lifecycle, threading TS call → JSON the SDK serialises and passes
to the executor via `--config-base64` → Rust trait method that dispatches → response
shape, across all five phases.
A complete state-aware lifecycle, threading TS call → exact JSON the SDK passes through
`mxc_ffi` → Rust trait method that dispatches → response shape, across all five phases.
Each phase also identifies the equivalent direct `wxc-exec` routing; that transport
removes `phase` and `sandboxId` from the shown exact JSON and supplies them as CLI
arguments.

#### Phase 1 — provision

Expand All @@ -873,15 +898,17 @@ const { sandboxId } = await provisionSandbox(
```json
{
"version": "0.9.0-alpha",
"containment": "isolation_session",
"phase": "provision",
"containment": "isolation_session",
Comment thread
MGudgin marked this conversation as resolved.
Resolved
"network": {
"egress": { "default": "allow" },
"ingress": { "default": "allow", "hostLoopback": "allow" }
}
}
```

Direct executor routing: remove `phase` and pass `--operation provision`.

```rust
// Exact adaptation carries the all-allow network policy on the request. After
// checked binding and backend validation, the dispatcher calls:
Expand Down Expand Up @@ -917,6 +944,9 @@ await startSandbox(
}
```

Direct executor routing: remove `phase` and `sandboxId`, then pass
`--operation start --sandbox-id <id>`.

```rust
// `start` carries no per-phase config for this backend — its StartConfig is
// `()`, so the envelope above has no backend-specific section and the
Expand Down Expand Up @@ -952,6 +982,9 @@ const r = await execInSandboxAsync(
}
```

Direct executor routing: remove `phase` and `sandboxId`, then pass
`--operation exec --sandbox-id <id>`.

```rust
// Parser populates request.script_code = "echo hello", request.script_timeout =
// 5000 from the wire-format `process` block (same path as one-shot). The
Expand Down Expand Up @@ -982,6 +1015,9 @@ await stopSandbox(sandboxId, {});
}
```

Direct executor routing: remove `phase` and `sandboxId`, then pass
`--operation stop --sandbox-id <id>`.

```rust
backend.stop("iso:eyJ2ZXJzaW9uIjoxLCJhZ2VudFVzZXJOYW1lIjoiX2lzb19hYmNfMTIzIn0", &request, /* config */ None)
// returns Ok(StopResult { metadata: None })
Expand All @@ -1005,6 +1041,9 @@ await deprovisionSandbox(sandboxId, {});
}
```

Direct executor routing: remove `phase` and `sandboxId`, then pass
`--operation deprovision --sandbox-id <id>`.

```rust
backend.deprovision("iso:eyJ2ZXJzaW9uIjoxLCJhZ2VudFVzZXJOYW1lIjoiX2lzb19hYmNfMTIzIn0", &request, /* config */ None)
// returns Ok(DeprovisionResult { metadata: None })
Expand All @@ -1022,12 +1061,14 @@ section when serialising state-aware calls — consumers write `appId` directly
fields (`filesystem` / `network` / `runtimeConfig` / `ui`) on a per-(backend, phase) Config map directly
to top-level wire fields — they are already wire-format-aligned in the Config, so the
SDK passes them through unchanged. Cross-backend exec fields (`commandLine`, `cwd`,
`env`, `timeout`) flow through the top-level `process` block. The typed SDK requires `commandLine`. The executor CLI can complete an `exec`
template from arguments after `--`; it sets `process.commandLine` before parsing.
Trailing commands are rejected for every non-exec phase. The Node SDK receives
owned response data and native process streams through `mxc_ffi`. Responses unwrap
any `result` envelope at the SDK boundary so the caller sees a plain `ProvisionResult` /
`StartResult` / `ExecResult` / `StopResult` / `DeprovisionResult`.
`env`, `timeout`) flow through the top-level `process` block. The typed SDK requires
`commandLine`. The executor CLI supplies operation and existing sandbox identity through
`--operation` and `--sandbox-id`; it can complete an `exec` template from arguments
after `--` by setting `process.commandLine` before parsing. Trailing commands are
rejected for every non-exec operation. The Node SDK receives owned response data and
native process streams through `mxc_ffi`. Responses unwrap any `result` envelope at the
SDK boundary so the caller sees a plain `ProvisionResult` / `StartResult` /
`ExecResult` / `StopResult` / `DeprovisionResult`.

## 8. Error model

Expand Down
19 changes: 16 additions & 3 deletions docs/windows-sandbox/windows-sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,11 @@ reuses a warm VM.

## State-Aware Lifecycle

The state-aware surface keeps the VM alive across separate `wxc-exec` phase
processes. The backend is inferred from the `wsb:` sandbox ID after provision.
The state-aware surface keeps the VM alive across separate `wxc-exec
--operation` processes. Raw SDK/FFI requests carry `phase` and, after
provision, `sandboxId` in JSON. Direct executor calls omit those routing fields
from JSON and pass them as `--operation` and `--sandbox-id`. The backend is
inferred from the `wsb:` sandbox ID after provision.

| Phase | Behaviour |
|---|---|
Expand Down Expand Up @@ -108,6 +111,8 @@ There is no idle watchdog. A started state-aware sandbox remains active until

### State-aware provision

The raw SDK/FFI provision request is:

```json
{
"version": "0.10.0-alpha",
Expand All @@ -120,7 +125,15 @@ There is no idle watchdog. A started state-aware sandbox remains active until
}
```

Subsequent phases use the returned `sandboxId`.
For a direct executor call, remove `phase` from that JSON and invoke:

```text
wxc-exec.exe config.json --operation provision
```

Subsequent raw SDK/FFI phases carry the returned `sandboxId` in JSON. Direct
executor calls remove `phase` and `sandboxId` from JSON and pass
`--operation <phase> --sandbox-id <id>`.

The legacy `windowsSandbox.idleTimeoutMs`, `idleTimeout`, and
`daemonPipeName` fields remain parseable for schema compatibility but do not
Expand Down
19 changes: 11 additions & 8 deletions docs/wsl/wslc-state-aware.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,11 @@ deserialization DTO.

## Sandbox IDs

`provision` mints an id of the form `wslc:<32 lowercase hex>` (`wslc:` + a UUID simple form). All
post-provision phases (`start` / `exec` / `stop` / `deprovision`) carry this id in `sandboxId`; the
dispatcher derives the backend from the `wslc:` prefix (they do **not** repeat `containment`).
`provision` mints an id of the form `wslc:<32 lowercase hex>` (`wslc:` + a UUID simple form).
Raw SDK/FFI requests carry this id in `sandboxId` for every post-provision phase
(`start` / `exec` / `stop` / `deprovision`). Direct `wxc-exec` calls omit it from JSON and pass it
as `--sandbox-id`; the dispatcher derives the backend from the `wslc:` prefix (later operations do
**not** repeat `containment`).

## Phase → WSLc SDK mapping

Expand Down Expand Up @@ -230,13 +232,14 @@ run individually or in an arbitrary order:
`deprovision` → `not_provisioned`).
- **The id must be threaded through.** `provision` returns the real `wslc:<32-hex>` id on stdout
(`result.sandboxId`). The post-provision fixtures (`_start`, `_stop`, `_deprovision`, and every
`_exec_*`) ship with a literal **`{{SANDBOX_ID}}` placeholder** that must be replaced with that
minted id before the config is passed to `wxc-exec`. Running a post-provision fixture as-is sends
the literal placeholder and fails validation.
`_exec_*`) ship with a literal **`{{SANDBOX_ID}}` placeholder**. These fixtures use the raw exact
SDK/FFI envelope shape; the harness replaces the placeholder before converting the request to
direct executor CLI form.

`run_wslc_state_aware_tests.ps1` handles both concerns automatically (it drives the phases in order
and does the `{{SANDBOX_ID}}` substitution from each provision's output), which is why the fixtures
should be exercised **through the harness**, not by pointing `wxc-exec --config` at them directly.
and does the `{{SANDBOX_ID}}` substitution from each provision's output). It then removes `phase`
and `sandboxId` from the JSON and passes them as `--operation` and `--sandbox-id`. Exercise these
fixtures **through the harness**, not by pointing `wxc-exec --config` at them directly.

## Known limitations

Expand Down
Loading
Loading