microsoft · MGudgin · Aug 1, 2026
@@ -140,6 +140,7 @@ The SDK auto-discovers native binaries by checking `sdk/node/bin/<target-triple>
 - **Dev schema**: the in-progress schema lives in [`schemas/dev/`](../schemas/dev). It is **generated** from the Rust wire model (`src/core/wxc_common/src/wire.rs`) by the `mxc_schema_gen` tool — **do not hand-edit it**. To change the dev schema, edit the wire model and regenerate with `cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- schemas/dev/mxc-config.schema.<dev>.json`. `scripts/versioning/check-schema-codegen.js` is a CI gate that regenerates and fails if the committed schema drifts. See [`docs/schema-codegen.md`](../docs/schema-codegen.md).
 - **Generated SDK wire types**: `sdk/node/src/generated/wire.ts` is **generated** from the same wire model by the `mxc_schema_gen --ts` TypeScript emitter (`wxc_common::ts_emit`, no third-party generator) — **do not hand-edit it**. It is a drift oracle (not public API); the SDK unit test `sdk/node/tests/unit/wire-conformance.test.ts` asserts the hand-written public types in `sdk/node/src/types.ts` conform to it, and `scripts/versioning/check-sdk-types-codegen.js` is a CI gate that fails if the committed file drifts. Regenerate with `cargo run --manifest-path src/Cargo.toml -p mxc_schema_gen -- --ts sdk/node/src/generated/wire.ts`.
 - **Canonical schema-version source**: `schemas/schema-version.json` — the single source of truth for the schema-version constants (min/maxSupported/state-aware/stable/dev). `scripts/versioning/check-schema-versions.js` enforces that the Rust parser, SDK, and schema filenames all agree with it; do not hand-edit a schema-version constant without updating the canonical file. See [`docs/versioning.md`](../docs/versioning.md) for the full design.
+- **Dev schema compatibility**: `scripts/versioning/check-dev-schema-compat.js` is a CI gate that compares the dev schema at the pull-request base against the dev schema at HEAD and **fails on any structural restriction** — a removed property, a new `required`, a narrowed `type`, a tightened bound. There is no per-field escape hatch. Because one dev schema validates configs declaring every supported version, surface a supported version can use has to stay in it. Make a breaking change **additively**: keep the old fields, add the new shape alongside them, and let the supported-version window govern which may be used. Deleting is legitimate only once `min` in `schemas/schema-version.json` rises past the surface being dropped.
 - Config files can reference schemas via `"$schema"` for editor validation. `scripts/versioning/validate-configs.js` validates the `tests/examples` + `tests/configs` corpus against the dev schema in CI.
 
 ### Key documentation (`docs/`)

@@ -47,5 +47,11 @@ jobs:
       - name: Check SDK wire types are in sync with the Rust wire model (codegen)
         run: node scripts/versioning/check-sdk-types-codegen.js
 
+      # Ahead of corpus validation: a pull request that removes a field also
+      # migrates the corpus, so validation passes and the removal is what needs
+      # reporting.
+      - name: Check the dev schema makes no breaking change
+        run: node scripts/versioning/check-dev-schema-compat.js
+
       - name: Validate config corpus against dev schema
         run: node scripts/versioning/validate-configs.js
@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+// Dev-schema compatibility gate.
+//
+// Every other breaking-change guard in this directory compares RELEASED stable
+// schemas, and only at release time. That leaves the surface a pull request
+// actually edits -- the dev schema -- unguarded: a PR can delete a stable field,
+// regenerate the schema and the SDK types, migrate the fixtures, and merge
+// green. PR #676 did exactly that.
+//
+// This gate closes that hole by comparing the dev schema at the pull request
+// base against the dev schema at HEAD and blocking any structural restriction
+// of the accepted instance set.
+//
+// There is deliberately no per-field escape hatch. A field may not simply
+// disappear: the supported-version window is what allows surface to end, so
+// until a change moves that window the only correct answer is to keep accepting
+// what the base accepted.
+//
+//   node scripts/versioning/check-dev-schema-compat.js
+//   node scripts/versioning/check-dev-schema-compat.js --base-ref origin/main
+
+const { resolve } = require("path");
+const { readFileAtCommit, resolveBaseCommit } = require("./lib/git-base");
+const { detectBreaking } = require("./lib/schema-compatibility");
+
+const repoRoot = resolve(__dirname, "..", "..");
+
+function fail(lines) {
+  console.error("Dev schema compatibility FAILED:");
+  for (const line of lines) console.error(`  - ${line}`);
+  process.exit(1);
+}
+
+function jsonAtCommit(commit, path) {
+  const content = readFileAtCommit(repoRoot, commit, path);
+  if (content === null) return null;
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    fail([`${path} at ${commit} is not valid JSON: ${error.message}`]);
+  }
+}
+
+let base;
+try {
+  base = resolveBaseCommit(repoRoot);
+} catch (error) {
+  fail([error.message]);
+}
+
+const devSchemaPath = (versions) =>
+  `schemas/dev/mxc-config.schema.${versions.devSchemaFile}.json`;
+
+const baseVersions = jsonAtCommit(base.commit, "schemas/schema-version.json");
+const headVersions = jsonAtCommit("HEAD", "schemas/schema-version.json");
+if (!baseVersions || !headVersions) {
+  fail(["schemas/schema-version.json is missing at the base or at HEAD"]);
+}
+for (const [label, versions] of [
+  [base.ref, baseVersions],
+  ["HEAD", headVersions],
+]) {
+  if (typeof versions.devSchemaFile !== "string" || !versions.devSchemaFile) {
+    fail([`schemas/schema-version.json at ${label} has no devSchemaFile`]);
+  }
+}
+
+// Each side is read at its own declared dev line. Opening a new dev line copies
+// the outgoing one, so the two documents stay the same lineage and the
+// structural comparison remains meaningful across that transition. Skipping the
+// comparison when the line moves -- or resolving both sides at the base path --
+// would let a pull request escape the gate by editing one line of
+// schemas/schema-version.json.
+const basePath = devSchemaPath(baseVersions);
+const headPath = devSchemaPath(headVersions);
+const baseSchema = jsonAtCommit(base.commit, basePath);
+const headSchema = jsonAtCommit("HEAD", headPath);
+if (!baseSchema) fail([`${basePath} is missing at ${base.ref}`]);
+if (!headSchema) fail([`${headPath} is missing at HEAD`]);
+
+const moved =
+  baseVersions.devSchemaFile === headVersions.devSchemaFile
+    ? ""
+    : ` (dev line moved ${baseVersions.devSchemaFile} -> ${headVersions.devSchemaFile})`;
+
+const findings = detectBreaking(baseSchema, headSchema);
+
+if (findings.length > 0) {
+  fail([
+    `the dev schema removes or restricts surface that callers may already ` +
+      `depend on, compared against ${base.ref} ` +
+      `${base.commit.slice(0, 8)}${moved}:`,
+    ...findings,
+    `Configs declaring an already-supported version must keep parsing. Add ` +
+      `surface instead of removing it, or move the supported-version window ` +
+      `in the same change.`,
+  ]);
+}
+
+console.log(
+  `Dev schema compatibility OK against ${base.ref} ` +
+    `(${base.commit.slice(0, 8)})${moved}: no breaking change.`
+);
@@ -7,6 +7,7 @@
     "pretest": "node check-tests-present.js",
     "test": "node --test tests/*.test.js",
     "check-schema-versions": "node check-schema-versions.js",
+    "check-dev-schema-compat": "node check-dev-schema-compat.js",
     "validate-configs": "node validate-configs.js"
   },
   "dependencies": {

@@ -0,0 +1,175 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+// End-to-end coverage for the dev-schema compatibility gate.
+//
+// The gate is only meaningful as a process: resolve the pull request base, read
+// both dev schemas out of git, compare them, and exit non-zero. Unit-testing the
+// pieces would miss exactly the bypasses that matter, so these tests drive the
+// real CLI against throwaway repositories and assert on its exit code.
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { execFileSync, spawnSync } = require("child_process");
+const { mkdtempSync, rmSync, writeFileSync, mkdirSync, cpSync } = require("fs");
+const { tmpdir } = require("os");
+const { join, resolve } = require("path");
+
+const scriptsDir = resolve(__dirname, "..");
+const gateRelative = "scripts/versioning/check-dev-schema-compat.js";
+
+function git(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+}
+
+const DEV_LINE = "0.8.0-dev";
+
+const schemaWith = (properties) => ({
+  $schema: "http://json-schema.org/draft-07/schema#",
+  type: "object",
+  additionalProperties: false,
+  properties,
+});
+
+function writeVersions(dir, devSchemaFile) {
+  writeFileSync(
+    join(dir, "schemas", "schema-version.json"),
+    `${JSON.stringify({ devSchemaFile }, null, 2)}\n`
+  );
+}
+
+function writeSchema(dir, devSchemaFile, schema) {
+  writeFileSync(
+    join(dir, "schemas", "dev", `mxc-config.schema.${devSchemaFile}.json`),
+    `${JSON.stringify(schema, null, 2)}\n`
+  );
+}
+
+// A repository that contains a real copy of the gate and its libraries, a base
+// commit on `main`, and a `topic` branch to run the gate from.
+function scratchRepo(baseSchema, devLine = DEV_LINE) {
+  const dir = mkdtempSync(join(tmpdir(), "dev-schema-gate-"));
+  git(dir, ["init", "-q", "-b", "main"]);
+  git(dir, ["config", "user.email", "test@example.com"]);
+  git(dir, ["config", "user.name", "Test"]);
+  mkdirSync(join(dir, "schemas", "dev"), { recursive: true });
+  mkdirSync(join(dir, "scripts"), { recursive: true });
+  cpSync(scriptsDir, join(dir, "scripts", "versioning"), { recursive: true });
+  rmSync(join(dir, "scripts", "versioning", "node_modules"), {
+    recursive: true,
+    force: true,
+  });
+  writeVersions(dir, devLine);
+  writeSchema(dir, devLine, baseSchema);
+  git(dir, ["add", "-A"]);
+  git(dir, ["commit", "-q", "-m", "base"]);
+  git(dir, ["checkout", "-q", "-b", "topic"]);
+  return dir;
+}
+
+function runGate(dir) {
+  return spawnSync(process.execPath, [join(dir, gateRelative), "--base-ref", "main"], {
+    cwd: dir,
+    encoding: "utf8",
+  });
+}
+
+function commit(dir, message) {
+  git(dir, ["add", "-A"]);
+  git(dir, ["commit", "-q", "-m", message]);
+}
+
+test("an unchanged dev schema passes", (t) => {
+  const dir = scratchRepo(schemaWith({ keep: { type: "string" } }));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const result = runGate(dir);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /no breaking change/);
+});
+
+test("adding a property passes", (t) => {
+  const dir = scratchRepo(schemaWith({ keep: { type: "string" } }));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeSchema(
+    dir,
+    DEV_LINE,
+    schemaWith({ keep: { type: "string" }, added: { type: "number" } })
+  );
+  commit(dir, "add a property");
+  const result = runGate(dir);
+  assert.equal(result.status, 0, result.stderr);
+});
+
+// The shape of PR #676: delete a stable field and regenerate everything around
+// it. Every other gate in this directory passes on that change.
+test("removing a property is blocked and the property is named", (t) => {
+  const dir = scratchRepo(
+    schemaWith({ keep: { type: "string" }, doomed: { type: "string" } })
+  );
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeSchema(dir, DEV_LINE, schemaWith({ keep: { type: "string" } }));
+  commit(dir, "remove a property");
+  const result = runGate(dir);
+  assert.equal(result.status, 1, result.stdout);
+  assert.match(result.stderr, /doomed/);
+});
+
+test("narrowing a property type is blocked", (t) => {
+  const dir = scratchRepo(schemaWith({ value: {} }));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeSchema(dir, DEV_LINE, schemaWith({ value: { type: "string" } }));
+  commit(dir, "narrow a type");
+  const result = runGate(dir);
+  assert.equal(result.status, 1, result.stdout);
+});
+
+// Reading both sides at the BASE path, or skipping the comparison outright,
+// would let a pull request disable the gate by editing one line of
+// schema-version.json.
+test("opening a new dev line does not disable the gate", (t) => {
+  const dir = scratchRepo(
+    schemaWith({ keep: { type: "string" }, doomed: { type: "string" } })
+  );
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeVersions(dir, "0.9.0-dev");
+  writeSchema(dir, "0.9.0-dev", schemaWith({ keep: { type: "string" } }));
+  commit(dir, "open a new dev line while dropping a property");
+  const result = runGate(dir);
+  assert.equal(result.status, 1, result.stdout);
+  assert.match(result.stderr, /doomed/);
+  assert.match(result.stderr, /0\.8\.0-dev -> 0\.9\.0-dev/);
+});
+
+test("a compatible new dev line passes and reports the move", (t) => {
+  const dir = scratchRepo(schemaWith({ keep: { type: "string" } }));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeVersions(dir, "0.9.0-dev");
+  writeSchema(dir, "0.9.0-dev", schemaWith({ keep: { type: "string" } }));
+  commit(dir, "open a new dev line");
+  const result = runGate(dir);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /0\.8\.0-dev -> 0\.9\.0-dev/);
+});
+
+test("a missing dev schema at HEAD fails rather than passing vacuously", (t) => {
+  const dir = scratchRepo(schemaWith({ keep: { type: "string" } }));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeVersions(dir, "0.9.0-dev");
+  commit(dir, "point at a dev line that does not exist");
+  const result = runGate(dir);
+  assert.equal(result.status, 1, result.stdout);
+  assert.match(result.stderr, /missing at HEAD/);
+});
+
+test("an unparsable dev schema fails with the file named", (t) => {
+  const dir = scratchRepo(schemaWith({ keep: { type: "string" } }));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeFileSync(
+    join(dir, "schemas", "dev", `mxc-config.schema.${DEV_LINE}.json`),
+    "{ not json"
+  );
+  commit(dir, "corrupt the dev schema");
+  const result = runGate(dir);
+  assert.equal(result.status, 1, result.stdout);
+  assert.match(result.stderr, /not valid JSON/);
+});