Add versioned development contract codegen by MGudgin · Pull Request #968 · microsoft/mxc

Gudge (MGudgin) · 2026-08-20T18:02:56Z

📖 Description

This PR adds generated schema and TypeScript artifacts for the exact
0.8.0-alpha development configuration contract.

Details

Add optional schema generation to mxc_config_contract and shared
deterministic schema rendering and TypeScript emission in
mxc_schema_support.
Add registry-driven schema, types, and versions generator commands and
commit the exact schema and non-exported TypeScript oracle.
Compose and gate all eight closed request roots, including exact
discriminators, compatibility aliases, capability constraints, and
automatically discovered fixtures.
Document how the rolling and exact development artifact families coexist
until exact parser dispatch becomes authoritative.

Tests

cargo fmt --all -- --check
cargo check --workspace --all-targets with Rust 1.93.1
cargo clippy --workspace --all-targets --all-features --release --
-D warnings
cargo test --workspace
Schema, SDK wire-type, contract, version-sync, and config-validation
codegen gates
npm run build and npm test in sdk/node

Microsoft Reviewers: Open in CodeFlow

azure-pipelines · 2026-08-20T18:03:06Z

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

Darren Hoehna (dhoehna)

Please modify the regex into something simpler. Considering the regex is comparing certain characters in a certain order a .ToLower() + string concatenation should work wonders.

Copilot

Pull request overview

Adds version-aware schema and TypeScript generation for the exact 0.8.0-alpha contract alongside the existing rolling wire model.

Changes:

Adds shared schema rendering and TypeScript emission infrastructure.
Generates and validates exact contract artifacts for eight request roots.
Updates CI, fixtures, and documentation for dual artifact families.

Show a summary per file

