Make exact versioned JSON the only FFI configuration ingress by MGudgin · Pull Request #1349 · microsoft/mxc

Gudge (MGudgin) · 2026-09-30T16:30:47Z

This PR adds exact-versioned JSON execution ingress to mxc_ffi and moves
state-aware callers to the explicitly named JSON exports. New configuration
entry points share the registered contract parser and take non-configuration
controls as typed arguments. This is the foundation stage: Node and .NET
one-shot execution and the .NET request probe retain their deprecated private
ingress until the follow-up migrations and cleanup land.

Details

Add mxc_run_json and mxc_spawn_json for exact one-shot configuration.
Rename the state-aware exports and update Node, .NET, and example callers.
Treat experimental opt-in as backend authorization, with
backend_unavailable for missing authorization on experimental backends.
Exclude authorization from one-shot and lifecycle policy identity.
Add shared SDK conformance inputs, expected exact documents, and invalid
documents. Rust/schema coverage is present; Node/.NET emitted-document
checks accompany their follow-up migrations.
Retain the existing Rust SDK serde support while private callers remain.
The private parser reuses SDK filesystem/network/UI types directly rather
than introducing temporary mirror models. Serde removal moves to cleanup.
Use shared exact-parser validation for blank proxy peers and strengthen
failure-result ownership coverage.

Tests

cargo fmt --all -- --check passed.
cargo check -p mxc-sdk -p mxc_engine -p mxc_ffi --all-targets --all-features passed.
cargo clippy -p mxc-sdk -p mxc_engine -p mxc_ffi --all-targets --all-features -- -D warnings passed.
cargo test -p mxc_ffi -p mxc_engine -p mxc-sdk --all-features passed,
including SDK fixture, parser, authorization, and FFI ownership coverage.
cargo test -p wxc_common --all-features -- policy_identity::tests passed:
31 tests, including one-shot and lifecycle authorization invariance.
cargo check -p mxc-sdk -p mxc_engine -p mxc_ffi --all-targets --target x86_64-unknown-linux-gnu passed; the same command with
--target x86_64-apple-darwin passed.
cargo doc -p mxc_ffi -p mxc-sdk -p mxc_engine --all-features --no-deps
passed with RUSTDOCFLAGS=-D warnings.
From sdk/node, npm run build and npm test passed against the current
native library. The refreshed integration consumer's
npx tsc --noEmit -p tsconfig.json passed.
From sdk/dotnet, dotnet test --solution Microsoft.Mxc.Sdk.slnx -p:MxcCargoProfile=debug --verbosity quiet passed: 299 tests, 29 skipped.
dotnet run --project Microsoft.Mxc.Sdk.AotSmokeTest -p:MxcCargoProfile=debug --no-restore passed with reflection disabled.
node scripts/versioning/check-contract-codegen.js passed: three exact
artifact sets match; published schemas match the current origin/main.
git diff --check passed. Native Linux/macOS, elevated Windows, and live
Node integration execution were not run.

Microsoft Reviewers: Open in CodeFlow

azure-pipelines · 2026-09-30T16:30:57Z

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

This PR adds a handoff for the v1 SDK and JSON-only FFI ingress stack and updates the ingress plan to match what was built. It records the pull requests, branches, worktrees, and backups, the design decisions and their reasons, review status, open items, and working notes for a new session. Details * Add docs/version-aware-stack-session-handoff-2026-09-30.md covering #1271, #1348, and #1349-#1353, the backend-based experimental opt-in, JSON-only ingress, V1 namespaces and MxcPlatform, the pinned SDK target, Node export conditions, shared goldens, and E0. * Mark the plan adopted, replace the planned branch table with the opened pull requests, record the unified experimental check, the serde removal, the V1 writer location, and E0, and add the namespace, goldens, and E0 decisions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 33217f7b-dc7d-4da0-af5f-018fef64013c Generated-with: claude-opus-5.5

Copilot

Copilot review overview

🟡 Changes recommended

The experimental opt-in currently changes policy identity, and documentation prematurely describes deferred binding migrations as complete.

Review effort: Balanced
Findings: 1 · 2

Open (3)

Exclude ignored authorization flags from production policy hashes · New
Clarify Node and .NET one-shot migration remains incomplete · New
Mark SDK emitted-JSON equality tests as planned follow-up coverage · New

