Audience: MXC developers
See the developer glossary for terms such as "exact contract," "wire format," and "request root."
Versioning determines which configuration contract is accepted, not which backend implementation runs or what the host can enforce. Keep these decisions separate:
| Decision | Authority |
|---|---|
| Which fields and values exist? | The exact Rust contract types and registration in mxc_contract. Published contracts are immutable; the development contract can evolve. |
| Which exact contract does a typed SDK emit? | sdkMajorTargets in schemas/schema-version.json, checked against the exact Rust registry. Callers select a major-version SDK API, not an exact JSON version. |
| Which contract does "MXC request JSON" use? | The caller's declared, registered version. A version range or development opt-in cannot authorize another spelling. |
| Which backend and policy can run? | mxc_engine resolves the backend and checks authorization; host capabilities and backend validation determine what can actually be enforced. |
Typed SDK inputs and "MXC request JSON" converge before backend execution:
flowchart LR
typed["Typed SDK policy or lifecycle request"]
target["SDK-owned published exact target"]
raw["'MXC request JSON' with caller-declared version"]
contract["Registered exact Rust contract"]
adapter["Version-specific adapter"]
normalized["Shared normalization<br/>ExecutionRequest and typed lifecycle operation"]
engine["Engine routing and authorization"]
backend["Host-capability validation and enforcement"]
typed --> target --> contract
raw --> contract
contract --> adapter --> normalized --> engine --> backend
Rust builders construct exact contract values in memory. Node and .NET exact writers serialize those values to JSON for the native boundary. In either case, version-specific adapters and shared normalization own the conversion to runtime requests; SDK policy types and generated schemas do not form another native configuration authority. The native-ingress section identifies the deprecated binding exceptions that remain while the migration is staged.
Publication, SDK targeting, and runtime authorization are independent:
opening 1.1.0-alpha does not change V1's published target, and accepting
that exact development contract does not grant experimental backend access.
Conversely, experimental authorization does not make a field legal in an
older contract or override backend policy validation.
The sections below distinguish the three version axes, contract shipping and parsing, SDK major targets, and backend authorization. Artifact regeneration belongs in Schema Code Generation; backend execution flow is covered by Architecture.
The policy (filesystem, network) expresses what the user wants — "block network, allow these paths." It does not specify how the OS enforces it, nor which container type to use.
Rust, .NET, and Node high-level one-shot policy and typed lifecycle APIs do not
take a caller-supplied schema version. Each v1 SDK targets the published exact
1.0.0 contract internally.
Raw configuration APIs require the caller to declare a registered version
to select an immutable published or mutable development contract.
The V1.Dev SDK APIs accept these documents.
Experimental backend authorization is supplied separately in invocation
options, not inferred from the document's version.
// sdk/node/src/types.ts
const policy: SandboxPolicy = {
filesystem: { ... },
network: { ... },
timeoutMs: 30000,
};The exact JSON emitted internally by a high-level v1 API carries the SDK-owned version:
{
"version": "1.0.0",
"process": { ... },
"filesystem": { ... },
"network": { ... }
}Contract-mapped SDK types live in a namespace for their schema-contract major:
Microsoft.Mxc.Sdk.V1, mxc_sdk::v1, and @microsoft/mxc-sdk/v1.
The typed V1 surface contains ContainerRequest, its policy sections,
containment selection and backend settings, and container lifecycle
request/result/option types and entry points. These typed APIs
evolve additively as published 1.x contracts grow; the SDK owns the exact
contract target (currently 1.0.0) and callers do not supply a schema version.
A future breaking schema line adds a side-by-side V2 namespace rather than
replacing V1. See Required V2 changes.
V1.Dev is a separate API family within the supported V1 entrypoint:
mxc_sdk::v1::dev, Microsoft.Mxc.Sdk.V1.Dev, and
@microsoft/mxc-sdk/v1/dev. Its callers declare a registered JSON contract
version instead of using the typed V1 target. The SDK API major and the
document's contract version are independent; Dev does not implicitly
select the development contract or authorize experimental backends.
Version-independent operations and types, including errors, process handles, output/wait types, discovery, and telemetry consent, use supported V* entrypoints.
SDK releases follow Semantic Versioning 2.0.0:
- Major (X.0.0): breaking public API or incompatible documented behavior changes.
- Minor (x.Y.0): backward-compatible API additions, newly exposed schema capabilities, or new behavior. Public API deprecations require at least a minor release.
- Patch (x.y.Z): backward-compatible bug fixes and internal refactoring, without new public APIs, schema capabilities, or feature behavior.
Correcting behavior to match the documented contract can be a patch; introducing an incompatible contract requires a major version. The highest required change determines the release version, including urgent out-of-cycle releases.
Features and fixes ship in new releases on the current release line; they are not backported to older release lines. Dependent projects must update to an SDK version that includes the change to receive it.
SDK package versions and schema versions are independent. Evaluate compatibility on each axis separately: changing a schema does not automatically bump an SDK package, and releasing an SDK does not automatically bump a schema. Published contracts remain immutable. See How MXC is managed for release cadence and milestone policy.
A development prerelease for the next minor must retain accepted fields from
the published major line. Retired settings such as fallback.allowDaclMutation
remain accepted and ignored in 1.x; removing their accepted JSON form requires
a new major contract, even when the setting no longer affects execution.
MXC tracks three independent "versions" that are deliberately never conflated. Each answers a different question and changes for different reasons:
| Axis | What it describes | Where it lives | Who decides it |
|---|---|---|---|
| Schema (config) version | The shape of the config JSON — which fields exist and what values they accept. | The version field in raw configuration; high-level SDK policy omits it. |
The raw-config author or, for high-level APIs, the SDK package. |
| Product version | The MXC binaries and Rust, Node, and .NET SDK packages. | Rust workspace version (src/Cargo.toml), sdk/node/package.json, and the .NET SDK project <Version>. |
The release. |
| Host capability | What the running OS can actually enforce (e.g. whether the BaseContainer sandbox API is usable, velocity keys, Hyper-V). | Negotiated at runtime — never a string in the config. | The host, probed at execution time. |
- Schema version selects an exact registered contract at the trust boundary:
0.9.0-alpha,1.0.0, or1.1.0-alpha. Patch and prerelease spelling are significant;0.6.1-alphaand0.8.0-devare not registered and are rejected. A missing declaration is rejected too. Raw SDK entry points enforce the same exact set. High-level v1 one-shot and state-aware APIs select stable1.0.0internally and expose only the backends supported by that contract. Capabilities the published contract does not declare — Windows Sandbox state-aware,wslc.provision.portMappings, and WSLc session operations (provision-session,deprovision-session, andwslc.provision.sessionId) — require MXC request JSON declaring1.1.0-alpha, or the in-process engine with that contract.stateAwareWslcnames this development contract; it does not change the published1.0.0target of the V1 SDKs. The compatibility constants inschemas/schema-version.jsondo not authorize other versions within their minimum/maximum range. - Product version tracks the shipped artifacts and moves independently of the
schema version; a binary release can fix bugs without changing the config shape.
The .NET packaging project passes the release's
PackageVersioninto its nuspec; the SDK project's<Version>supplies its managed assembly version. Windows binaries, includingmxc_ffi.dll, embed the product version and source commit in their version-resource metadata.scripts/check-version-sync.jskeeps the Rust workspace and npm versions in step, andscripts/versioning/check-schema-versions.jskeeps the schema-version constants in step — but the two axes are not tied to each other. - Host capability is resolved by runtime negotiation, not by a version string.
The schema
versiondoes not select the Windows backend: ProcessContainer requires native PSEC support for the complete policy (see Version Negotiation). An identical policy that is expressible in multiple registered contracts retains the same host-capability-driven backend selection.
mxc/schemas/
├── stable/
│ ├── mxc-config.schema.0.4.0-alpha.json (retired — below the supported floor)
│ ├── mxc-config.schema.0.5.0-alpha.json (retired — below the supported floor)
│ ├── mxc-config.schema.0.6.0-alpha.json (retired — below the supported floor)
│ ├── mxc-config.schema.0.7.0-alpha.json (retired — below the supported floor)
│ ├── mxc-config.schema.0.8.0-alpha.json (retired — below the supported floor)
│ ├── mxc-config.schema.0.9.0-alpha.json (minimum supported)
│ └── mxc-config.schema.1.0.0.json (shipped — current stable)
└── dev/
└── mxc-config.schema.1.1.0-alpha.json (exact closed development contract)
Published stable schemas remain immutable and cannot be removed, including
those below the supported floor (0.9.0-alpha). The parser rejects retired
versions even though their schema artifacts remain in the repository.
The development artifact is generated from the exact
mxc_contract::dev model. It describes all eight closed one-shot and
state-aware roots, including recursively closed experimental structures. The
registered Rust types remain the authority for declared 1.1.0-alpha
requests; the schema is their derived editor and validation artifact.
"MXC request JSON" is parsed with the registered contract named by its version
field. High-level Rust, .NET, and Node v1 builders do not accept a caller-supplied
schema version: they construct requests for exact 1.0.0 and reject fields or
backends outside that contract. Repository config validation selects the schema
matching each raw document's declared version.
Only the v1.1 prerelease file under schemas/dev/ is a generated development
artifact. Published v0.9 and v1.0 are represented by exact Rust contracts and
immutable stable schemas. Exact fixtures and adapter/runtime tests remain
ordinary mutable tests so they can gain regression coverage as implementations
evolve. See Schema Code Generation for the regeneration
commands and independent drift/history gates.
Exact development requests adapt directly to a StateAwareOperation and
cross-cutting ExecutionRequest. The operation determines its phase:
provision retains a backend tag and optional runtime configuration, while
start, exec, stop, and deprovision carry their required sandbox ID.
ParsedStateAwareRequest exposes read-only accessors, not independently
writable phase, containment, or payload fields. Successful production requests
retain neither raw backend JSON nor source text.
The engine resolves provision by containment and later phases by the sandbox
ID prefix. After the existing experimental and build-availability gates, its
checked binding helpers produce BoundStateAwareRequest<B> for both relayed
lifecycle dispatch and streaming exec. An incompatible operation/backend pair
is an error, never an absent configuration or a fallback to another backend.
The dispatcher borrows configuration for validation, then moves it into the
phase method. It does not deserialize backend payloads.
Configuration presence is preserved: absent provision configuration is None,
a present empty object is Some(Config { ...: None }), and an explicit empty
appId remains Some(""). Outer absent/empty backend sections that have the
same backend meaning need not survive. WSLC uses runtime-owned
models::WslcProvisionConfig; the backend still chooses an omitted image's
default. Top-level telemetry and network/UI presence flags remain in common
normalization. Source-aware errors remain at exact structural deserialization.
Exact fixtures cover structural acceptance and rejection, including
appId: null. Recording backends cover binding, configuration delivery,
validation order, dry-run behavior, and both exec topologies without requiring
live sandboxes.
Version-specific adapters convert registered JSON contract types into the
private CommonRequestIR intermediate representation. Shared normalization in
normalize_common_request_ir then validates and converts that representation
into the runtime ExecutionRequest; adapters do not perform this second stage.
ExecutionRequest.source_contract records the originating registered contract
for diagnostics and telemetry only. Direct typed SDK requests clear that
attribution after exact validation because they did not originate as external
configuration JSON.
Runtime behavior is selected from explicit normalized semantics rather than by comparing contract-version strings. Registered exact contracts and direct typed SDK requests use the same strict network enforcement. Retired pre-v0.9 contracts cannot select legacy enforcement behavior. Direct typed SDK construction clears only source-contract attribution; it does not weaken validation.
The published 0.9.0-alpha and 1.0.0 contracts accept the standard
directional all-allow posture for IsolationSession:
{
"egress": { "default": "allow" },
"ingress": { "default": "allow", "hostLoopback": "allow" }
}Legacy fields, rules, proxies, mixed postures, an empty network object, or
omission are errors. State-aware provision and one-shot exact request parsing
both require network structurally, so omission is rejected before backend
validation.
The policy continues through the ordinary cross-cutting network model and policy identity. No backend-specific acknowledgment field, transport, or hash projection is introduced.
The stable v0.9 and v1.0 schemas and TypeScript oracles are regenerated from their published Rust models and compared in CI. Exact fixture and adapter/runtime tests remain editable so regression coverage can grow without changing a published JSON contract.
The v1.0 contract preserves the v0.9 request roots and canonical field/value
spellings, but removes the legacy appcontainer, appContainer, and
macos_sandbox aliases. They remain rejected throughout the v1 contract line.
Features that exist only in mutable v1.1 development, including Windows Sandbox
provision, Seatbelt captureDenials, and the vm, microvm, and hyperlight
one-shot surfaces, are not accepted by v1.0.
Schemas in stable/ are immutable: they document the input shape that was
promised at release. They are not authoritative for runtime security
defaults. Native contract parsing and backend validation form the trust
boundary for both executor and library callers. Runtime enforcement may apply
stricter defaults than a stable schema declares when a security issue requires
it.
For example, an older stable schema may declare
network.defaultPolicy defaulting to "allow". The runtime may treat an
absent network.defaultPolicy as block regardless of the declared schema
version when the old default is a security bug. The older stable schema is
left unchanged so the release contract stays auditable; newer schemas
document the corrected default. Consumers that need the legacy behavior
must set the field explicitly.
The four Required events described in Telemetry apply
to 0.9.0-alpha, 1.0.0, and 1.1.0-alpha, including V1 SDK callers.
This intentionally replaces published contracts' optional-collection behavior:
request telemetry settings, consent withdrawal, and administrative policy no
longer suppress these events. Other telemetry events are excluded for these
contracts. Existing consent-management APIs and stored decisions are preserved.
This approved behavior change does not alter accepted JSON, published schemas, SDK signatures, or SDK contract targets. It is not a general exception to published-API versioning; unrelated breaking changes still require a new versioned surface.
On Windows, the Rust V1
mxc_sdk::v1::policy::filesystem::available_tools_policy and Node V1
policy.filesystem.getAvailableToolsPolicy helpers must not implicitly grant
recursive read access to the system-drive root when discovering pwsh.exe.
Such a grant can expose host files beyond the discovered tool directories.
Discovery grants access to tool directories and the PSReadLine history
directory.
This specific security-servicing exception applies within V1 and does not require a new versioned API surface.
For PowerShell startup failures, see troubleshooting.
The published 0.9.0-alpha and 1.0.0 create-and-run contracts, and the
Node V1 WslcConfig.targetOs property, accept any string for
wslc.targetOs. WSLc runs only Linux containers and cannot select another
operating system, so the WSLc backend rejects every value other than "linux"
with policy_validation before it creates a session or container. Omit the
field or set it to "linux".
This fail-closed exception applies within V1 and does not require a new versioned API surface.
Development features use their intended permanent top-level locations in the
mutable exact contract. JSON location, publication eligibility, and runtime
authorization are separate concerns. This gives editors full autocomplete and
validation without requiring a later field move when a feature graduates.
The engine-owned backend registry in
src/mxc-sdk/src/core/mxc_engine/backend_registry.rs records which backend selections
require runtime experimental authorization. Contract publication does not
implicitly change that classification. The flag does not enable otherwise
invalid fields or bypass backend enforcement.
Rules:
- Published contract contents — shipped, stable, and immutable.
- Development contract contents — mutable fields and roots at their permanent locations. Inclusion does not imply runtime authorization.
- Promotion: Publish the feature in an exact stable contract without changing its JSON location. Update backend experimental classification separately when that backend is ready for production; publishing a field alone does not remove a backend's authorization requirement.
scripts/versioning/check-contract-codegen.js compares every stable schema
present at the merge base with the current tree. A published schema cannot be
changed or removed. New stable schemas are allowed because they have no
merge-base predecessor.
The same gate requires exactly one development contract and verifies that every supported stable schema has a published registry entry with the same version, schema path, and schema identifier. Git already content-addresses the files, so no separate digest manifest is recorded.
Each ContractDescriptor also owns whether that contract generates artifacts
and the request roots used for generation and fixture validation. Each
registered root names its fixture directory and schema definition. The codegen
gate consumes this metadata directly, so a generated contract cannot silently
omit a request root. Legacy v0.6-v0.8 contracts intentionally advertise no
generated request roots.
schemas/schema-version.json owns sdkMajorTargets, the canonical mapping
from each high-level SDK major line to the latest published stable exact
line targets. The v1 line targets "1": "1.0.0". Opening mutable
1.1.0-alpha development does not advance that target; publishing stable
1.1.0 does.
The exact Rust contract registry is authoritative. The schema-version gate
loads that registry through mxc_schema_gen and verifies that each mapping:
- names a registered exact stable-version contract;
- stays within the named major line;
- selects the latest published stable contract in that line;
- exists for every published stable major line beginning with v1.
Generated schemas remain derived artifacts and drift oracles. They do not define the SDK target or the accepted contract shape.
Compatibility comparison and SDK API baselines are intentionally deferred
until the relevant stable and public API artifacts exist. When stable 1.0.0
and 1.1.0 are both published, structural tooling may compare temporary
projections generated directly from their exact Rust types, while explicit
Rust and fixture tests cover semantic meaning. Rust, Node, and .NET API
baselines are captured when the v1.0 SDK surface is established rather than
through empty placeholder
descriptors.
The exact JSON execution surface uses mxc_run_json, mxc_spawn_json, and
the state-aware JSON exports. Typed binding writers select the SDK-owned
contract; raw APIs preserve the caller's exact document. These exports use
the registered contract parser and take non-configuration controls, including
experimental authorization, as typed FFI arguments rather than JSON fields.
The SDK conformance fixtures
pair high-level invocations with independently hand-authored expected exact
documents to check mapping intent across Rust, Node, and .NET.
The .NET request probe uses the same exact request writer as execution and
calls mxc_probe_request_json_with_error. The private execution and probe
exports and their request parser are removed. Rust SDK policy authoring types
no longer derive serde traits; they build exact contract values rather than
forming another deserializable JSON contract. Exact contract types and
test-only fixture types retain their serialization support.
The experimental flag must be supported at every layer of the stack:
1. wxc-exec.exe / lxc-exec (Rust binaries):
wxc-exec.exe config.json --experimental
lxc-exec config.json --experimental
# Flag order does not matter — these are equivalent:
wxc-exec.exe --experimental config.jsonThe parser always parses fields defined by the selected exact contract;
parsing is flag-independent. The flag authorizes selecting an experimental
backend (MicroVM, Hyperlight, or Windows Sandbox). Without it, native refuses
the request with
backend_unavailable on every one-shot and state-aware entry point. The flag
is ignored for production backends, including production-backend fields in a
development contract; unsupported policy still fails closed rather than being
silently ignored. Contract version and backend authorization are separate.
The authorization switch is excluded from policy identity because it does not
change the selected backend's enforcement.
2. SDK: the published v1 SDKs do not authorize experimental backends.
Their create-and-run and container lifecycle operations always pass the native
entry points' experimental argument as off, so a request that selects an
experimental backend fails with backend_unavailable. Exercise experimental
backends through wxc-exec --experimental.
Developers adding experimental features follow this pattern. For a detailed step-by-step guide, see Authoring a New Feature.
In the exact development contract (the production parse + schema source of truth):
Add the field to the applicable closed request type under
src/mxc-sdk/src/core/mxc_contract/dev/, including the backend and phase roots
that admit it.
In the exact adapter and common request IR:
pub(crate) struct CommonRequestIR {
// ... stable fields ...
pub(crate) gpu_isolation: Option<GpuIsolation>,
}Edit the authoritative closed mutable contract under
src/mxc-sdk/src/core/mxc_contract/dev/, then adapt the exact field into
CommonRequestIR. Regenerate the exact schema:
cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- schema --version 1.1.0-alpha --out schemas/dev/mxc-config.schema.1.1.0-alpha.json
Also regenerate the exact TypeScript oracle with the corresponding
mxc_schema_gen types --version command. Do not hand-edit generated artifacts.
In models.rs:
pub struct ExecutionRequest {
// ... stable fields ...
pub gpu_isolation: Option<GpuIsolationConfig>,
pub experimental_enabled: bool, // set by --experimental flag
}In the version-specific adapter and config_parser.rs: map the exact
contract field into the common request IR, then map its DTO directly to the
corresponding ExecutionRequest field inside normalize_common_request_ir.
In the runner (e.g., appcontainer.rs):
fn run(&mut self, request: &ExecutionRequest, logger: &mut Logger) -> ScriptResponse {
// ... normal execution ...
// Experimental features only applied when flag is set
if request.experimental_enabled {
if let Some(ref gpu) = request.gpu_isolation {
self.apply_gpu_isolation(gpu, logger);
}
}
}Promotion process: When an experimental feature is ready to ship:
- Carry the field from the mutable development contract into the next exact
stable contract at the same permanent JSON location, then regenerate its
exact schema and TypeScript artifacts with
mxc_schema_gen - Add the stable contract adapter mapping while retaining the existing
normalize_common_request_irdomain normalization - Remove the
if request.experimental_enabledguard - Bump the minor version
- Preserve every published contract unchanged; older contracts continue to reject the field structurally.
Backend-section validation does not move during promotion: an experimental backend's exact-contract section already occupies its permanent top-level location. Existing containment/section consistency rules continue unchanged.
Caller supplies SandboxPolicy (no schema-version field)
│
▼
v1 SDK builds a request for its exact `1.0.0` target
│
▼
MXC validates the request against the selected contract and policy
│
▼
Stage 2: resolve `containment` intent → concrete backend
│
▼
Stage 3: probe host capability → validate backend availability
│ (ProcessContainer: native PSEC or backend_unavailable)
│
▼
For the BaseContainer tier: translate policy → PSEC flat buffer
│
▼
Create process security environment, then launch with CreateProcessW
│
▼
Process runs in sandbox
MXC deliberately keeps three Rust representations rather than sharing one type across trust-boundary parsing, common normalization, and backend execution:
- Exact registered contracts (
mxc_contract) — version-, phase-, and backend-specific closed request roots. These are the production JSON deserialization boundary and the source for authoritative schemas and generated exact TypeScript wire types. - Common request IR
(
mxc_common::common_request_ir::CommonRequestIR) — the private common representation produced by version-specific adapters and consumed by shared semantic normalization. It is not a JSON parse or schema generation target. - Runtime / domain model (
models::ExecutionRequestand friends) — the validated, defaults-applied, invariant-rich model the backends consume: abstract containment resolved to a concrete backend,process.commandLinereshaped toscript_code, enums resolved to domain enums, and required fields no longer optional.
The exact contract rejects structural errors first. Version-specific adapters
then perform structural conversion into CommonRequestIR.
normalize_common_request_ir applies shared defaults and semantic validation
and constructs the runtime model.
The registered contracts admit only directional networking, so their adapters
pass directional network sections to shared normalization. An omitted network
section receives directional deny defaults; shared normalization does not select
a network format from contract provenance or legacy field presence.
Reusable nested DTOs under mxc_common::wire help adapters share representations
for common fields. They are not a whole-request deserialization boundary and do
not generate schemas or public SDK types.
- Exact version boundaries. Each registered contract owns its accepted JSON shape, generated schema, and generated exact TypeScript types. A field cannot leak into another version or request phase through a shared permissive root.
- One validate/normalize boundary. Defaults, invariant enforcement, abstract→concrete backend resolution, and field reshaping all happen in exactly one place; backends receive a type whose invariants already hold.
- Parse, don't validate. The domain type makes illegal states
unrepresentable (required fields non-
Option, enums resolved, containment always concrete), so a backend never re-checks "is this set / known?". - Shared normalization without shared acceptance. Exact adapters converge on
CommonRequestIR, so semantic rules stay common without making every version deserialize through one rolling request type. - Decoupled evolution. An exact contract can rename, alias, or restructure a field without exposing those JSON details to backend code.
- Backends don't couple to JSON quirks — camelCase renames, deprecated-spelling
serde aliases,
$schema/_commentpassthrough, and request-root differences do not leak into runner code.
- Adapter work. Adding a field touches each exact contract that accepts it,
its adapter,
CommonRequestIRor a phase-specific runtime config, and the runtime model when the field survives normalization. - Internal drift risk. Exact adapters and common normalization can diverge.
Exhaustive destructuring without
..makes newly added contract fields fail compilation until they are deliberately mapped. - Indirection. Tracing one field means following exact request → adapter →
CommonRequestIR→ExecutionRequest→ backend.
The exact contracts must remain JSON-shaped because they define each published
trust boundary and generate its schema and TypeScript representation.
CommonRequestIR gives those version-specific contracts one private convergence
point, while ExecutionRequest gives backends stable, validated runtime
semantics. Combining any two would either weaken exact-version closure, duplicate
normalization across versions, or expose JSON-specific optionality and aliases to
backends.
The costs are addressable without merging these responsibilities, for example with shared adapter helpers and compile-time mapping checks. No planned phase reintroduces a rolling whole-request contract.
Execution resolves a request in three ordered stages. The schema version gates only the first; it does not influence stages 2 or 3.
Stage 1 — Exact contract selection (the trust boundary, `config_parser`)
Does config.version name an exact registered contract?
missing / malformed → declaration error
unregistered → unsupported contract version error
registered → deserialize that contract
→ adapt to CommonRequestIR
→ normalize and validate into ExecutionRequest
Patch and prerelease spelling are significant; there is no range fallback.
Stage 2 — Containment resolve (independent of schema version)
Map the `containment` intent to a concrete backend:
omitted / "process" → OS-native process sandbox
(Windows: ProcessContainer, Linux: Bubblewrap,
macOS: Seatbelt)
"vm" → host VM-class backend
explicit backend → used verbatim
Stage 3 — Host-capability negotiate (runtime probe, no version input)
For ProcessContainer on Windows:
PSEC compatible and usable? → PSEC
otherwise → backend_unavailable
MXC does not emulate native containment by modifying host filesystem ACLs.
For the BaseContainer tier, Stage 3 translates the policy into a PSEC
FlatBuffer, creates a process security environment, and supplies it to
CreateProcessW:
translate policy → PSEC FlatBuffer
→ CreateProcessSecurityEnvironment(flatbuffer)
→ CreateProcessW(PROC_THREAD_ATTRIBUTE_SECURITY_ENVIRONMENT)
→ success or typed error
PSEC compatibility is runtime-probed. MXC selects this tier only when the installed contract supports the complete requested policy.
Backend selection is capability-driven, not version-driven (Stage 3 takes no version input), and security policy never fuzzy-falls-back: if the selected backend cannot honor the requested filesystem/network policy, execution fails with a typed, actionable error rather than silently weakening enforcement (see Error Contract).
The BaseContainer tier creates a process security environment and attaches it to the child launch:
HRESULT CreateProcessSecurityEnvironment(
BYTE* specification,
UINT32 specificationSize,
HANDLE* securityEnvironment
);
BOOL CreateProcessW(
...,
LPPROC_THREAD_ATTRIBUTE_LIST attributeList,
...
);Negotiation failures are typed and actionable — never a silent fallback:
- JSON and policy-shape failures distinguish malformed JSON syntax from
valid JSON that does not match the typed wire contract. Typed failures name
the full policy path (for example,
network.proxy.localhost), retain Serde's expected type/value information, and include source line/column when parsing directly from request text. State-aware per-backend configuration errors are prefixed with their full<backendSection>.<phase>location. Diagnostic text escapes control characters, and errors at secret-bearing paths redact the submitted value. After the root JSON value, only whitespace is accepted; trailing JSON values or other trailing content are rejected as malformed syntax. - Contract-version failures (Stage 1) identify a missing or malformed declaration or an unsupported exact version. The SDK retains its "older than supported" / "newer than supported" hints for versions outside the supported lines, and rejects unregistered in-range spellings with "not a registered schema contract". No loader silently chooses a version.
- Capability failures (Stage 3) surface on the runner's
ScriptResponse(and the SDKspawnpath'sMxcError) as aBackendUnavailablefailure phase when the requested backend's API is absent (e.g. the BaseContainer OS sandbox API is not present on this build), with a hint pointing at the host requirement — not a downgrade to a weaker backend behind the caller's back. - Policy-unsupported failures (a backend that cannot honor a specific policy
field, e.g.
deniedPaths) fail with a specific message naming the unsupported field. Security policy is deterministic — no relaxation, no fuzzy fallback.
Every executor failure is classified by which side can act on it, and that classification drives both the wire code and the process exit code:
| Side at fault | Failure phase | Wire code | Exit code |
|---|---|---|---|
| The request — a different request succeeds | Rejected |
policy_validation |
1 |
| The host — no request change helps | BackendUnavailable |
backend_unavailable |
-1 |
| The runtime, during an accepted run | all other phases | backend_error |
-1 |
Common cases:
| Failure | Wire code |
|---|---|
Policy field the backend cannot enforce (e.g. ProcessContainer enumeratePaths, deniedPaths, LPAC) |
backend_unavailable¹ |
| Policy path the invoking user cannot access | backend_error¹ |
| Host fault while checking a policy path (I/O error, unresolvable path) | backend_error |
| Missing host capability (e.g. no native PSEC, no denial-capture provider) | backend_unavailable |
| Backend not compiled into this build | unsupported_containment¹ |
| Experimental backend without the experimental opt-in | backend_unavailable |
| Backend for another OS: create-and-run / container lifecycle operations | unsupported_containment / backend_unavailable |
Unsupported policy is never silently dropped, and no failure above starts the
run. The phase-specific codes malformed_request, unsupported_containment,
unsupported_phase, and malformed_id also exit 1.
¹ Kept for SDK v1 compatibility, as are some backend refusals that still report
backend_error. See the SDK v2 error codes plan.
Envelope lines share stderr with the workload's own output, so a workload can
print text that looks like an envelope. Treat stderr envelopes as diagnostics,
not as an authenticated result; the exit code and a held ScriptResponse are
authoritative.
ScriptResponse carries an optional warnings array of diagnostic strings.
Warnings are advisory and never change the exit code; they are omitted from the
wire entirely when a run produced none. The serialized response and the
executor's stderr stream are two distinct shapes of the same warnings: on the
response they are a warnings: string[] field, while an executor writes each
one to stderr as its own line-delimited JSON object,
{"warning":{"message":"..."}}, matching the error envelope
{"error":{"code":"...","message":"..."}}. A caller reading stderr must parse
the per-line objects; the array exists only on a response it holds directly.
The MXC ↔ OS contract therefore reports: which feature failed, whether it was a version mismatch or a runtime/capability unavailability (e.g. Hyper-V off), and what the user should do (upgrade OS, enable feature, change the config).
Shipping model: The shipped schema contains only non-experimental
features. Experimental features exist solely for internal development and
testing — they are never shipped to end users. The --experimental flag is a
development tool, not a production feature.
Global flag: The --experimental flag is a single global toggle. When enabled,
all experimental features in the config are active. There is no per-feature
enable/disable mechanism — simplicity over granularity.
Migration after promotion: Promotion changes publication and runtime authorization, not the feature's JSON path. Each exact contract retains its version-specific shape; requests must use the shape defined by their declared version.
When a wire value is renamed (e.g. appcontainer → processcontainer in
#268), the legacy spelling enters a
deprecation window where both forms are accepted on the wire.
Policy: alias acceptance belongs to each exact parser contract. The parser,
schema, generated raw type, and raw SDK validator must agree on the spellings
accepted by the declared config.version; aliases are not version-independent
parser exceptions.
The supported v0.9 contract accepts appcontainer, appContainer, and
macos_sandbox as compatibility aliases. The v1 line removes all three
spellings at its major-version boundary, so raw v1.0 and v1.1 requests must use
processcontainer, processContainer, and seatbelt.
Observability. Each exact contract accepts its version-specific legacy
value aliases and normalizes them during exact deserialization, before its
adapter produces CommonRequestIR. The private normalization DTOs are not a
JSON trust boundary. Internal raw-string consumers that need containment only
for classification, such as command splicing, recognize aliases explicitly
through wire::Containment::parse_wire_name. Alias acceptance is silent in the
native parser; the TypeScript SDK validator may still surface a deprecation hint
via diagLog while inspecting raw config.
Removal. Removing an accepted alias is a breaking wire change and therefore belongs at a major-version boundary. The supported v0.9 contract continues to accept its aliases; the new major rejects them with the standard exact-contract diagnostic.
-
Security of the experimental flag: Should
--experimentalrequire additional privilege or be restricted to debug builds? A malicious caller could pass--experimentalto enable a feature that weakens the sandbox boundary. -
Conflicting experimental features: If two experimental features have conflicting requirements (e.g., one denies a namespace, another relaxes it), how are conflicts resolved? First-wins, last-wins, or error?
-
Per-feature vs global experimental flag: Should
--experimentalbe a global toggle (all experimental features on/off), or per-feature (--experimental compartments --experimental gpu-isolation)? Per-feature gives more control but adds complexity to the executor and SDK interfaces. -
Shipping experimental features to customers: Should experimental features be shippable to specific customers (e.g., Anthropic, Nemoclaw), or strictly internal development only? If shippable, the security and stability requirements for experimental features increase significantly. What is the delivery mechanism — private npm package drop, feature-flagged public release, or a separate experimental binary?
-
Multiple dev schemas for multiple major versions: When multiple major versions are alive simultaneously (e.g., v1 shipped on OS 26100, v2 shipped on OS 27000, v3 in development), promoting a feature may require adding it to multiple schemas. For example, if "compartments" is additive, it should be added to both
dev/1.vnext.jsonanddev/2.vnext.jsonas a minor bump for each. If it's breaking, it goes only intodev/3.vnext.json. Thedev/folder and promotion process need to support this multi-schema model. Today we are pre-1.0 with only one major version, so a single dev schema suffices. -
Experimental features modifying stable behavior: Experimental features may need to modify stable behavior. How do we reason about and test this?
These changes would break V1 callers, so they wait for V2:
- Rename
captureDenials.retainEtland the result'setlPathtoretainTraceandtracePath. On macOS the file is a Seatbelt log, not an ETL. - Move
captureDenialsto a top-level request field that each backend accepts or rejects, instead of a backend-specific field. - Mark every Rust SDK options struct
#[non_exhaustive]so options can gain fields without a new operation, and foldspawnintospawn_with_extended_options.