[docs] Glossary + simplify doc terms by jsidewhite · Pull Request #1454 · microsoft/mxc

Jeff Whiteside (jsidewhite) · 2026-10-08T21:14:34Z

Adds glossary.

Terminology
In consumer-targeted docs, don't use weird-vague terms. (In internal developer docs - OK.)

Stop using,

"closed" (to mean 'predefined') and "pinned" (to mean 'restricted')
"exact contract"
"one-shot"
"state-aware"
"wire-format"

Use specific format names, not "raw JSON".

Don't use garbled mojibake characters in .rs files (e.g. "â€").

Microsoft Reviewers: Open in CodeFlow

Adds glossary. Terminology In consumer-targeted docs, don't use weird-vague terms. (In internal developer docs - OK.) Stop using, - "closed" (to mean 'predefined') and "pinned" (to mean 'restricted') - "exact contract" - "one-shot" - "state-aware" - "wire-format" Use specific format names, not "raw JSON". Don't use garbled mojibake characters in .rs files (e.g. "â€").

Copilot

🟡 Changes recommended

The new glossary and WSLc documentation contain inaccurate definitions, contradictory wording, and several grammatical errors.

7 open findings

Clarify the required development contract version · New
Add the missing relative pronoun · New
Complete the container definition · New
Remove deprecated one-shot terminology · New
Distinguish request JSON from its schema · New
Correct captured and streaming output timing definitions · New
Fix subject-verb agreement in SDK sentence · New

What changed in this PR

Adds consumer/developer glossaries and simplifies terminology across SDK and backend documentation.

Changes:

Defines preferred consumer and internal terminology.
Replaces ambiguous lifecycle, contract, and JSON wording.
Removes mojibake from Rust documentation.

File	Description
`src/mxc-sdk/src/telemetry.rs`	Clarifies serialized telemetry values.
`src/mxc-sdk/src/sandbox.rs`	Fixes mojibake and lifecycle wording.
`src/mxc-sdk/src/policy.rs`	Renames execution concepts in API docs.
`src/mxc-sdk/src/lib.rs`	Updates crate and FFI documentation.
`src/mxc-sdk/src/core/mxc_engine/probe.rs`	Clarifies backend identifiers.
`src/mxc-sdk/src/core/mxc_engine/platform.rs`	Clarifies containment values and link.
`src/mxc-sdk/src/core/mxc_engine/error.rs`	Simplifies error documentation.
`src/mxc-sdk/README.md`	Links glossary and updates PTY terminology.
`sdk/node/README.md`	Updates contract and lifecycle terminology.
`sdk/dotnet/README.md`	Updates contract and type terminology.
`samples/run-with-containment-of-network/README.md`	Clarifies deny-all networking.
`samples/README.md`	Names MXC request JSON explicitly.
`README.md`	Updates lifecycle terminology and documentation links.
`docs/schema.md`	Defines MXC request JSON and revises lifecycle guidance.
`docs/logging-access-denied.md`	Replaces “closed” terminology.
`docs/glossary.md`	Adds the consumer glossary.
`docs/development/README.md`	Links the developer glossary.
`docs/development/glossary.md`	Adds internal wording guidance.
`docs/development/architecture/versioning.md`	Distinguishes typed inputs from request JSON.
`docs/development/architecture/repository-architecture.md`	Clarifies manual lifecycle operations.
`docs/development/architecture/container-lifecycle.md`	Revises JSON and lifecycle terminology.
`docs/container-lifecycle.md`	Simplifies the consumer lifecycle guide.
`docs/backends/wslc/wslc-state-aware.md`	Rewords WSLc lifecycle documentation.
`docs/backends/wslc/wsl-container-getting-started.md`	Updates WSLc execution terminology.
`docs/backends/windows-sandbox/windows-sandbox.md`	Renames execution modes.
`docs/backends/windows-sandbox/windows-sandbox-reference.md`	Updates lifecycle reference terminology.
`docs/backends/seatbelt/seatbelt-backend.md`	Clarifies parsing language.
`docs/backends/process-container/UIPolicy_Schema.md`	Rewords version selection.
`docs/backends/process-container/networking.md`	Simplifies contract terminology.
`docs/backends/lxc/lxc-backend.md`	Updates networking and lifecycle wording.
`docs/backends/hyperlight/hyperlight-backend.md`	Rewords dependency version selection.
`docs/backends/bwrap/bubblewrap-backend.md`	Updates contract, proxy, and lifecycle wording.
`docs/api-reference/rust/v1/types.md`	Rewords predefined Rust types.
`docs/api-reference/rust/v1/api.md`	Updates PTY terminology.
`docs/api-reference/README.md`	Clarifies SDK inputs and links glossary.
`docs/api-reference/node/v1/types.md`	Updates Node type descriptions.
`docs/api-reference/node/v1/api.md`	Clarifies Node JSON and lifecycle APIs.
`docs/api-reference/dotnet/v1/types.md`	Updates .NET type descriptions.
`docs/api-reference/dotnet/v1/api.md`	Clarifies .NET JSON and lifecycle APIs.

