Add backend support probe API design & discussion doc

[Huzaifa Danish (huzaifa-d)]

• I have signed the Contributor License Agreement.
• This pull request is related to an issue.
• If this PR changes build commands, project architecture, or key conventions, I have updated .github/copilot-instructions.md.

---

Summary

Adds a design & discussion document for a proposed read-only Rust available_backends() host-capability probe API.

Changes:

• Defines the proposed API and isolation-tier semantics.
• Documents existing detection methods and gaps.
• Outlines testing and follow-up work.

Details

File	Description
docs/backend-support-probe-api-plan.md	Adds the backend-support probe API design.

Review details

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 a discussion document proposing a Rust API for probing available containment backends.

Changes:

• Defines the proposed API and isolation-tier semantics.
• Documents existing detection methods and gaps.
• Outlines testing and follow-up work.

Show a summary per file

File	Description
docs/backend-support-probe-api-plan.md	Adds the backend-support probe API design.

Review details

Comments suppressed due to low confidence (3)

docs/backend-support-probe-api-plan.md:119

• There is no IsoSessionApp.dll resolvability gate in the TypeScript platform probe to port; isIsoSessionSupported() only checks CurrentBuild == 26300 and UBR >= 8553 (sdk/node/src/platform.ts:96-105). The Rust work must add the DLL check rather than copy it from TypeScript.

2. `isolation_session` - port the build-number + `IsoSessionApp.dll` gate from TypeScript to Rust.

docs/backend-support-probe-api-plan.md:110

• These PATH-based probes are synchronous and the plan specifies no deadline. A broken or wrapper-provided bwrap/lxc-ls can therefore block available_backends() indefinitely even though the API is intended for startup discovery. Require a bounded timeout and add a test that a hung probe is treated as unavailable.

- On Linux, `bubblewrap` and `lxc` each appear when their check passes (`bwrap --version` / `lxc-ls --version`).

docs/backend-support-probe-api-plan.md:141

• Remove the duplicated space.

The named tier is  the strongest isolation the host is capable

• Files reviewed: 1/1 changed files
• Comments generated: 6
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (9)

docs/backend-support-probe-api-plan.md:94

• The build condition does not match the TypeScript gate this plan proposes to port. isIsoSessionSupported() currently accepts only major === 26300 && minor >= 8553 and explicitly rejects other major builds (sdk/node/src/platform.ts:102-104), whereas >= 26300.8553 includes all later builds. Specify the intended compatibility rule consistently before implementing the Rust detector.

| `isolation_session` | build ≥ 26300.8553 **and** `IsoSessionApp.dll` resolvable **and** feature compiled | build gate lives **only in the TypeScript SDK** | wrong OS builds falsely pass |

docs/backend-support-probe-api-plan.md:65

• Fix the merged words in “checkwhich.”

| `windows_sandbox` | `isWindowsSandboxAvailable()` runs `dism /online /get-featureinfo `<br>`/featurename:Containers-DisposableClientVM ` and looks for `State : Enabled`<br>if DISM throws (usually non-elevated) it falls back to<br>`fs.existsSync(%SystemRoot%\\System32\\WindowsSandbox.exe)`; result cached. | TypeScript SDK | `dism /online` needs elevation, so a non-elevated caller can't tell *disabled* from<br>*no permission* and drops to the exe-existence checkwhich proves the feature is installed,<br>not that a sandbox VM can boot. (Will move to Rust) |

docs/backend-support-probe-api-plan.md:107

• Porting only the Windows Sandbox and LXC checks cannot make the function cover “every backend”: this same document leaves Isolation Session, MicroVM, and Hyperlight unreported until separate detectors land (§4.1 and lines 128-129). Limit this step to the currently probe-ready backends or include all missing-detector work in it.

| 1. Consolidate detectors in Rust | Port the two TypeScript-only checks (`windows_sandbox` DISM/feature check, `lxc-ls`) into Rust<br>so `available_backends()` covers every backend. | Each backend has exactly one detector. |

docs/backend-support-probe-api-plan.md:137

• There is no IsoSessionApp.dll gate in TypeScript to port—the current TypeScript check only queries CurrentBuild/UBR (sdk/node/src/platform.ts:67-104). State that DLL resolvability and compile-feature detection are new Rust checks so the follow-up scope is accurate.

2. `isolation_session` - port the build-number + `IsoSessionApp.dll` gate from TypeScript to Rust.

docs/backend-support-probe-api-plan.md:27

