Document supported containment policy contracts by MGudgin · Pull Request #1416 · microsoft/mxc

Gudge (MGudgin) · 2026-10-06T20:33:41Z

This PR adds policy-first documentation for the published 0.9.0-alpha and
1.0.0 contracts and the V1 development contract. It explains how policy
is authored through typed SDKs or MXC request JSON, what each backend can
enforce, and how container lifecycle operations behave.

Details

Add versioned guides linked from repository and subsystem documentation.
Describe network, filesystem, and UI policy, backend-specific handling,
and container lifecycle identity and recovery semantics.
Replace generic sandbox terms with container/workload in documentation
and test diagnostics, preserving product names and API/wire identifiers.

Tests

cargo fmt --manifest-path src\Cargo.toml --all -- --check passed.
cargo check --manifest-path src\Cargo.toml --workspace --all-targets --quiet passed.
node - parsed 15 TypeScript examples; python - checked JSON examples,
Markdown links, and registered contract shapes.
git diff --check origin/main...HEAD passed. Backend runtime suites were
not run (documentation and wording changes).

Microsoft Reviewers: Open in CodeFlow

azure-pipelines · 2026-10-06T20:33:51Z

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

Copilot

Copilot review overview

🟡 Changes recommended

The new contract pages misstate cross-platform containment defaults, WSLC proxy requirements, and the abstract vm selection.

Review effort: Balanced
Findings: 3

Open (3)

Correct the documented default containment behavior · New
Document host-native default containment resolution · New
Clarify platform resolution of abstract vm containment · New

What changed in this PR

Documents supported sandbox policy contracts and replaces retired policy references without runtime changes.

Changes:

Adds contract documentation for 0.9, 1.0, and development 1.1.
Removes retired 0.7/0.8 documentation.
Updates SDK, backend, and test references.

File	Description
`tests/scripts/run_lxc_network_no_network_test.sh`	Updates contract references.
`tests/scripts/lib/WinProcessContainer.Common.ps1`	Updates networking reference.
`src/mxc-sdk/src/core/mxc_common/network_parser_ingress_default_tests.rs`	Updates test documentation.
`src/mxc-sdk/src/backends/bubblewrap/common/network_rules.rs`	Updates policy citation.
`sdk/node/README.md`	Links stable policy.
`sdk/dotnet/README.md`	Links stable policy.
`README.md`	Links policy index.
`docs/seatbelt/seatbelt-backend.md`	Updates policy guidance.
`docs/schema.md`	Introduces versioned policy documentation.
`docs/sandbox-policy/README.md`	Adds supported-contract index.
`docs/sandbox-policy/1.1.0/policy.md`	Documents development contract.
`docs/sandbox-policy/1.0.0/policy.md`	Documents stable contract.
`docs/sandbox-policy/0.9.0/policy.md`	Documents minimum supported contract.
`docs/sandbox-policy/0.8.0/policy.md`	Removes retired policy.
`docs/sandbox-policy/0.8.0/networking/schema-updates.md`	Removes retired migration document.
`docs/sandbox-policy/0.8.0/networking/networking.md`	Removes retired networking design.
`docs/sandbox-policy/0.7.0/policy.md`	Removes retired policy.
`docs/process-container/os-version-support.md`	Updates stable-policy link.
`docs/process-container/networking.md`	Updates shared-policy references.
`docs/process-container/guide.md`	Updates prerequisites and legacy guidance.
`docs/process-container/examples/0.8.0-schema.md`	Redirects historical guidance.
`docs/examples.md`	Updates networking references.
`docs/authoring-a-new-feature.md`	Updates authoring references.

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

Copilot

Copilot review overview

🟢 Approval recommended

The documentation accurately reflects the registered exact contracts and removes stale references without affecting code behavior.

Review effort: Balanced
Findings: None

Resolved since last review (3)

Clarify platform resolution of abstract vm containment
Document host-native default containment resolution
Correct the documented default containment behavior