🧠 Review effort: Balanced

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

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

🔵 Needs a closer look

The new glossary contains malformed and inaccurate definitions, and several Node references incorrectly limit SDK errors to native-runtime failures.

6 open findings

Fix subject-verb agreement in SDK sentence
Correct captured and streaming output timing definitions
Remove deprecated one-shot terminology
Complete the container definition
Add the missing relative pronoun
Clarify the required development contract version

1 resolved since last review

Distinguish request JSON from its schema

Previously missed (4)

In code that hasn't changed since last review

Avoid limiting helper codes to native-runtime errors

docs/api-reference/node/v1/api.md:101

This public helper is also used to create SDK-side validation errors (for example, malformed container IDs in sdk/node/src/state-aware-helper.ts:56-72), and its string parameter intentionally accepts unknown codes. Calling the input a native-runtime code is therefore too narrow.

Include SDK-side validation errors in the error code scope

docs/api-reference/node/v1/types.md:240

These codes are not limited to native-runtime failures. The Node SDK also uses this union for SDK-side request and option validation before calling native code (for example, sdk/node/src/v1/container.ts:336-341).

Document MxcError for SDK validation and binding failures

docs/api-reference/node/v1/types.md:410

MxcError is also thrown directly for SDK-side validation and binding failures, so describing it only as a response to native JSON excludes common documented behavior. For example, containerConfig constructs it before native execution (sdk/node/src/v1/container.ts:336-341).

Distinguish policies from backend configuration

docs/glossary.md:12

Policy and config are distinct concepts in the SDK: policies are cross-backend restrictions, while backend configuration contains settings such as a WSLc image (sdk/node/README.md:190-192). Combining them here incorrectly defines all configuration as access rules.

This issue also appears on line 22 of the same file.

🧠 Review effort: Balanced

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Clarify the explanation of failure classification and error handling in WSLc. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Updated comment to clarify usage of camelCase in result field. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Clarified the definition of 'Container' in the glossary. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

🔵 Needs a closer look

The new glossary and API wording contain malformed or inaccurate definitions and reintroduce the discouraged “one-shot” term.

0 open findings

6 resolved since last review

Fix subject-verb agreement in SDK sentence
Correct captured and streaming output timing definitions
Remove deprecated one-shot terminology
Complete the container definition
Add the missing relative pronoun
Clarify the required development contract version

Previously missed (2)

In code that hasn't changed since last review

Avoid claiming all MxcError values originate from native JSON

docs/api-reference/node/v1/types.md:410

Not every MxcError is produced from JSON: local SDK validation constructs this type directly, and most native calls map the FFI status plus MxcErrorDetail. Describing all instances as responses to a native JSON object is therefore inaccurate.

This issue also appears on line 428 of the same file.

Clarify foreground exit and descendant cleanup guarantees

src/mxc-sdk/src/sandbox.rs:226

This sentence is incomplete: “confirms that process” does not say what is confirmed, and the singular descendant wording obscures the cleanup guarantee. State explicitly that the foreground process is confirmed gone and that backgrounded descendants are reclaimed later.

🧠 Review effort: Balanced

Copilot

🔵 Needs a closer look

The new consumer glossary contains inaccurate lifecycle, streaming, opaque-ID, and host-loopback definitions.

0 open findings

Previously missed (4)

In code that hasn't changed since last review

Distinguish configuration from access policy

docs/glossary.md:12

config is broader than policy: MXC configuration also carries the workload, containment selection, runtime settings, and other non-access fields. Treating the terms as synonyms gives consumers an incorrect definition; split them into separate entries.

Clarify valid handling of persisted container identifiers

docs/glossary.md:17

“Never construct it” conflicts with the public SDKs: Rust exposes ContainerId::parse, and .NET exposes new ContainerId(string) specifically to restore a persisted identifier. Consumers must not fabricate or interpret the value, but they may need to wrap the unchanged returned string after persistence.

Distinguish live streams from captured output

docs/glossary.md:20

The streaming definition conflates captured output (“collected after completion”) with live output. spawn returns readable streams that must be accessed before wait; captured execution instead returns stdout/stderr after completion. Define these as distinct delivery models.

Document host loopback as bidirectional access

docs/glossary.md:22

This defines host loopback as container-to-host only, but ingress.hostLoopback is explicitly bidirectional (docs/backends/process-container/networking.md:105 and docs/schema.md:113). Consumers could otherwise underestimate the access granted by "allow".