• The signature does not enforce the canonical-name contract: backend is a public String (and tier is another String below), so Rust consumers cannot match exhaustively and future construction can serialize invalid names despite output tests. Use serde-renamed enums—ideally a concrete-backend enum plus a tier enum—and convert to strings only at the wire boundary.

    pub backend: String,
    /// The highest-isolation tier the host supports for this backend, if the
    /// backend has a tier ladder. `None` for backends with no tiers. The string
    /// values are the canonical `IsolationTier::as_str()` names (not free-form),
    /// and the field is omitted from JSON when `None`.

docs/backend-support-probe-api-plan.md:60

• This inventory omits two checks already used today: Seatbelt is probed via /usr/bin/sandbox-exec existence (mxc_engine/src/platform.rs:37), and Bubblewrap via bwrap --version (mxc_engine/src/platform.rs:55), with equivalent TypeScript checks. Include both rows and their shallow-check risks; otherwise the stated detector inventory conflicts with the later test plan.

This issue also appears in the following locations of the same file:

• line 65
• line 94
• line 107
• line 137

Four backends already have *some* presence check, but they are spread across two
layers and vary in how much they actually prove. Documenting them here so the
probe API can reuse the Rust ones and knowingly accept the risk of the shallower
ones.

docs/backend-support-probe-api-plan.md:79

• appcontainer-dacl is always selected by the policy-free tier walk, but that does not establish the API's promised “can actually run” result. The existing detector only warns when the system-drive and \Device\Null preparations are absent (fallback_detector.rs:248-253), while docs/host-prep.md:38-54 says Tier 3 depends on them and the null-device default is AppContainer-hostile. Either gate availability on those prep facts or narrow the API contract and the “Stock Windows” example to report tier selectability rather than runnable availability.

| `base-container` | BaseContainer API is **usable** (not merely symbol-present) | `fallback_detector::is_base_container_usable()` (the cached wrapper) |
| `appcontainer-bfs` | built with the `tier2_bfs` feature | `cfg!(feature = "tier2_bfs")` |
| `appcontainer-dacl` | always (universal Windows floor) | — |

docs/backend-support-probe-api-plan.md:127

• The CLI-based Linux checks need a bounded timeout. Both the existing Rust command_succeeds() and TypeScript lxc-ls/bwrap probes wait indefinitely, so calling this API at startup can hang the application if a PATH-resolved executable stalls. Require timeout plus child termination and treat timeout as unavailable.

- On Linux, `bubblewrap` and `lxc` each appear when their check passes (`bwrap --version` / `lxc-ls --version`).

docs/backend-support-probe-api-plan.md:142

• wxc-exec is Windows-only, and mxc_ffi currently exposes no probe entry point, so this transport cannot project the Linux/macOS backend results described above into the Node SDK. Define a native endpoint for each platform (lxc-exec and mxc-exec-mac as well as wxc-exec), or add a cross-platform binding that Node can actually call.

5. TypeScript projection - make `getPlatformSupport()` read the native probe (`wxc-exec --probe` / `mxc_ffi`)
instead of running its own `dism`/`lxc-ls`, so the two layers can't drift (§4.2, step 2).

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Balanced

[azure-pipelines]

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

[Copilot]

Review details

Suppressed comments (8)

docs/backend-support-probe-api-plan.md:94

• The IsolationSession prerequisite does not match the TypeScript gate this follow-up says to port. sdk/node/src/platform.ts:96-105 accepts only major === 26300 && minor >= 8553; a generic >= 26300.8553 also admits later major builds that the current implementation explicitly rejects. State the exact predicate, or explicitly document and test the intended expansion.

| `isolation_session` | build ≥ 26300.8553 **and** `IsoSessionApp.dll` resolvable **and** feature compiled | build gate lives **only in the TypeScript SDK** | wrong OS builds falsely pass |

docs/backend-support-probe-api-plan.md:107

• Porting only these two checks cannot make the API cover every backend: this same plan says isolation_session, microvm, and hyperlight remain omitted until separate detectors land. Limit this claim to the two newly consolidated backends and keep the single-detector rationale scoped to backends with landed detectors.

| 1. Consolidate detectors in Rust | Port the two TypeScript-only checks (`windows_sandbox` DISM/feature check, `lxc-ls`) into Rust<br>so `available_backends()` covers every backend. | Each backend has exactly one detector. |

docs/backend-support-probe-api-plan.md:89

• The “no process launch” criterion conflicts with the planned dism, bwrap --version, and lxc-ls --version subprocesses. If the intended restriction is only that probing must not launch a sandbox workload, say that explicitly; otherwise the proposed detectors do not satisfy this definition of probe-suitable.

