Carry the failing API's detail through the in-process SDKs

[adpa-ms]

📖 Description

When a platform API call fails, the backend records which call failed, its native status, and sometimes a remediation hint. The TypeScript SDK already surfaces all three. In-process callers get none of it.

wxc_common::mxc_error::MxcError carries that detail in api_failure, but the public SDK facade mxc_engine::error::Error holds only { code, message } and its From<MxcError> drops api_failure on the floor. Everything below is blind: the Rust SDK, the C ABI, and the C# MxcException. Two callers observing the same failure get materially different diagnoses — in-process callers see backend_error: The provision was not found. and no way to learn which call failed.

This carries the detail through all three layers.

• The engine facade carries the three flat on Error, beside code and message, matching the wire envelope, the C ABI, the C# binding and the TypeScript SDK. Nesting them behind a sub-struct would make the Rust SDK the one surface of five shaped differently.
• The C ABI gains one MxcErrorDetail used by every failing surface — MxcRunResult, MxcStateAwareResult, and the out_error parameter — so a binding learns the same things from any of them and frees them all the same way.
• The C# binding surfaces Operation / NativeCode / Remediation on MxcException. A null pointer becomes null, never ""; null means the layer below supplied nothing.

The Rust SDK gains structured errors too, not only C#.

Notes for reviewers

• out_error changes ownership shape, from a library-allocated string to caller-provided storage for one detail. The detail owns heap strings with no destructor, so a caller passing null would leak them; finish_spawn frees it on that path.
• The field-coupling claims are removed. The docs said nativeCode and remediation do not appear without operation. This decouples remediation, so the claims no longer hold — including in the TypeScript SDK and both wire docs.
• Error is #[non_exhaustive], mirroring the wire envelope and MxcError. Adding it later is a breaking change; removing it is not. ErrorCode stays closed, mirroring MxcErrorCode.
• The codegen gate gains a parity assertion. csbindgen's sources and the C# project's MSBuild Inputs name the same files; adding to one and not the other compiles against stale bindings.
• mxc_version is the one C ABI entry point not catch_unwind-wrapped, contradicting the module header. Now wrapped, 23 of 23.
• Growing REQUIRED_ENTRY_POINTS to the full P/Invoke surface belongs with the C# workstream: the compiler already catches rename and removal.
• The C ABI is not a stable external contract — native and binding are co-versioned and generated together — so reshaping the #[repr(C)] types is expected.

🔗 References

Resolves #924

🔍 Validation

• Local gauntlet, 23 checks green, plus wxc_host_prep (16 tests) run elevated: fmt, clippy -D warnings, workspace tests with the isolation-session feature on and off, arm64 cross-build, six versioning gates, both C# SDK gates, dotnet test (47), and the Node build, unit, pack and integration legs.
• Isolation-session E2E on a VM running the OS-side service, from a package built at this commit: 90 passed, 0 failed, 0 skipped — 16 one-shot, 62 state-aware, 12 SDK-integration — confirmed against the JUnit output. The agent-account leak check came back empty against a pre-run baseline, and IsoSessionCli list-users agreed at Found 0 agent user(s).
• The three interactive TTY tests were run by an operator at the VM console and passed.
• ErrorCode parity is unaffected; this adds no new MXC_STATUS_* codes.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)

📋 Issue Type

• Bug fix

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

Carries structured platform API failure details through the Rust, C ABI, and C# SDK layers, addressing #924.

Changes:

• Preserves ApiFailure in the engine and Rust SDK.
• Adds shared C ABI and C# structured error models.
• Updates bindings generation, documentation, and tests.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/core/mxc_engine/src/error.rs	Adds structured API failure details.
src/core/mxc_engine/src/lib.rs	Exports ApiFailure.
src/core/mxc-sdk/src/lib.rs	Exposes and documents structured errors.
src/ffi/mxc_ffi/src/error_detail.rs	Defines the shared FFI error shape.
src/ffi/mxc_ffi/src/lib.rs	Integrates details into run results.
src/ffi/mxc_ffi/src/streaming.rs	Returns details from streaming spawn.
src/ffi/mxc_ffi/src/state_aware.rs	Returns details from lifecycle calls.
src/ffi/mxc_ffi/build.rs	Adds error-detail binding generation.
src/ffi/mxc_ffi/tests/ffi.rs	Updates FFI result assertions.
sdk/dotnet/Microsoft.Mxc.Sdk/Native/NativeError.cs	Marshals native error details.
sdk/dotnet/Microsoft.Mxc.Sdk/MxcException.cs	Exposes structured exception properties.
sdk/dotnet/Microsoft.Mxc.Sdk/MxcSandbox.cs	Propagates run and spawn details.
sdk/dotnet/Microsoft.Mxc.Sdk/MxcLifecycle.cs	Propagates lifecycle details.
sdk/dotnet/Microsoft.Mxc.Sdk/Microsoft.Mxc.Sdk.csproj	Tracks the new binding input.
sdk/dotnet/Microsoft.Mxc.Sdk.Tests/MxcExceptionTests.cs	Tests structured exceptions.
sdk/dotnet/README.md	Documents failure diagnostics.
scripts/check-dotnet-bindings-codegen.js	Checks binding-input parity.

---

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

[Copilot]

Pull request overview

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