What changed in this PR

Introduces exact-version JSON FFI entry points and standardizes experimental-backend authorization while staging migration away from private binding requests.

Changes:

Adds one-shot JSON run/spawn exports and renames lifecycle JSON exports.
Centralizes experimental-backend checks and adds SDK v1 policy goldens.
Removes Serde coupling from Rust policy types and updates bindings/docs.

File	Description
`tests/policy/sdk-v1/invalid/unknown-field.json`	Tests closed contracts.
`tests/policy/sdk-v1/invalid/processcontainer-with-seatbelt-section.json`	Tests mismatched backend sections.
`tests/policy/sdk-v1/invalid/process-with-wslc-section.json`	Tests mismatched WSLC section.
`tests/policy/sdk-v1/invalid/isolation-session-without-network.json`	Tests required network policy.
`tests/policy/sdk-v1/invalid/comma-capability.json`	Tests capability validation.
`tests/policy/sdk-v1/input/wslc.json`	Adds WSLC policy input.
`tests/policy/sdk-v1/input/seatbelt-options.json`	Adds Seatbelt input.
`tests/policy/sdk-v1/input/processcontainer-options.json`	Adds ProcessContainer input.
`tests/policy/sdk-v1/input/processcontainer-network-proxy.json`	Adds proxy-policy input.
`tests/policy/sdk-v1/input/process-minimal.json`	Adds minimal process input.
`tests/policy/sdk-v1/input/process-filesystem-ui-timeout.json`	Adds filesystem/UI input.
`tests/policy/sdk-v1/input/process-directional-network.json`	Adds directional-network input.
`tests/policy/sdk-v1/input/lxc.json`	Adds LXC input.
`tests/policy/sdk-v1/input/isolation-session.json`	Adds IsolationSession input.
`tests/policy/sdk-v1/input/invocation-options.json`	Adds invocation options.
`tests/policy/sdk-v1/input/bubblewrap.json`	Adds Bubblewrap input.
`tests/policy/sdk-v1/expected/wslc.json`	Defines expected WSLC document.
`tests/policy/sdk-v1/expected/seatbelt-options.json`	Defines expected Seatbelt document.
`tests/policy/sdk-v1/expected/processcontainer-options.json`	Defines expected ProcessContainer document.
`tests/policy/sdk-v1/expected/processcontainer-network-proxy.json`	Defines expected proxy document.
`tests/policy/sdk-v1/expected/process-minimal.json`	Defines minimal process document.
`tests/policy/sdk-v1/expected/process-filesystem-ui-timeout.json`	Defines filesystem/UI document.
`tests/policy/sdk-v1/expected/process-directional-network.json`	Defines directional-network document.
`tests/policy/sdk-v1/expected/lxc.json`	Defines expected LXC document.
`tests/policy/sdk-v1/expected/isolation-session.json`	Defines IsolationSession document.
`tests/policy/sdk-v1/expected/invocation-options.json`	Defines invocation document.
`tests/policy/sdk-v1/expected/bubblewrap.json`	Defines Bubblewrap document.
`tests/policy/README.md`	Documents fixture families.
`src/ffi/mxc_ffi/tests/ffi.rs`	Tests new JSON exports.
`src/ffi/mxc_ffi/src/streaming.rs`	Adds `mxc_spawn_json`.
`src/ffi/mxc_ffi/src/state_aware.rs`	Renames lifecycle exports.
`src/ffi/mxc_ffi/src/request.rs`	Preserves deprecated request parsing.
`src/ffi/mxc_ffi/src/lib.rs`	Adds `mxc_run_json`.
`src/ffi/mxc_ffi/examples/attached_console_ffi.rs`	Updates lifecycle example symbols.
`src/core/wxc_common/src/models.rs`	Classifies experimental backends.
`src/core/mxc-sdk/src/lib.rs`	Adds raw JSON SDK APIs.
`src/core/mxc-sdk/README.md`	Removes obsolete legacy-network guidance.
`src/core/mxc_engine/src/state_aware.rs`	Centralizes lifecycle authorization.
`src/core/mxc_engine/src/run.rs`	Centralizes one-shot authorization.
`src/core/mxc_engine/src/policy/sdk_v1_goldens.rs`	Adds golden-policy tests.
`src/core/mxc_engine/src/policy/network.rs`	Removes policy Serde derives.
`src/core/mxc_engine/src/policy/exact/v1_0.rs`	Aligns v1 exact mapping.
`src/core/mxc_engine/src/policy/exact/mod.rs`	Removes host-derived sections.
`src/core/mxc_engine/src/policy.rs`	Updates plain policy types.
`src/core/mxc_engine/src/lib.rs`	Adds exact JSON engine ingress.
`src/core/mxc_engine/src/experimental.rs`	Implements shared opt-in validation.
`src/core/mxc_engine/src/configs/process_container.rs`	Defers capability derivation.
`sdk/node/tests/unit/state-aware.test.ts`	Updates renamed-symbol wording.
`sdk/node/src/bindings/streaming.ts`	Binds renamed streaming exec.
`sdk/node/src/bindings/state-aware.ts`	Binds renamed lifecycle run.
`sdk/dotnet/Microsoft.Mxc.Sdk/V1/MxcLifecycle.cs`	Updates lifecycle P/Invokes.
`sdk/dotnet/Microsoft.Mxc.Sdk.Tests/V1/MxcLifecycleTests.cs`	Updates lifecycle test wording.
`scripts/versioning/validate-configs.js`	Validates expected goldens.
`scripts/check-dotnet-bindings-codegen.js`	Requires new JSON exports.
`docs/versioning.md`	Documents JSON ingress.
`docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md`	Updates lifecycle symbols/errors.
`docs/isolation-session/state-aware-rust.md`	Updates lifecycle API table.

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