🧠 Review effort: Balanced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 20145d41-b4e8-4801-b041-2e7058dad1e8

Copilot

🔵 Needs a closer look

The new glossary contains inaccurate I/O definitions and retains ambiguous terminology the PR intends to remove.

0 open findings

Previously missed (2)

In code that hasn't changed since last review

Split policy and config glossary definitions

docs/glossary.md:12

Policy and config are not synonyms: a ContainerRequest configuration also carries the workload command, containment/backend settings, working directory, and environment. Defining both as access rules makes the new glossary misleading; split the terms so config retains its broader meaning.

Use the defined MXC request JSON terminology

sdk/node/README.md:74

executor JSON configuration introduces another undefined name for the format and prevents readers from connecting this statement to the glossary and schema guide. Use the defined “MXC request JSON” name, as the PR description requires for consumer documentation.

🧠 Review effort: Balanced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 20145d41-b4e8-4801-b041-2e7058dad1e8

Copilot

🟡 Changes recommended

The new glossary and Node reference contain factual inaccuracies about lifecycle cleanup, streaming output, host-loopback directionality, and error origins.

7 open findings

Avoid implying error codes originate in native execution · New
Distinguish SDK validation codes from native runtime codes · New
Document all MxcError construction paths · New
Separate policy from broader SDK configuration · New
Do not conflate create-and-run with transient execution · New
Distinguish buffered output from live process streams · New
Document hostLoopback as bidirectional connectivity · New

🧠 Review effort: Balanced

 ## `@microsoft/mxc-sdk/v1::mxcErrorFromCode`

-Constructs an MxcError from a wire-format error code.
+Constructs an `MxcError` from a native runtime error code.


 ## `@microsoft/mxc-sdk/v1::ErrorCode`

-Closed set of MXC wire-format error codes.
+The SDK-defined set of MXC native runtime error codes.


 ## `@microsoft/mxc-sdk/v1::MxcError`

-Typed error thrown by the MXC SDK in response to a wire-format error envelope.
+Typed error thrown by the MXC SDK in response to a native JSON error object.


+| Container | Isolated environment in which a command or program runs. | Process isolation, Linux container, user session, or VM. |
+| Backend | MXC implementation of a container technology. | Bubblewrap on Linux. |
+| Workload | Command or program running inside the container. | `node -e "console.log('hello')"` |
+| Policy / config | Access rules enforced by the container. | `FilesystemPolicy`: readable, writable, and denied paths. |


+| Backend | MXC implementation of a container technology. | Bubblewrap on Linux. |
+| Workload | Command or program running inside the container. | `node -e "console.log('hello')"` |
+| Policy / config | Access rules enforced by the container. | `FilesystemPolicy`: readable, writable, and denied paths. |
+| **Create-and-run** \(transient\) | Setup, execute, and cleanup all in "one-shot". | Node V1 `run` or `spawn`. |


+| **\[I\/O model\]** Captured | Full output emitted after program execution. | Node V1 `run`. |
+| **\[I\/O model\]** Streaming output | Output collected after completion / readable during execution. | Node V1 `spawn`. |


+| **\[I\/O model\]** Captured | Full output emitted after program execution. | Node V1 `run`. |
+| **\[I\/O model\]** Streaming output | Output collected after completion / readable during execution. | Node V1 `spawn`. |
+| **\[I\/O model\]** PTY (pseudoterminal) | Interactive terminal with input, combined output, and resizing. | Node V1 `spawnWithPty`. |
+| **\[Networking\]** Host loopback | Container-to-host loopback communication, not access from other machines. | `network.ingress.hostLoopback`. |


Branden Bonaby (bbonaby) · 2026-10-09T17:20:39Z

-in this API use the owned V1 contract rather than exposing a wire-version
-selector.
+in this API use the SDK-selected contract version; callers do not select
+that version. See the [consumer glossary](../../docs/glossary.md) for terminology.


note: can you tell the bot to update all links in the sdk README.md's to the full link from github main and to have it remove any stale links? I think this one will go to a 404 page if clicked from nuget.org.

Copilot

🔵 Needs a closer look

The new glossary contains inaccurate definitions and retired terminology, while several guides still use ambiguous format and contract wording.

7 open findings

Previously missed (3)

In code that hasn't changed since last review

Refer to the version-specific contract parser, not the schema

docs/backends/wslc/wsl-container-getting-started.md:450

The rejection is performed by the version-specific contract parser, not by the schema artifact. Calling this “schema 0.9.0-alpha” conflicts with the terminology rule introduced in this PR to reserve “schema” for a contract's JSON description.

Describe contract parser and backend validation behavior