Copilot

Copilot review overview

🟢 Approval recommended

The documentation matches the registered exact contracts, and obsolete references were consistently removed.

Review effort: Balanced
Findings: None

Copilot

Copilot review overview

🟡 Changes recommended

The development policy omits that vm requests on Windows require experimental authorization.

Review effort: Balanced
Findings: 1

Open (1)

Document Windows vm authorization in runtime gate guidance · New

Copilot

Copilot review overview

🟡 Changes recommended

The 1.1 guide incorrectly states that vm resolves to Windows Sandbox, while runtime dispatch rejects it as unimplemented.

Review effort: Balanced
Findings: 2

Open (2)

Correct Windows resolution claim for unsupported VM backend · New
Document Windows vm authorization in runtime gate guidance

Copilot

🟢 Approval recommended

The documentation matches the registered exact contracts, parser defaults, SDK target, and backend validation behavior.

2 open findings

Correct Windows resolution claim for unsupported VM backend
Document Windows vm authorization in runtime gate guidance

🧠 Review effort: Balanced

Copilot

🟢 Approval recommended

The documentation matches the registered contracts and SDK surfaces, and the remaining changes are terminology-only.

0 open findings

5 resolved since last review

🧠 Review effort: Balanced

Copilot

🟡 Changes recommended

The lifecycle architecture still documents unsupported Node AbortSignal and SandboxSpawnOptions APIs.

1 open finding

Correct SDK summary to document supported options and cancellation · New

🧠 Review effort: Balanced

Copilot

🟡 Changes recommended

The stable policy guide omits a port-range constraint and overstates LXC egress enforcement despite its documented raw-socket bypass.

2 open findings

1 resolved since last review

Correct SDK summary to document supported options and cancellation

🧠 Review effort: Balanced

Copilot

🟢 Approval recommended

The documentation matches the registered contracts, SDK surfaces, and current backend validation behavior.

0 open findings

2 resolved since last review

🧠 Review effort: Balanced

Copilot

🟡 Changes recommended

The WSLC loopback guarantee and several contract and lifecycle statements do not match runtime behavior.

3 open findings

🧠 Review effort: Balanced

This PR adds policy-first documentation for the published 0.9.0-alpha and 1.0.0 contracts and the V1 development contract. It explains how policy is authored through typed SDKs or MXC request JSON, what each backend can enforce, and how container lifecycle operations behave. Details * Add versioned guides linked from repository and subsystem documentation. * Describe network, filesystem, and UI policy, backend-specific handling, and container lifecycle identity and recovery semantics. * Replace generic sandbox terms with container/workload in documentation and test diagnostics, preserving product names and API/wire identifiers. Tests * `cargo fmt --manifest-path src\Cargo.toml --all -- --check` passed. * `cargo check --manifest-path src\Cargo.toml --workspace --all-targets --quiet` passed. * `node -` parsed 15 TypeScript examples; `python -` checked JSON examples, Markdown links, and registered contract shapes. * `git diff --check origin/main...HEAD` passed. Backend runtime suites were not run (documentation and wording changes). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a30a59a8-e257-4e4b-9995-762f3611dabe 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

4 open findings

This wire-contract interface omits wslc.provision.portMappings, but later text in the same… · New
This paragraph claims WSLC port mappings are 'illustrated here', but the nearby TypeScript… · New
Within this document, the typed SDK identifier is consistently called ContainerId, but the… · New
This sentence appears to have lost its punctuation when the trailing ; was removed from the… · New

3 resolved since last review

