Consume the Windows Learning Mode trace API: FFI loader + capture lifecycle

[richiemsft]

📖 Description

Adds the Windows runtime FFI and RAII lifecycle for consuming the new OS Learning Mode
trace API exported by processmodel.dll — the foundation for the upcoming
captureDenials feature (capture a sandboxed process's access denials to an ETL for
later analysis).

This PR is foundation only; it does not yet wire any runner. It introduces a new
crate, learning_mode_windows (src/backends/learning_mode/windows):

• Trace FFI (ffi.rs) — LearningModeApi loads/resolves StartLearningModeTrace /
  StopLearningModeTrace via LoadLibraryExW(SYSTEM32) + GetProcAddress, with a
  is_learning_mode_api_available() capability probe. Mirrors the existing
  Experimental_CreateProcessInSandbox loader pattern.
• 2-phase security-environment FFI (secenv.rs) — SecurityEnvironmentApi
  (CreateProcessSecurityEnvironment / CreateProcessAsUserInsideSecurityEnvironment /
  CloseProcessSecurityEnvironment) that produces the HPROCESS_SECURITY_ENVIRONMENT
  handle StartLearningModeTrace keys on, plus a per-export diagnostic probe with an
  Experimental_-prefixed fallback.
• RAII lifecycle (lifecycle.rs) — CaptureSession sequences create-env →
  start-trace → [caller launches child] → stop-trace → close-env in the required order,
  with best-effort Drop teardown (discard trace + close env) on the early-exit/unwind
  path.
• Validation examples — lm_probe (export-resolution probe) and lm_capture (drives
  the entire lifecycle against a real child and asserts an ETL is produced).

The API surface is resolved at runtime and degrades cleanly on OS builds that lack it
(the probe returns false, load() returns a typed error). The crate compiles on all
platforms (non-Windows is a stub).

Not in this PR (follow-ups): the captureDenials config, the production runner path
in appcontainer_common, and ETL parsing. The runner wiring will reuse BaseContainer's
FlatBuffer sandbox_spec builder and swap the one-shot launch for CaptureSession +
launch_fn; it depends on the captureDenials config landing first.

🔗 References

Part of the Windows learning-mode / captureDenials effort. Follow-up PRs will add the
captureDenials config + schema, the runner integration, and ETL → DeniedResource
parsing.

🔍 Validation

• cargo test -p learning_mode_windows — 5 unit tests pass.
• cargo clippy -p learning_mode_windows --all-targets -- -D warnings — clean.
• cargo fmt -p learning_mode_windows -- --check — clean.
• Hardware-validated on a GE_CURRENT DirectWinPD x64 build:
  • lm_probe: all trace + security-environment exports resolve under their plain
    (graduated) names; LearningModeApi::load / SecurityEnvironmentApi::load succeed.
  • lm_capture: the full lifecycle ran end-to-end — MXC's own FlatBuffer "SBOX" spec
    was accepted directly by CreateProcessSecurityEnvironment (no text tech-spec
    compile), the child launched inside the environment and exited 0, and
    StopLearningModeTrace sealed a 3650-byte ETL.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)
• If this PR changes Cargo.lock, the dependency-feed-check check passes (the Cargo.lock change only adds already-present workspace crates — flatbuffers, sandbox_spec — as dev-deps of the new member; no new external crates)

📋 Issue Type

• Bug fix
• Feature
• Task

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 new Rust workspace member (learning_mode_windows) that dynamically loads the Windows Learning Mode trace and process security-environment exports from processmodel.dll, and provides an RAII capture lifecycle intended to be reused by a future captureDenials runner integration.

Changes:

• Adds learning_mode_windows as a workspace crate and dependency entry.
• Implements runtime FFI loaders for Learning Mode trace exports and 2-phase security-environment exports (including Experimental_ name fallbacks) plus capability probes.
• Introduces an RAII CaptureSession to sequence create-env → start-trace → stop-trace → close-env, along with lm_probe/lm_capture validation examples.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Cargo.toml	Adds the new backend crate to the workspace and workspace dependencies.
src/Cargo.lock	Records the new workspace package entry for learning_mode_windows.
src/backends/learning_mode/windows/Cargo.toml	Defines the new crate and its Windows-only deps/dev-deps.
src/backends/learning_mode/windows/src/lib.rs	Public crate surface, cfg-gated module structure, and shared error type.
src/backends/learning_mode/windows/src/ffi.rs	Runtime loader + safe wrapper for StartLearningModeTrace / StopLearningModeTrace.
src/backends/learning_mode/windows/src/secenv.rs	Runtime loader + wrapper for 2-phase security-environment process creation exports.
src/backends/learning_mode/windows/src/lifecycle.rs	RAII CaptureSession orchestration of the capture lifecycle.
src/backends/learning_mode/windows/examples/lm_probe.rs	Manual probe example to validate export resolution on real OS builds.
src/backends/learning_mode/windows/examples/lm_capture.rs	End-to-end example driving the full lifecycle and asserting an ETL is produced.

[richiemsft]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/backends/learning_mode/windows/src/lifecycle.rs:152

• The tests below only cover result combination; neither this new Drop path nor its required stop-before-close ordering is exercised. A regression that skips one cleanup call or reverses the order would still pass. Please add mock/injectable FFI callbacks and verify Drop calls stop_trace(None) before close, including cleanup-call failures.

impl Drop for CaptureSession {
    fn drop(&mut self) {
        // Best-effort teardown for the early-exit / unwind path: discard the trace
        // (NULL output path) before closing the environment. Errors are unrecoverable
        // here and are intentionally ignored — `finish` is the fallible path.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/backends/learning_mode/windows/src/lifecycle.rs:74

• The lifecycle tests only exercise result aggregation, so the key RAII guarantees here—closing the environment when trace startup fails and stopping the trace before closing on Drop—are untested; the hardware example covers only the successful finish path. Add an injectable/test API implementation and assert call order and cleanup for these failure paths.

        let trace = match unsafe { learning_mode_api.start_trace(environment.raw()) } {
            Ok(trace) => trace,
            Err(start_err) => {
                return match secenv_api.close(environment) {

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/backends/learning_mode/windows/src/lifecycle.rs:158

• The core RAII guarantee on this path is not covered by the added unit tests: they only exercise combine_teardown_results, so a regression that omits cleanup or reverses the required discard-before-close order would still pass. Add injectable/fake API function tables and assert that Drop calls StopLearningModeTrace(..., NULL) before CloseProcessSecurityEnvironment, including when the first cleanup call fails.

        if let Some(trace) = self.trace.take() {
            let _ = self.learning_mode_api.stop_trace(trace, None);
        }
        if let Some(environment) = self.environment.take() {
            let _ = self.secenv_api.close(environment);

[Copilot]

Pull request overview

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