Copilot

Copilot review overview

🟡 Changes recommended

Node and .NET one-shot paths still use the deprecated JSON request exports, including JSON-based experimental authorization.

Review effort: Balanced
Findings: 2 · 2

Open (4)

Migrate Node and .NET bindings to typed run/spawn configuration · New
Exclude ignored authorization flags from production policy hashes
Mark SDK emitted-JSON equality tests as planned follow-up coverage
Clarify Node and .NET one-shot migration remains incomplete

This PR makes exact versioned JSON the only way sandbox configuration crosses the native mxc_ffi boundary. Non-configuration controls, such as the experimental opt-in and dry-run, stay typed i32 arguments and are never read from JSON. Details * Add mxc_run_json and mxc_spawn_json, backed by mxc_sdk::run_json and spawn_sandbox_json, for exact-version one-shot documents. * Rename the lifecycle exports to mxc_run_state_aware_json, mxc_exec_state_aware_json, and mxc_exec_state_aware_attached_json, with no aliases, and move every .NET, Node, and example caller. * Replace the per-backend experimental checks with one rule: the opt-in only permits an experimental backend (MicroVM, Hyperlight, Windows Sandbox) and is ignored for production backends. A missing opt-in is backend_unavailable on every one-shot and lifecycle path. * Add tests/policy/sdk-v1 goldens pairing high-level policy invocations with the exact 1.0.0 document every v1 SDK must emit, plus invalid documents, and align the Rust builder with them. * Document the JSON-only ingress rule and deprecate mxc_run_request, mxc_spawn_request, and the private binding request. * Remove Deserialize and Serialize from the Rust SDK policy types; the deprecated binding request owns private copies until it is removed. Tests * From src, these format, compile, lint and unit-test commands passed: cargo fmt -p mxc_ffi -p mxc_engine -p mxc-sdk -p wxc_common -- --check cargo check -p mxc_ffi -p mxc_engine -p mxc-sdk -p wxc_common --all-targets cargo clippy -p mxc_ffi -p mxc_engine -p mxc-sdk -p wxc_common --all-targets -- -D warnings cargo test -p mxc_ffi -p mxc_engine -p mxc-sdk -p wxc_common * cargo check -p mxc_ffi --all-targets --features isolation_session,wslc passed on Windows. * Node: npm run build passed; npm test passed against freshly built mxc_ffi.dll (387 passed, 20 skipped). * .NET: dotnet test --solution Microsoft.Mxc.Sdk.slnx passed (266 passed, 27 host-dependent tests skipped). * node scripts\check-dotnet-bindings-codegen.js passed (40 entry points); node scripts\versioning\validate-configs.js passed (414 exact configs). * Linux/macOS execution and host-dependent backend E2E were not run. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2b92ee5b-30e2-4c0c-8189-df64fc215078 Generated-with: gpt-6.1-sol