docs/backends/wslc/wslc-state-aware.md:209

This is contract behavior, not schema behavior: the contract parser and backend validation determine which networking combinations are accepted. The new developer glossary explicitly reserves “schema” for the JSON description of a contract.

Name the specific JSON interface format

docs/container-lifecycle.md:5

“Native JSON format” is not a defined format name and leaves readers guessing which interface the link describes. Name the owning interface, consistent with the new wording guide's requirement to use explicit format names.

This issue also appears on line 11 of the same file.

🧠 Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings October 8, 2026 21:14

Jeff Whiteside (jsidewhite) requested a review from a team as a code owner October 8, 2026 21:14

Copilot started reviewing on behalf of Jeff Whiteside (jsidewhite) October 8, 2026 21:15 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Jeff Whiteside (jsidewhite) requested review from Gudge (MGudgin) and Branden Bonaby (bbonaby) October 8, 2026 21:18

Update MXC request JSON description and link

1be05cb

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

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

Copilot started reviewing on behalf of Jeff Whiteside (jsidewhite) October 8, 2026 21:22 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Clarify requirements for development contract version

882787a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 8, 2026 21:34

Copilot started reviewing on behalf of Jeff Whiteside (jsidewhite) October 8, 2026 21:35 View session

Jeff Whiteside (jsidewhite) and others added 3 commits October 8, 2026 14:36

Improve documentation on WSLc failure phases

f578bbf

Clarify the explanation of failure classification and error handling in WSLc. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Refactor comment for ConsentActionResult

f00083a

Updated comment to clarify usage of camelCase in result field. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Update definition of 'Container' in glossary

fdee69c

Clarified the definition of 'Container' in the glossary. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 8, 2026 21:38

Copilot started reviewing on behalf of Jeff Whiteside (jsidewhite) October 8, 2026 21:38 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Jeff Whiteside (jsidewhite) and others added 2 commits October 8, 2026 14:50

user/jwhites/mxc_pseudoconsole_support in OS for now

6111ce8

Merge remote updates into jsidewhite/mxc_docs4.5SQ

ebe5ca5

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 20145d41-b4e8-4801-b041-2e7058dad1e8

Copilot AI balanced review requested due to automatic review settings October 8, 2026 21:54

microsoft-github-policy-service Bot added the Copilot-Instructions label Oct 8, 2026

Copilot started reviewing on behalf of Jeff Whiteside (jsidewhite) October 8, 2026 21:54 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Merge origin/main into jsidewhite/mxc_docs4.5SQ

b5e77e0

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 20145d41-b4e8-4801-b041-2e7058dad1e8

Copilot AI balanced review requested due to automatic review settings October 8, 2026 22:16

Copilot started reviewing on behalf of Jeff Whiteside (jsidewhite) October 8, 2026 22:17 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Branden Bonaby (bbonaby) reviewed Oct 9, 2026

View reviewed changes

editws

1490dbd

Copilot AI balanced review requested due to automatic review settings October 9, 2026 18:44

Copilot started reviewing on behalf of Jeff Whiteside (jsidewhite) October 9, 2026 18:44 View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Branden Bonaby (bbonaby) approved these changes Oct 9, 2026

View reviewed changes

Jeff Whiteside (jsidewhite) merged commit c6f301d into main Oct 9, 2026
31 checks passed

Jeff Whiteside (jsidewhite) deleted the jsidewhite/mxc_docs4.5SQ branch October 9, 2026 21:35

Navigation Menu

Repository navigation

[docs] Glossary + simplify doc terms - #1454

[docs] Glossary + simplify doc terms#1454
Jeff Whiteside (jsidewhite) merged 10 commits into
mainfrom
jsidewhite/mxc_docs4.5SQ

Jeff Whiteside (jsidewhite) commented Oct 8, 2026 •

edited by microsoft-github-policy-service Bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Branden Bonaby (bbonaby) Oct 9, 2026 •

edited

Loading

Uh oh!

Jeff Whiteside (jsidewhite) Oct 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		\| \[I\/O model\] Captured \| Full output emitted after program execution. \| Node V1 `run`. \|
		\| \[I\/O model\] Streaming output \| Output collected after completion / readable during execution. \| Node V1 `spawn`. \|

Conversation

Jeff Whiteside (jsidewhite) commented Oct 8, 2026 • edited by microsoft-github-policy-service Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Microsoft Reviewers: Open in CodeFlow

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Branden Bonaby (bbonaby) Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jeff Whiteside (jsidewhite) Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Jeff Whiteside (jsidewhite) commented Oct 8, 2026 •

edited by microsoft-github-policy-service Bot

Loading

Branden Bonaby (bbonaby) Oct 9, 2026 •

edited

Loading