Four backends have no *probe-suitable* (cheap, no persistent host mutation, no
process/VM launch) host detector in Rust today, so a truthful availability signal
for them **cannot be built just yet**.

docs/backend-support-probe-api-plan.md:127

• These subprocess probes need a bounded timeout before they are used by a startup API. The existing Rust Bubblewrap check calls Command::status() without a timeout (src/core/mxc_engine/src/platform.rs:90-99), and the TypeScript LXC/Bubblewrap checks are also unbounded, so a hung executable can block available_backends() indefinitely. Specify and test timeout handling, treating expiry as unavailable.

- On Linux, `bubblewrap` and `lxc` each appear when their check passes (`bwrap --version` / `lxc-ls --version`).

docs/backend-support-probe-api-plan.md:14

• The stated contract is stronger than the proposed detectors can provide. The document later acknowledges that lxc-ls --version does not prove container privileges, the Windows Sandbox check does not prove a VM can boot, and tier selection does not guarantee a request will run. Either strengthen detection to meet “can actually run”/“not currently usable for any reason,” or consistently describe this as a best-effort prerequisite probe so callers do not treat a positive result as an execution guarantee.

This issue also appears in the following locations of the same file:

• line 87
• line 107

Provide a read-only Rust API that reports which containment backends the
current host can actually run. Callers can read at startup
to choose a backend without attempting an execution. 

docs/backend-support-probe-api-plan.md:60

• This inventory omits two existing Rust presence checks: Seatbelt checks /usr/bin/sandbox-exec at src/core/mxc_engine/src/platform.rs:35-50, and Bubblewrap runs bwrap --version at platform.rs:53-65. Add both rows (including their false-positive risks), otherwise this section does not accurately identify the detectors the new API can reuse.

This issue also appears on line 127 of the same file.

Four backends already have *some* presence check, but they are spread across two
layers and vary in how much they actually prove. Documenting them here so the
probe API can reuse the Rust ones and knowingly accept the risk of the shallower
ones.

docs/backend-support-probe-api-plan.md:65

• Correct the merged words and punctuation in “checkwhich.”

| `windows_sandbox` | `isWindowsSandboxAvailable()` runs `dism /online /get-featureinfo `<br>`/featurename:Containers-DisposableClientVM ` and looks for `State : Enabled`<br>if DISM throws (usually non-elevated) it falls back to<br>`fs.existsSync(%SystemRoot%\\System32\\WindowsSandbox.exe)`; result cached. | TypeScript SDK | `dism /online` needs elevation, so a non-elevated caller can't tell *disabled* from<br>*no permission* and drops to the exe-existence checkwhich proves the feature is installed,<br>not that a sandbox VM can boot. (Will move to Rust) |

docs/backend-support-probe-api-plan.md:29

• Option<String> is free-form despite the comment claiming otherwise, so the public Rust API cannot enforce canonical tier values and the claimed structural drift prevention does not hold. Use a typed public enum/newtype (serialized to the existing strings), or make construction private and validate through a canonical constructor.

This issue also appears on line 94 of the same file.

    /// values are the canonical `IsolationTier::as_str()` names (not free-form),
    /// and the field is omitted from JSON when `None`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tier: Option<String>,

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Branden Bonaby (bbonaby)]

adpa-ms will sessions have an API we can call with our new probe? Just to see if it's available I mean. Possibly could be an Is-Apiset-Available call, assuming they apis are in an apiset that is.

[adpa-ms]

I improved the probe in #761 where it now looks for the API class being registered on the OS instead of checking a build number.

[Huzaifa Danish (huzaifa-d)]

adpa-ms following up: could sessions expose an apiset-available style check (for example IsApiSetImplemented against the IsolationSession apiset) so the probe can confirm availability cheaply without attempting a real activation? Now that #761 detects the Windows.AI.IsolationSession.Preview IsoSessionOps class registration rather than a build number, a lightweight availability query would shape the isolation_session detector nicely.

[adpa-ms]

This API isn't in an apiset unfortunately. I do not think I can do better than I have put in right now. However, I'm noting this down as a follow up. The isolation session API is also attempting to lift out of the OS, so that may open up some better options down line.

[Copilot]

Review details

Suppressed comments (7)

docs/backend-support-probe-api-plan.md:95

• “No process launch” contradicts the proposed bwrap --version and lxc-ls --version detectors, which spawn child processes. Clarify that the constraint is no sandbox workload or VM launch; otherwise those planned detectors are not probe-suitable by this definition.