File	Description
`src/tools/mxc_schema_gen/src/main.rs`	Adds version-aware generator CLI.
`src/tools/mxc_schema_gen/Cargo.toml`	Adds generator dependencies.
`src/core/wxc_common/src/wire.rs`	Uses shared schema support.
`src/core/wxc_common/src/lib.rs`	Removes local TS emitter module.
`src/core/wxc_common/Cargo.toml`	Adds shared schema dependency.
`src/core/mxc_schema_support/src/ts_emit.rs`	Extends TypeScript schema emission.
`src/core/mxc_schema_support/src/lib.rs`	Adds shared schema utilities.
`src/core/mxc_schema_support/Cargo.toml`	Defines the new support crate.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/wslc_provision/valid/minimal.json`	Adds valid WSLC provision fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/wslc_provision/invalid/foreign_sandbox_id.json`	Adds invalid WSLC fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/windows_sandbox_provision/valid/minimal.json`	Adds valid Windows Sandbox fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/windows_sandbox_provision/invalid/foreign_network.json`	Adds invalid Windows Sandbox fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/stop/valid/minimal.json`	Adds valid stop fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/stop/invalid/unknown_field.json`	Adds invalid stop fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/start/valid/minimal.json`	Adds valid start fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/start/invalid/foreign_process.json`	Adds invalid start fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/seatbelt_minimal.json`	Adds minimal Seatbelt fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/seatbelt_complete.json`	Adds complete Seatbelt fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/proxy_url.json`	Covers URL proxy form.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/proxy_localhost.json`	Covers localhost proxy form.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/proxy_builtin.json`	Covers built-in proxy form.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/minimal.json`	Adds minimal one-shot fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/macos_sandbox_alias.json`	Covers Seatbelt compatibility alias.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/experimental.json`	Covers experimental configuration.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/empty_optional_objects.json`	Covers empty optional objects.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/complete.json`	Expands complete fixture capabilities.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/app_container_alias.json`	Covers ProcessContainer alias.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/valid/annotations.json`	Adds annotation fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/unknown_root_field.json`	Tests closed root validation.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/unknown_nested_field.json`	Tests closed nested validation.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/state_aware.json`	Tests one-shot phase exclusion.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/seatbelt_unknown_field.json`	Tests closed Seatbelt fields.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/seatbelt_invalid_launch_method.json`	Tests Seatbelt enum validation.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/port_out_of_range.json`	Tests port bounds.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/incomplete_lxc.json`	Tests required LXC fields.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/duplicate_seatbelt_alias.json`	Tests alias exclusivity.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/duplicate_process_container_alias.json`	Tests ProcessContainer alias exclusivity.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/capability_with_comma.json`	Tests capability delimiters.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/capability_permissive_learning_mode_reserved.json`	Tests reserved capability handling.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/one_shot/invalid/capability_learning_mode_logging_reserved.json`	Tests reserved logging capability.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/isolation_session_provision/valid/minimal.json`	Adds valid IsolationSession fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/isolation_session_provision/invalid/missing_network.json`	Tests required network acknowledgment.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/exec/valid/minimal.json`	Adds valid exec fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/exec/invalid/missing_process.json`	Tests required exec process.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/deprovision/valid/minimal.json`	Adds valid deprovision fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures/deprovision/invalid/foreign_containment.json`	Adds invalid deprovision fixture.
`src/core/mxc_config_contract/tests/v0_8_0_alpha/fixtures.rs`	Auto-discovers per-root fixtures.
`src/core/mxc_config_contract/src/registry.rs`	Registers artifact metadata.
`src/core/mxc_config_contract/src/dev/state_aware/stop.rs`	Enables stop schema generation.
`src/core/mxc_config_contract/src/dev/state_aware/start.rs`	Enables start schema generation.
`src/core/mxc_config_contract/src/dev/state_aware/provision/wslc.rs`	Enables WSLC provision schemas.
`src/core/mxc_config_contract/src/dev/state_aware/provision/windows_sandbox.rs`	Enables Windows Sandbox schemas.
`src/core/mxc_config_contract/src/dev/state_aware/provision/isolation_session.rs`	Enables IsolationSession schemas.
`src/core/mxc_config_contract/src/dev/state_aware/mod.rs`	Generates marker schemas.
`src/core/mxc_config_contract/src/dev/state_aware/exec.rs`	Enables exec schema generation.
`src/core/mxc_config_contract/src/dev/state_aware/deprovision.rs`	Enables deprovision schemas.
`src/core/mxc_config_contract/src/dev/stable.rs`	Adds exact stable-surface schemas.
`src/core/mxc_config_contract/src/dev/schema.rs`	Composes the eight-root schema.
`src/core/mxc_config_contract/src/dev/primitives.rs`	Adds constrained primitive schemas.
`src/core/mxc_config_contract/src/dev/one_shot.rs`	Generates the one-shot schema.
`src/core/mxc_config_contract/src/dev/network.rs`	Generates network schemas.
`src/core/mxc_config_contract/src/dev/mod.rs`	Adds enum schema generation.
`src/core/mxc_config_contract/src/dev/experimental.rs`	Generates experimental schemas.
`src/core/mxc_config_contract/Cargo.toml`	Adds optional Schemars support.
`src/Cargo.toml`	Registers shared schema crate.
`src/Cargo.lock`	Locks new workspace dependencies.
`sdk/node/tests/unit/wire-conformance.test.ts`	Updates generator documentation.
`sdk/node/src/generated/wire.ts`	Refreshes rolling oracle banner.
`sdk/node/src/generated/v0_8_0_alpha/wire.ts`	Adds exact TypeScript oracle.
`scripts/versioning/package.json`	Adds contract-codegen command.
`scripts/versioning/check-sdk-types-codegen.js`	Uses the new generator CLI.
`scripts/versioning/check-schema-codegen.js`	Uses the new schema command.
`scripts/versioning/check-contract-codegen.js`	Adds exact artifact and fixture gate.
`schemas/dev/mxc-config.schema.0.8.0-dev.json`	Adds integer upper bounds.
`schemas/dev/mxc-config.schema.0.8.0-alpha.json`	Adds exact development schema.
`docs/versioning.md`	Documents parallel schema families.
`docs/schema-codegen.md`	Documents exact code generation.
`docs/bwrap-support/bubblewrap-backend-plan.md`	Updates schema regeneration guidance.
`docs/authoring-a-new-feature.md`	Updates feature-authoring workflow.
`.github/workflows/Versioning.Checks.Job.yml`	Runs the exact contract gate.

Review details

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

Files reviewed: 56/80 changed files
Comments generated: 2
Review effort level: Balanced

Copilot

Review details

Files reviewed: 56/80 changed files
Comments generated: 1
Review effort level: Balanced

This PR adds generated schema and TypeScript artifacts for the exact `0.8.0-alpha` development configuration contract. Details * Add optional schema generation to `mxc_config_contract` and shared deterministic schema rendering and TypeScript emission in `mxc_schema_support`. * Add registry-driven `schema`, `types`, and `versions` generator commands and commit the exact schema and non-exported TypeScript oracle. * Compose and gate all eight closed request roots, including exact discriminators, compatibility aliases, capability constraints, and automatically discovered fixtures. * Document how the rolling and exact development artifact families coexist until exact parser dispatch becomes authoritative. Tests * `cargo fmt --all -- --check` * `cargo check --workspace --all-targets` with Rust 1.93.1 * `cargo clippy --workspace --all-targets --all-features --release --` `-D warnings` * `cargo test --workspace` * Schema, SDK wire-type, contract, version-sync, and config-validation codegen gates * `npm run build` and `npm test` in `sdk/node` Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3e21b1cb-c31f-4aaa-82c5-7689c0b25e77

