Audience: MXC developers
MXC generates artifacts from exact registered configuration contracts:
| Artifact family | Rust source | Purpose |
|---|---|---|
Exact 0.9.0-alpha |
src/mxc-sdk/src/core/mxc_contract/published/v0_9_0_alpha/ |
Authoritative closed published contract and versioned TypeScript oracle |
Exact 1.0.0 |
src/mxc-sdk/src/core/mxc_contract/published/v1_0_0/ |
Authoritative closed published SDK target and generated TypeScript / C# wire types |
Exact 1.1.0-alpha |
src/mxc-sdk/src/core/mxc_contract/dev/ |
Authoritative closed development contract and versioned TypeScript oracle |
Published schemas under schemas/stable/ are immutable release artifacts.
mxc_schema_gen renders published v0.9 and v1.0 into temporary output so
check-contract-codegen.js can compare the enforcing Rust model with the
committed stable schema and TypeScript oracle. The gate also compares
pre-existing stable schemas with the merge base and validates their registry
identities.
src/mxc-sdk/src/core/mxc_contract/dev/ defines the exact mutable
1.1.0-alpha contract. Its one-shot and eleven state-aware request roots are
independent closed Rust types. Constrained primitives and the string_enum!
and string_marker! macros implement JsonSchema so deserialization and
generated constants cannot drift.
src/mxc-sdk/src/core/mxc_contract/published/v0_9_0_alpha/ defines the exact
published v0.9 contract, including IsolationSession and WSLC one-shot and
state-aware roots. It remains renderable for verification; generation does
not make the stable artifact mutable.
src/mxc-sdk/src/core/mxc_contract/published/v1_0_0/ defines the exact
published v1.0 contract. It preserves the seven v0.9 request roots while
removing the pre-v1 compatibility aliases. The mutable v1.1 contract retains
that removal so no v1 exact contract accepts the retired spellings. Published
v1.0 also remains renderable for verification without making the stable
artifact mutable.
mxc_schema_support owns shared integer normalization, deterministic root
rendering, TypeScript emission, and C# wire-type emission. mxc_schema_gen
uses those helpers for every renderable exact contract.
mxc_common::common_request_ir::CommonRequestIR is the internal whole-request
normalization boundary that replaced the former deserializable
wire::MxcConfig root. Exact contract adapters assemble it, and it may contain
reusable nested DTOs from wire.rs, but it has no JSON deserialization or
schema-generation surface of its own.
Development-contract artifacts:
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
cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- types --version 1.1.0-alpha --out sdk/node/src/generated/v1_1_0_alpha/wire.ts
Published verification artifacts:
cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- schema --version 0.9.0-alpha --out <temporary-schema>
cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- types --version 0.9.0-alpha --out <temporary-types>
cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- schema --version 1.0.0 --out <temporary-schema>
cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- types --version 1.0.0 --out <temporary-types>
.NET SDK target-contract wire types:
cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- csharp --version 1.0.0 --out sdk/dotnet/Microsoft.Mxc.Sdk/Generated/MxcConfigV1_0_0.g.cs
mxc_schema_gen versions --json emits registry-driven lifecycle and artifact
metadata, including whether an exact model is renderable and the fixture
directory/schema-definition pair for every request root. Versioning gates use
that metadata for artifact regeneration, root validation, fixture discovery,
and state-aware backend-version checks rather than maintaining separate
per-version root tables. Published v0.9, published v1.0, and development v1.1
dispatch to their own exact models. Older published versions without
renderable exact models return an explicit error; no version falls back to
another model.
The exact contract crate gates Schemars behind schema-gen, so normal builds
do not carry it. The exact OptionalField<T> schema is transparent and
non-referenceable: omitted fields remain optional while explicit null stays
rejected.
The exact schema uses one shared definitions table and nested if/then
dispatch:
- absence of
phaseselects one-shot; - a present
phaseselects provision-session, provision, start, exec, stop, deprovision, or deprovision-session; - provision additionally selects a backend-specific root by
containment(Windows Sandbox, IsolationSession, MicroVM, WSLC, or W365 Agents in v1.1 development; IsolationSession or WSLC in published v0.9 and v1.0). The two session phases select bycontainmentas well, but admit only WSLC.
This structure evaluates only the relevant branch and gives more focused
editor diagnostics than a bare request-root union. One-shot and exec require
process; the other lifecycle roots do not. Every reachable object has
additionalProperties: false.
Each exact schema is both the authoring contract and the runtime contract for
its registered version. Repository config validation obtains schema paths from
mxc_schema_gen versions --json and selects the exact schema named by each
document's declared version.
The CLI command-override entry point splices process.commandLine before exact
parsing. Therefore the exact contract and schema require process and a
non-empty process.commandLine; a pre-splice policy document is not itself
contract-valid, and no relaxed schema twin is generated.
- Define and export the closed provision request and containment marker under
src/mxc-sdk/src/core/mxc_contract/dev/state_aware/provision/. - Add its subschema and containment discriminator to
provision_dispatch()indev/schema.rs, then include the root inROOT_NAMES. - Add the root's
ContractRequestRootentry to the version'srequest_rootsmetadata insrc/mxc-sdk/src/core/mxc_contract/registry.rs, and create matching valid and invalid fixture directories undertests/v1_1_0_alpha/fixtures/. - Regenerate the exact schema and versioned TypeScript oracle.
- Wire the request through the exact-contract adapter and state-aware runtime dispatcher.
check-contract-codegen.jsdiscovers renderable exact artifacts throughmxc_schema_gen versions --json, regenerates v0.9, v1.0, and v1.1 schema, TypeScript outputs, and registered C# SDK wire types, validates each version's expected roots and fixture corpus, and protects stable schema history and published registry identities.validate-configs.jsvalidates the repository config corpus against exact registered schemas discovered from the same registry command.wire-conformance.test.tschecks the Node one-shot public-to-raw v1.0 mapping against the exact generated published v1.0 oracle.wire-conformance-state-aware.test.tschecks backend-specific state-aware public types against the exact v0.9 and v1.1 oracles.check-schema-versions.jsandcheck-version-sync.jsenforce schema and product version synchronization. The schema-version check also validates the canonical high-level SDK major target against the exact Rust contract registry; generated schemas are not the authority for that mapping.
The generated TypeScript files are drift oracles, not public SDK exports. The
generated C# files are internal .NET SDK wire records for the exact SDK target
contract. Integral schema bounds, including 0.0, select the appropriate
unsigned C# wire type for nonnegative minimums; a nonnegative bound without
a small maximum uses ulong. Public SDK types remain hand-written and are
checked at compile time.