feat: prefer option-aware Learning Mode trace startup

[Richie Gomez (richiemsft)]

📖 Description

Introduces option-aware Learning Mode trace startup while preserving compatibility with systems that expose only the legacy start export.

• Prefers StartLearningModeTraceWithOptions when available.
• Falls back to StartLearningModeTrace only when the option-aware export is absent.
• Keeps Stop and Close mandatory for either ABI.
• Exposes whether the selected trace collects access-only or access-and-network events.
• Adds an injectable export-selection seam and complete mixed-ABI coverage.

This is PR 1 of 4 in the WFP Learning Mode stack.

🔗 References

Related to #1286.

🔍 Validation

• cargo test -p mxc-sdk --lib 'core_modules::learning_mode_windows::ffi::tests::' — 18 passed.
• Native capture source propagation — 6 passed.
• Native capture serviceability probe — 1 passed.
• cargo clippy -p mxc-sdk --lib -- -D warnings — passed.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated documentation (if applicable)
• Updated Copilot instructions (not applicable)
• If this PR changes Cargo.lock, the dependency-feed-check check passes (not applicable)

📋 Issue Type

• Bug fix
• Feature
• Task

🧱 Stack

1. feat: prefer option-aware Learning Mode trace startup #1417 — API startup and compatibility
2. feat: decode WFP Learning Mode network events #1418 — WFP event decoding
3. fix: route captured network decisions through Tessera #1419 — ProcessContainer integration
4. docs: describe WFP denial capture #1420 — Documentation

Review and merge in this order.

Microsoft Reviewers: Open in CodeFlow

[Copilot]

Copilot review overview

🟡 Changes recommended

The canonical host-selection documentation still incorrectly requires the legacy start export.

Review effort: Balanced
Findings: 1

Open (1)

• Update host-selection docs for options-only compatibility · New

What changed in this PR

Adds option-aware Learning Mode trace startup while retaining legacy ABI compatibility.

Changes:

• Prefers access-and-network tracing when supported.
• Falls back to the legacy start export.
• Adds mixed-ABI selection and failure tests.

File	Description
src/​core/​learning_mode_platforms/​windows/​src/​lib.rs	Documents both start exports.
src/​core/​learning_mode_platforms/​windows/​src/​ffi.rs	Implements export selection, invocation, and tests.

---

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

[Gudge (MGudgin)]

Summary

Requested change: Expose which Learning Mode sources a successful trace actually collected. The new options path requests access and network events, but the legacy path is access-only; both return an indistinguishable LearningModeTraceHandle. Once #1418 consumes network events, a caller cannot tell whether an empty network-denial result means no denial or no network collection. #1420 documents the distinction for readers but does not provide a machine-readable signal. The other findings are Low-priority improvements.

Verified clean: The PR patch matches GitHub's diff; both start paths still require Stop and Close (ffi.rs:422-430), and the DLL remains restricted to System32. The new selection tests cover options-only, mixed and legacy-only export availability. #1418 supplies the decoder and #1420 fixes the canonical host-selection guide, so neither earlier stack-stage concern is repeated here. The PR branch is behind the current main tip (merge-base 2f85ccd, current base 1ad9202); intervening base commits do not touch the affected FFI or lifecycle files.

Finding outside the diff

Low (maintainability) — Update the legacy-only lifecycle comments. src/mxc-sdk/src/backends/process_container/common/native_capture.rs:11,62 — Attribution: newly_exposed_by_change. This file is byte-identical between the PR's merge-base and head; it is not an old defect charged to this PR. Its description of every start/failure as StartLearningModeTrace becomes inaccurate because the new preferred path invokes StartLearningModeTraceWithOptions and reports that function name on failure. Fix: Describe the selected Learning Mode start export in those comments; retain legacy-specific assertions in tests using a legacy fake.

Verified pre-existing — not attributed to this PR

None. The byte-identical lifecycle file above is included only because the new preferred ABI makes its comments stale. No finding already handled in later stack PRs is a merge condition here.

[Richie Gomez (richiemsft)]

Also addressed the review summary's out-of-diff maintainability note in 08def3b: native_capture.rs now describes the selected Learning Mode start export rather than assuming the legacy export. The stack was rebased onto current main, adapted to the new documentation layout, and all downstream branches were restacked.

[Copilot]

🟡 Changes recommended

Native availability probing can still select an incomplete ABI and bypass the guarded fallback.

1 open finding

• Native availability probe ignores required ABI exports · New

1 resolved since last review

• Update host-selection docs for options-only compatibility

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The compatibility logic is scoped, fail-closed, and comprehensively tested.

0 open findings

1 resolved since last review

• Native availability probe ignores required ABI exports

🧠 Review effort: Balanced

[Gudge (MGudgin)]

Re-verified #1417 at 477de8c against its rebased PR base. Four of my five filed findings are addressed: the missing-export diagnostic, lifecycle comments, null-handle test, and selected-pointer lifecycle test. The effective source mode now reaches LearningModeApi, LearningModeTraceHandle, and CaptureSession; I noted in the original thread that it is not yet threaded into the caller-visible captureDenials/SDK result. I accept that remaining result-level propagation as a non-blocking follow-up for the integration layer, not as a completed end-to-end fix.

Validation on this updated Windows tree: cargo test --quiet -p mxc-sdk --lib core_modules::learning_mode_windows::ffi::tests:: (18 passed) and cargo test --quiet -p mxc-sdk --lib native_capture (12 passed). These are fake-backed and serviceability tests; I did not verify an options-capable live Windows host. This approval covers the updated PR and the dispositions above, not the completeness of the later stack's user-facing result metadata.