Four backends have no *probe-suitable* (cheap, no persistent host mutation, no
process/VM launch) host detector in Rust today, so a truthful availability signal
for them **cannot be built just yet**.

docs/backend-support-probe-api-plan.md:115

• This does not structurally eliminate wire-name drift: AvailableBackend.backend and tier are both String, so producers must still hand-encode the values and serde will serialize any typo unchanged. Use serializable closed enums (a concrete-backend enum and an isolation-tier enum), or make these fields private and expose constructors that derive the strings from those enums.

| 3. Names flow from serde | Backend names (`Containment`) and tier strings (`IsolationTier::as_str()`) are already Rust-serialized;<br>TypeScript consumes them as-is instead of hand-re-encoding. | Removes the wire-name drift class structurally. |

docs/backend-support-probe-api-plan.md:102

• The proposed Hyperlight check is incomplete. Dispatch supports Hyperlight only on x86_64 (mxc_engine/src/run.rs:351-372), and the runner fails preflight when neither an installed image nor kernel/initrd install source exists (hyperlight/common/src/lib.rs:241-257). Checking only the feature and hypervisor can therefore report an ARM64 build or image-less host as available; include architecture and image/install-source checks.

| `hyperlight` | hypervisor present + feature compiled | nothing | same VM-boot risk |

docs/backend-support-probe-api-plan.md:135

• WslcSdk::load() only proves that the colocated SDK DLL and exports exist. The execution path immediately calls WslcGetMissingComponents and refuses to run when the WSL package or Virtual Machine Platform is missing (wsl_container_runner.rs:346-365), so this test would advertise wslc on hosts that cannot use it. Require WslcGetMissingComponents to succeed with no missing bits before returning this backend, and update the detector table accordingly.

- `wslc` appears when `WslcSdk::load()` resolves `wslcsdk.dll`; the remaining VM group
(`windows_sandbox`, `isolation_session`, `microvm`, `hyperlight`) never appears until its detector lands.

docs/backend-support-probe-api-plan.md:100

• The “as of #761” status is stale: that change already adds public is_service_available() activation probing and transports it as probes.isolationSessionAvailable. The remaining gap is moving/reusing that detector behind the new side-effect-free transport, not creating or exposing a Rust probe seam; update this row and follow-up item 2 so they do not schedule completed work.

| `isolation_session` | activation of the in-proc `Windows.AI.IsolationSession.Preview` `IsoSessionOps` runtime class succeeds (the API class is registered on the OS **and** its OS feature gate is on) **and** the backend feature is compiled | as of #761, detection queries whether the API class is registered rather than gating on a build number; a `CLASS_E_CLASSNOTAVAILABLE` / `REGDB_E_CLASSNOTREG` activation failure means unavailable | none for false-availability now — a machine without the API registered fails activation cleanly; still needs a cheap probe seam so callers don't have to attempt a real activation |

docs/backend-support-probe-api-plan.md:66

• This inventory is incomplete: mxc_engine::platform_support() already checks bwrap --version and /usr/bin/sandbox-exec (platform.rs:35-66), and the TypeScript layer has the same checks. Add Bubblewrap and Seatbelt so the design records the existing detectors it plans to reuse.

This issue also appears on line 93 of the same file.

Four backends already have *some* presence check, but they are spread across two
layers and vary in how much they actually prove. Documenting them here so the
probe API can reuse the Rust ones and knowingly accept the risk of the shallower
ones.

docs/backend-support-probe-api-plan.md:71

• Correct the merged words in this sentence.

| `windows_sandbox` | `isWindowsSandboxAvailable()` runs `dism /online /get-featureinfo `<br>`/featurename:Containers-DisposableClientVM ` and looks for `State : Enabled`<br>if DISM throws (usually non-elevated) it falls back to<br>`fs.existsSync(%SystemRoot%\\System32\\WindowsSandbox.exe)`; result cached. | TypeScript SDK | `dism /online` needs elevation, so a non-elevated caller can't tell *disabled* from<br>*no permission* and drops to the exe-existence checkwhich proves the feature is installed,<br>not that a sandbox VM can boot. (Will move to Rust) |

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Branden Bonaby (bbonaby)]

FYI: Gudge (@MGudgin) would probably be interested in seeing how we implement this

[Branden Bonaby (bbonaby)]

note: Richie added a check directly in base_container_runner now I believe that you can use.

[azure-pipelines]

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

[azure-pipelines]

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