Block breaking changes to the dev schema at pull-request time

.github/copilot-instructions.md

@@ -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/`)

.github/workflows/Versioning.Checks.Job.yml

@@ -50,5 +50,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

scripts/versioning/check-dev-schema-compat.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.`
+);