This PR keeps experimental backend authorization out of policy identity and delegates blank proxy-peer validation to the shared exact parser. It also clarifies the transitional binding paths and failure-result ownership while the language bindings complete their JSON ingress migrations. Details * Exclude authorization from one-shot and lifecycle hashes, with backend invariance and projection-key regression coverage. * Remove duplicate builder validation, compare its errors with shared parser diagnostics, and add the blank-peer invalid golden. * Verify lifecycle error cleanup and correct native, fixture, versioning, and telemetry documentation, including qualified Rust API links. * Adapt merged Linux LXC FFI test imports to the new common import list. Tests * cargo fmt --all -- --check passed. Both workspace commands passed: cargo check --workspace --all-targets --all-features cargo clippy --workspace --all-targets --all-features -- -D warnings * Full wxc_common/mxc_engine/mxc-sdk/mxc_ffi tests passed. Targeted tests: 31 policy identity, 3 builder validation, 3 SDK goldens, 17 lifecycle. * Linux all-target checks, macOS clippy, and Rustdoc passed with warnings denied. Elevated and native Linux/macOS backend suites were not run. * Node build/typecheck and npm test passed (389 passed, 20 skipped). .NET tests passed (299 passed, 29 skipped), plus XML docs, API parity, 40 generated bindings, and native AOT publish and smoke execution. * Versioning tests: 67 passed. Schema validation: 417 exact configs passed; SDK/schema synchronization and git diff --check passed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 30c4f940-9c8e-4d3e-89ff-b1776045bb1c Generated-with: gpt-6.1-sol

This PR keeps the existing SDK serde support while legacy binding callers remain active. The private parser again reuses SDK policy types directly, avoiding the filesystem, network, UI, and denial-capture mirror models that would otherwise be added only to be removed by cleanup. Details * Restore the authoring derives and wire attributes needed by the existing private request path through A, B, and C. * Remove new mirror policy types and conversions while retaining earlier backend-specific adapters whose private shapes differ from SDK types. Tests * cargo test -p mxc_ffi --lib -- request::tests: 22 passed. * cargo test -p mxc_engine --lib -- policy::: 42 passed. * SDK/FFI formatting and git diff --check passed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 30c4f940-9c8e-4d3e-89ff-b1776045bb1c Generated-with: gpt-6.1-sol

Copilot

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 1 · 1 · 1

Open (3)

resolve_runner_for_audit is #[cfg(target_os = \"windows\")], but this test calls it… · New
This test asserts the full formatted error string including {shared_error}’s Display output.… · New
Rustdoc intra-doc links typically use the item name without parentheses ([run]). Using… · New

Resolved since last review (4)

Migrate Node and .NET bindings to typed run/spawn configuration
Exclude ignored authorization flags from production policy hashes
Mark SDK emitted-JSON equality tests as planned follow-up coverage
Clarify Node and .NET one-shot migration remains incomplete

This PR clarifies how typed SDK requests and exact JSON reach the same normalized execution request, and moves experimental backend classification from the shared model into an engine-owned registration table. Details * Restore the versioning big picture and document staged native ingress. * Rename the Rust fixture harness to SDK conformance, explain its independent expected documents and test-only access to private request internals. * Register all backends in the engine, retaining explicit authorization classification and existing host-probe and dispatch behavior. Tests * cargo fmt --all -- --check; cargo check --workspace --all-targets --all-features; cargo clippy --workspace --all-targets --all-features -- -D warnings: passed. * cargo test -p mxc_engine -p mxc_ffi -p mxc-sdk -p wxc_common --all-features: passed. * Default-feature all-target Linux and macOS SDK/engine/FFI checks passed. * RUSTDOCFLAGS=-D warnings cargo doc -p mxc_engine -p mxc_ffi -p mxc-sdk --all-features --no-deps: passed. * node scripts/versioning/validate-configs.js: 417 configs validated. * Native Linux/macOS and live host-dependent suites were not run. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 30c4f940-9c8e-4d3e-89ff-b1776045bb1c Generated-with: gpt-6-sol