Copilot

Review details

Suppressed comments (1)

src/core/mxc_schema_support/src/ts_emit.rs:68

The emitter accepts an arbitrary contract version, but the generated regeneration command always targets the v0_8_0_alpha file. As soon as another development contract is registered, its generated oracle will instruct contributors to overwrite the 0.8 artifact. Pass the descriptor's registered TypeScript path into the banner instead of hardcoding it.

Files reviewed: 58/82 changed files
Comments generated: 2
Review effort level: Balanced

Gudge (MGudgin) · 2026-08-22T02:29:54Z

+ "Network": {
+ "additionalProperties": false,
+ "description": "Network access policy shared by the stable containment backends.",
+ "properties": {


Addressed in a83afb3. The development contract now carries the directional network surface: NetworkAction, NetworkProtocol, NetworkPeer, NetworkPort, NetworkRule, NetworkEgress, and NetworkIngress, plus egress and ingress on Network, runtimeConfig.networkProxy, and processContainer.network.allowedProxyPeer. Every field maps through the development adapter, replacing the hardcoded None fills, and both the schema and the TypeScript oracle are regenerated.
A rule's to and ports use a new NonEmptyVec primitive so the contract carries the same minItems constraint as the shipped schema instead of accepting empty arrays the schema rejects; the exact and rolling 0.8 schemas now agree on NetworkRule.to.minItems and NetworkRule.ports.minItems.
Coverage: 19 new contract tests and two new fixtures, a valid directional policy and an invalid empty destination list, both discovered automatically by the Rust harness and the codegen gate.

Gudge (MGudgin) · 2026-08-22T02:30:04Z

+const fixtureRoot = join(
+ cargoRoot,
+ "core",
+ "mxc_config_contract",
+ "tests",
+ "v0_8_0_alpha",
+ "fixtures"
+);


Addressed in a83afb3. The fixture corpus is now resolved per registry record: a fixtureRootFor(contract) helper maps a contract version onto the crate's module naming (0.8.0-alpha becomes v0_8_0_alpha), and it is called from inside the existing per-contract loop. The resolved root is threaded through readFixtures, readFixture, and validateFixtures rather than closed over as a module-level constant, so registering a second development contract validates its own fixtures.
Verified the gate is not vacuously passing: corrupting a valid 0.8 fixture makes it fail with a focused diagnostic naming the offending property.

Copilot

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/core/mxc_schema_support/src/ts_emit.rs:68

The versioned emitter still hard-codes the v0_8_0_alpha output directory in every generated banner. Once another development contract is registered, its oracle will instruct contributors to overwrite the 0.8 artifact even though the generator and registry otherwise support per-version paths. Derive this directory from version (or pass the registered TypeScript path into the emitter).

Files reviewed: 58/82 changed files
Comments generated: 0 new
Review effort level: Balanced

Copilot

Review details

Suppressed comments (1)

src/core/mxc_schema_support/src/ts_emit.rs:68

This supposedly version-aware banner hard-codes the v0_8_0_alpha output directory. When another development contract is registered, its generated oracle and drift gate will still tell contributors to overwrite the 0.8 artifact. Please derive the banner path from the selected registry descriptor (or pass that descriptor's typescript_path into the emitter) so the registry remains the source of truth.

Files reviewed: 65/89 changed files
Comments generated: 2
Review effort level: Balanced

Gudge (MGudgin) · 2026-08-22T02:30:17Z

+ egress: egress.into_option().map(convert_network_egress),
+ ingress: ingress.into_option().map(convert_network_ingress),


Addressed in a83afb3. The adapter suite now covers the directional conversion end to end.
directional_network_request_maps_expected_wire_fields adapts a request with nested allow and deny rules and asserts the wire values directly: two destinations with a CIDR exception list, an inclusive port range, a ports-only rule, a destinations-only rule, and both ingress controls. directional_network_request_matches_current_wire_deserialization runs the same document through the exact-versus-current-wire comparison. every_network_action_maps_to_the_expected_wire_value and every_network_protocol_maps_to_the_expected_wire_value cover both action values and all four protocol values, each with the equivalence check. absent_directional_network_sections_stay_absent pins the negative case.
Two things worth recording. A misroute is caught: swapping Tcp to Udp in the protocol mapping fails both the direct assertion and the wire-equivalence comparison. A dropped field is caught earlier still, at compile time rather than by a test, because the adapter destructures exhaustively with no .. and the crate denies warnings, so removing a field's mapping produces unused variable and fails the build.

Gudge (MGudgin) · 2026-08-22T02:30:27Z

 fallback: fallback.into_option().map(convert_fallback),
 network: network.into_option().map(convert_network),
- runtime_config: None,
+ runtime_config: runtime_config.into_option().map(convert_runtime_config),


Addressed in a83afb3. runtimeConfig and processContainer.network.allowedProxyPeer are now carried in the DIRECTIONAL_NETWORK_REQUEST_JSON adapter fixture, and directional_network_request_maps_expected_wire_fields asserts both adapted wire values: runtime_config.network_proxy and process_container.network.allowed_proxy_peer. The same document also runs through assert_matches_current_wire_deserialization, so preservation through into_wire is checked against the current wire deserialization rather than only against the contract parse.
absent_directional_network_sections_stay_absent covers the other direction, asserting that a minimal request leaves runtime_config and network absent rather than defaulted.

This PR addresses the review feedback on the versioned development contract codegen: the exact 0.8 contract now covers the directional networking surface the rolling model already accepts, the codegen gate resolves its fixture corpus per registered contract, and the generator's bare-filename handling and authoring documentation are corrected. Details * Add the directional network types to the development contract -- NetworkAction, NetworkProtocol, NetworkPeer, NetworkPort, NetworkRule, NetworkEgress, and NetworkIngress -- plus egress and ingress on Network, so the generated artifacts stop rejecting valid, documented 0.8 configurations. * Add runtimeConfig.networkProxy and processContainer.network.allowedProxyPeer, the remaining two thirds of the shipped 0.8 network surface, and map every new field through the development adapter in place of its hardcoded None fills. * Add a NonEmptyVec primitive for a rule's `to` and `ports` so the contract carries the same minItems constraint as the shipped schema instead of accepting empty arrays the schema rejects. * Resolve the contract fixture corpus from each registry record rather than a fixed directory, so registering a second development contract validates its own fixtures. * Preserve bare output filenames in the generator and cover the CLI behavior with a regression test. * Generate case-insensitive capability schema constraints from the reserved-name constants, and clarify fail-closed contract selection. * Update the schema documentation and repository instructions with phase-neutral transition guidance, current generator commands, and state-aware root extension steps. Tests * cargo test -p mxc_config_contract: 362 passed, up from 343, covering a complete directional policy, partial rule entries, empty and null rejection in every directional object, port boundaries, both enum value sets, unknown-field closure, runtimeConfig, and the ProcessContainer proxy peer. * Two new fixtures, discovered by both the Rust harness and the codegen gate: a valid directional policy and an invalid empty rule destination list. * Mutation-checked two assertions rather than trusting a green run: reverting `to` to a plain Vec fails the empty-array test, and adding "block" as a NetworkAction alias fails the action-vocabulary test. The latter guards a real trap, since legacy defaultPolicy is allow/block while directional is allow/deny. * The exact and rolling 0.8 schemas now agree on NetworkRule.to.minItems and NetworkRule.ports.minItems. * Verified the codegen gate is not vacuous: corrupting a valid 0.8 fixture makes it fail with a focused diagnostic. * cargo fmt --all -- --check, cargo check --workspace --all-targets, cargo clippy --workspace --all-targets --all-features --release -- -D warnings, and cargo test --workspace. * Schema, SDK wire-type, contract, version-sync, and config-validation codegen gates. * npm run build and npm test in sdk/node. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2a8e0d88-21dd-48e5-8e44-df2393b8a664

Copilot

Review details

Files reviewed: 66/90 changed files
Comments generated: 0 new
Review effort level: Balanced

This PR updates the version-specific parser plan for the current state: Phase 5 is fully merged, Phase 6 is awaiting signoff in PR #968, and Phase 6.5 is rebased onto it as a single commit. Details * Rewrite the status paragraph: #966 merged, #968 awaiting a final signoff and now carrying the directional networking port, Phase 6.5 rebased onto it, and Phase 7a open as PR #969. * Mark steps 1 through 5 of the publication sequence with their outcomes, and record that the step 2 port landed inside #968 rather than separately because a review of that pull request identified the same gap. * Add a "Phase 6.5 as rebased" section describing what the branch contains and the two version-marker errors the rebase surfaced, both found by a failing test rather than by inspection. * Correct the development version suffix from 0.9.0-dev to 0.9.0-alpha throughout the contract-side text, leaving the rolling-artifact references unchanged since -dev remains correct there. * Mark the fixture schema reference and the registry path items of the immediate remediation as done, noting that the stable artifact itself is published by the old stack rather than by this work. Tests * Documentation-only change; no build, lint, or test gate applies. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2a8e0d88-21dd-48e5-8e44-df2393b8a664

Gudge (MGudgin) requested a review from a team as a code owner August 20, 2026 18:02

Gudge (MGudgin)force-pushed the user/gudge/version_specific_config_parsers_phase6 branch from 4ac35a4 to d7df271Compare August 20, 2026 18:04

Gudge (MGudgin) requested review from a teamAugust 20, 2026 18:04