Suppressed comments (3)

src/ffi/mxc_ffi/src/error_detail.rs:117

• This new exported C ABI destructor bypasses the crate's panic barrier. The other destructors wrap their bodies in catch_unwind (src/ffi/mxc_ffi/src/lib.rs:384-391, :400-407, and state_aware.rs:154-161), matching the crate-level guarantee that every entry point is panic-contained. Wrap this body too so a future panic in cleanup cannot abort at the FFI boundary.

pub unsafe extern "C" fn mxc_error_detail_free(detail: *mut MxcErrorDetail) {
    if detail.is_null() {
        return;
    }
    // SAFETY: non-null per the check above, and valid per the caller contract.
    unsafe { (*detail).free_strings() };

src/core/mxc-sdk/src/lib.rs:142

• The repository's SDK documentation rule (.github/copilot-instructions.md:248) requires public Rust SDK API changes to update both crate docs and src/core/mxc-sdk/README.md. This new ApiFailure export and its accessors are covered only in the crate docs; the README still mentions bare Error/ErrorCode behavior and gives callers no structured-diagnostics guidance. Please add the same contract and example there.

pub use mxc_engine::{
    available_backends, available_tools_policy, build_request, build_request_with_containment,
    platform_support, temporary_files_policy, user_profile_policy, ApiFailure, AvailableBackend,
    BackendCapability, Containment, Error, ErrorCode, FilesystemPolicyResult, PlatformSupport,
    SandboxPolicy, SandboxRequest, WslcSection,

sdk/dotnet/Microsoft.Mxc.Sdk/Native/NativeError.cs:39

• The key populated-detail marshalling path remains untested. Existing native C# tests exercise only null operation/status fields, while ApiDetail_IsCarriedAlongsideTheCodeAndMessage bypasses this helper by constructing MxcException directly. A field-order or UTF-8 mapping regression here would therefore pass. Add a unit test that builds an MxcErrorDetail with unmanaged UTF-8 values, calls ToException, and asserts all four mapped strings plus null-versus-empty behavior.

        return new MxcException(
            (ErrorCode)status,
            ToStringOrNull(detail.message_utf8) ?? fallbackMessage,
            ToStringOrNull(detail.operation_utf8),
            ToStringOrNull(detail.native_code_utf8),
            ToStringOrNull(detail.remediation_utf8));

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Suppressed comments (1)

src/core/mxc_engine/src/error.rs:97

• These independent public fields do not enforce the documented “native code implies operation” invariant. Even with #[non_exhaustive], a downstream caller can create Error::new(...) and then set native_code while leaving operation as None; Display will silently omit that status, while MxcErrorDetail::from_error propagates the invalid pair. Please use the grouped Option<Box<ApiFailure>> representation described in the PR, with operation required, or make these fields private and expose invariant-preserving accessors/builders.

    pub operation: Option<String>,
    /// The underlying platform status, e.g. `0x80070490`. Only ever present
    /// alongside [`operation`](Self::operation): a status with no call to
    /// attribute it to is not something a producer can express.
    pub native_code: Option<String>,

[Branden Bonaby (bbonaby)]

Two serious issues found in the Rust/adversarial review.

[Copilot]

Pull request overview

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

Suppressed comments (4)

sdk/node/src/errors.ts:32

• This still implies that remediation cannot exist without operation, while this PR explicitly makes remediation independent (and adds a remediation-only Rust test). It also drops the remaining nativeCode ⇒ operation invariant that the PR description says is still guaranteed. Please document those two rules directly so TypeScript consumers get the intended contract.

 * **Invariant:** `operation` marks that an underlying API call was in flight.
 * A failure MXC raises before or outside any API call carries only `code` and
 * `message`.

sdk/node/README.md:288

• Saying pre-backend failures carry only code and message reintroduces the removed remediation ⇒ operation coupling. It also leaves the actual nativeCode ⇒ operation invariant undocumented here. Align this README with the contract described by the PR and the Rust remediation-only case.

`operation`, `nativeCode` and `remediation` are optional. A failure MXC raises before reaching the backend — a malformed request or id, or a policy rejection — carries only `code` and `message`.

docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md:822

• This wording still makes remediation impossible without an operation because non-API failures are said to carry only code and message, contrary to this PR's remediation-only public shape. It also no longer states the retained nativeCode ⇒ operation invariant. Please describe both rules explicitly.

**Invariant:** `operation` marks that an API operation was in flight. A failure
MXC raises before or outside any API call — a malformed request or id, a policy
rejection, or an internal failure of MXC's own machinery — carries only `code`
and `message`.

scripts/check-dotnet-bindings-codegen.js:179

• The new parity gate checks csbindgen inputs against MSBuild inputs but not against Cargo's rerun-if-changed list. If a future extern source is added to both checked lists but omitted from rerun-if-changed, MSBuild will invoke Cargo after edits while Cargo skips the build script, leaving stale bindings—the same incremental failure this gate is intended to prevent. Parse and compare the cargo:rerun-if-changed source paths as a third set.

const notDeclared = csbindgenInputs.filter((rel) => {
  const expected = `${CRATE_REL_ROOT}/${rel}`;
  return !declaredInputs.some((declared) => declared.endsWith(expected));
});

[Copilot]

Pull request overview

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