Copilot

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 1 · 1

Open (2)

resolve_runner_for_audit is #[cfg(target_os = \"windows\")], but this test references it… · New
The assert_eq!(error.message, format!(\"failed to build request: {shared_error}\")) assertion… · New

Resolved since last review (3)

resolve_runner_for_audit is #[cfg(target_os = \"windows\")], but this test calls it…
This test asserts the full formatted error string including {shared_error}’s Display output.…
Rustdoc intra-doc links typically use the item name without parentheses ([run]). Using…

Copilot

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 2 · 1

Open (3)

resolve_runner_for_audit is declared behind #[cfg(target_os = \"windows\")], but this test (as… · New
resolve_runner_for_audit is #[cfg(target_os = \"windows\")], but this test references it…
The assert_eq!(error.message, format!(\"failed to build request: {shared_error}\")) assertion…

Jeff Whiteside (jsidewhite)

This PR adds a handoff for the v1 SDK and JSON-only FFI ingress stack and updates the ingress plan to match what was built. It records the pull requests, branches, worktrees, and backups, the design decisions and their reasons, review status, open items, and working notes for a new session. Details * Add docs/version-aware-stack-session-handoff-2026-09-30.md covering #1271, #1348, and #1349-#1353, the backend-based experimental opt-in, JSON-only ingress, V1 namespaces and MxcPlatform, the pinned SDK target, Node export conditions, shared goldens, and E0. * Mark the plan adopted, replace the planned branch table with the opened pull requests, record the unified experimental check, the serde removal, the V1 writer location, and E0, and add the namespace, goldens, and E0 decisions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 33217f7b-dc7d-4da0-af5f-018fef64013c Generated-with: claude-opus-5.5

Gudge (MGudgin) force-pushed the user/gudge/rust_ffi_json_ingress branch from 48e32ec to 08b1f91 Compare September 30, 2026 16:33

This was referenced Sep 30, 2026

Switch Node to exact JSON FFI ingress #1350

Merged

Switch .NET to exact JSON FFI ingress #1351

Merged

Remove the binding request FFI exports #1352

Merged

Gudge (MGudgin) force-pushed the user/gudge/rust_ffi_json_ingress branch from 08b1f91 to 8f5133c Compare September 30, 2026 17:18

Gudge (MGudgin) force-pushed the user/gudge/rust_ffi_json_ingress branch from 8f5133c to c3bb09e Compare September 30, 2026 17:27

Gudge (MGudgin) changed the base branch from user/gudge/rust-sdk-phase14c to user/gudge/sdk-v1-namespaces September 30, 2026 20:19

Gudge (MGudgin) force-pushed the user/gudge/rust_ffi_json_ingress branch from c3bb09e to 6aa09b2 Compare September 30, 2026 20:29

Gudge (MGudgin) force-pushed the user/gudge/rust_ffi_json_ingress branch from 6aa09b2 to 1e5d971 Compare September 30, 2026 20:31

Gudge (MGudgin) added this pull request to stack #1356 September 30, 2026 21:26

Gudge (MGudgin) marked this pull request as ready for review September 30, 2026 21:27

Gudge (MGudgin) requested review from a team and a balanced review from Copilot September 30, 2026 21:27

Gudge (MGudgin) requested a review from a team as a code owner September 30, 2026 21:27

Copilot started reviewing on behalf of Gudge (MGudgin) September 30, 2026 21:28 View session

Gudge (MGudgin) force-pushed the user/gudge/rust_ffi_json_ingress branch from 1e5d971 to 3477383 Compare September 30, 2026 21:30

Copilot AI reviewed Sep 30, 2026

View reviewed changes

Comment thread src/core/mxc_engine/src/lib.rs

Comment thread docs/versioning.md Outdated

Comment thread tests/policy/README.md Outdated

Copilot AI balanced review requested due to automatic review settings September 30, 2026 21:32

Copilot started reviewing on behalf of Gudge (MGudgin) September 30, 2026 21:32 View session

Copilot AI reviewed Sep 30, 2026

View reviewed changes

Comment thread src/ffi/mxc_ffi/src/request.rs Outdated