🧠 Review effort: Lite

 interface ProvisionStateAwareRequest {
  phase: 'provision';                             // discriminator
  version: '1.0.0';
-  containment: StateAwareContainmentBackend;
+  containment: LifecycleContainmentKind;
  filesystem?: FilesystemConfig;                  // backend declares per-phase honor
  network?: NetworkConfig;                        // backend declares per-phase honor
  ui?: UiConfig;                                  // backend declares per-phase honor
  isolationSession?: {
    provision?: { appId?: string };
  };
  wslc?: {
-    provision?: { image?: string; imageTarPath?: string; portMappings?: PortMapping[] };
+    provision?: { image?: string; imageTarPath?: string };
  };
 }


 Backend-specific configuration uses each backend's permanent top-level JSON
-section. The SDK builds these sections internally from the per-(backend, phase)
-Configs defined in §6.1:
+section. The SDK maps its per-(backend, phase) Configs to the published
+fields; raw `1.1.0-alpha` JSON also accepts the WSLC port mappings illustrated
+here:


 All types above are in `Microsoft.Mxc.Sdk.V1`. See the
-[networking guide](https://github.com/microsoft/mxc/blob/main/docs/schema.md#directional-networking-supported-contracts);
+[networking guide](https://github.com/microsoft/mxc/blob/main/docs/schema.md#directional-networking-supported-contracts)
 for policy behavior and the
 [SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/api-reference/README.md)


Copilot

🟡 Changes recommended

The lifecycle error table incorrectly assigns unsupported_containment to provision failures.

4 open findings

Align error classification for unsupported provision containment · New
This paragraph claims WSLC port mappings are 'illustrated here', but the nearby TypeScript…
This wire-contract interface omits wslc.provision.portMappings, but later text in the same…
This sentence appears to have lost its punctuation when the trailing ; was removed from the…

1 resolved since last review

Within this document, the typed SDK identifier is consistently called ContainerId, but the…

🧠 Review effort: Balanced

 |---|---|
 | `malformed_request` | Structural request error: malformed JSON, missing required field, unknown or phase-inappropriate field, recursively unknown backend-specific field, or invalid phase-specific shape |
-| `unsupported_containment` | The backend named by `containment` (provision) or implied by a syntactically valid `sandboxId` prefix (non-provision) is not recognised in this build. The TypeScript SDK checks its closed prefix union before dispatch and instead throws `malformed_id`; the typed Rust SDK keeps ids opaque and therefore returns `unsupported_containment` from dispatch, matching raw FFI requests. See §6.4. |
+| `unsupported_containment` | The backend named by `containment` (provision) or implied by a syntactically valid `sandboxId` prefix (non-provision) is unsupported by the selected API or build. The TypeScript SDK reports an unknown prefix as `malformed_id`, but reports the recognised experimental Windows Sandbox `wsb:` prefix as `unsupported_containment` on V1; typed Rust and raw FFI dispatch also use `unsupported_containment` for unrecognised prefixes. See §5. |


Gudge (MGudgin) · 2026-10-12T16:55:59Z

Not converging

Gudge (MGudgin) requested a review from a team as a code owner October 6, 2026 20:33

Copilot AI balanced review requested due to automatic review settings October 6, 2026 20:33

Copilot started reviewing on behalf of Gudge (MGudgin) October 6, 2026 20:34

View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Comment thread docs/sandbox-policy/0.9.0/policy.md Outdated

Comment thread docs/sandbox-policy/1.0.0/policy.md Outdated

Comment thread docs/sandbox-policy/1.1.0/policy.md Outdated

Copilot AI balanced review requested due to automatic review settings October 6, 2026 20:56

Copilot started reviewing on behalf of Gudge (MGudgin) October 6, 2026 20:57

View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 6, 2026 23:04

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from c9fdfe7 to 88cd785 Compare October 6, 2026 23:04

Copilot started reviewing on behalf of Gudge (MGudgin) October 6, 2026 23:05

View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 6, 2026 23:22

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from 88cd785 to 3678ee5 Compare October 6, 2026 23:22

Copilot started reviewing on behalf of Gudge (MGudgin) October 6, 2026 23:22

View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Comment thread docs/containment-configuration/1.1.0/policy.md Outdated

Branden Bonaby (bbonaby) reviewed Oct 6, 2026

View reviewed changes

Comment thread docs/development/guides/authoring-a-new-feature.md Outdated

Branden Bonaby (bbonaby) reviewed Oct 7, 2026

View reviewed changes

Comment thread docs/containment-configuration/1.1.0/policy.md Outdated

Branden Bonaby (bbonaby) mentioned this pull request Oct 7, 2026

Fix build break on Windows runner #1433

Merged

1 of 8 tasks

Branden Bonaby (bbonaby) reviewed Oct 7, 2026

View reviewed changes

Comment thread docs/containment-configuration/1.0.0/policy.md Outdated

Copilot AI balanced review requested due to automatic review settings October 7, 2026 02:35

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from 3678ee5 to f4fbf2d Compare October 7, 2026 02:35

Copilot started reviewing on behalf of Gudge (MGudgin) October 7, 2026 02:36

View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

Comment thread docs/containment-configuration/v1-dev/policy.md Outdated

Copilot AI balanced review requested due to automatic review settings October 7, 2026 15:42

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from f4fbf2d to 7e65507 Compare October 7, 2026 15:42

Copilot started reviewing on behalf of Gudge (MGudgin) October 7, 2026 15:42

View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 7, 2026 21:43

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from 7e65507 to 8318ad9 Compare October 7, 2026 21:43

Copilot AI balanced review requested due to automatic review settings October 9, 2026 19:51

Copilot started reviewing on behalf of Gudge (MGudgin) October 9, 2026 19:52

View session

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from 28fc82e to 9dd66cc Compare October 9, 2026 19:53

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 9, 2026 19:56

Copilot started reviewing on behalf of Gudge (MGudgin) October 9, 2026 19:57

View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Comment thread docs/development/architecture/container-lifecycle.md Outdated

Copilot AI balanced review requested due to automatic review settings October 9, 2026 20:27

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from 9dd66cc to eea54a7 Compare October 9, 2026 20:27

Copilot started reviewing on behalf of Gudge (MGudgin) October 9, 2026 20:28

View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Comment thread docs/containment-configuration/1.0.0/policy.md Outdated

Comment thread docs/containment-configuration/1.0.0/policy.md Outdated

Copilot AI balanced review requested due to automatic review settings October 9, 2026 20:35

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from eea54a7 to 775fbdb Compare October 9, 2026 20:35

Copilot started reviewing on behalf of Gudge (MGudgin) October 9, 2026 20:36

View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 12, 2026 14:57

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from 775fbdb to de23857 Compare October 12, 2026 14:57

Copilot started reviewing on behalf of Gudge (MGudgin) October 12, 2026 14:58

View session

Copilot AI reviewed Oct 12, 2026

View reviewed changes

Comment thread docs/containment-configuration/1.0.0/policy.md Outdated

Comment thread docs/containment-configuration/v1-dev/policy.md Outdated

Comment thread docs/development/architecture/container-lifecycle.md Outdated

Copilot AI balanced review requested due to automatic review settings October 12, 2026 16:10

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from de23857 to 5189e5d Compare October 12, 2026 16:10

Gudge (MGudgin) force-pushed the user/gudge/policy_docs branch from 5189e5d to f17ea42 Compare October 12, 2026 16:18

Copilot AI reviewed Oct 12, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 12, 2026 16:30

Copilot started reviewing on behalf of Gudge (MGudgin) October 12, 2026 16:31

View session

Copilot AI reviewed Oct 12, 2026

View reviewed changes

Gudge (MGudgin) closed this Oct 12, 2026

Gudge (MGudgin) deleted the user/gudge/policy_docs branch October 15, 2026 17:26

Conversation

Gudge (MGudgin) commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Details

Tests

Microsoft Reviewers: Open in CodeFlow

Uh oh!

azure-pipelines Bot commented Oct 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Gudge (MGudgin) commented Oct 6, 2026 •

edited

Loading