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

[Gudge (MGudgin)]

Stacked on #731. Base is user/gudge/versioning_phase7c_detector_lib; review the top commit only.

Summary

This PR adds a CI gate that compares the dev schema at the pull-request base against the dev schema at HEAD and fails when the new one rejects an instance the old one accepted.

Every other breaking-change guard compares RELEASED stable schemas, and only at release time. The surface a pull request actually edits -- the dev schema -- is unguarded, so a change can delete a stable field, regenerate the schema and the SDK types, migrate the config corpus, and merge green. PR #676 did exactly that, and was reverted by hand.

Details

• scripts/versioning/check-dev-schema-compat.js resolves the base commit with the fail-closed helper, reads both dev schemas out of git, and reports every structural restriction the compatibility detector finds.
• Each side is read at its own declared devSchemaFile. Opening a new dev line copies the outgoing one, so the documents stay the same lineage and the comparison holds across that transition. Skipping the comparison when the line moves would let a change disable the gate by editing one line of schemas/schema-version.json.
• A missing or unparsable schema on either side fails. The gate is only useful if it cannot succeed vacuously.
• There is no per-field escape hatch. The supported-version window is what allows surface to end, so until a change moves that window, a config declaring an already-supported version has to keep parsing.
• Documented in .github/copilot-instructions.md alongside the other schema gates, including how to make a breaking change additively, since this gate is what a contributor meets when they try to remove surface.
• Runs ahead of corpus validation, because a change that removes a field also migrates the corpus; validation then passes and the removal is what needs reporting.

Tests

• 8 end-to-end tests drive the real CLI against throwaway repositories and assert on its exit code: unchanged and additive schemas pass; a removed property, a narrowed type, a missing schema and an unparsable schema all exit 1; a compatible new dev line passes and reports the move; and an incompatible new dev line is still blocked.
• Replayed against PR Bring network wire schema to full GA spec (wire.rs + config fixtures only) #676: the gate exits 1 and names all six removed network fields.
• Run against the repository as it stands, the gate passes, as do check-schema-versions.js and corpus validation across 195 configs.
• Full versioning suite: 71 tests.

Note for reviewers

The gate blocks the dev schema accepting less than it did, which is not the same as blocking breaking changes. Because one dev schema validates configs declaring every supported version, surface a supported version can use has to remain in it. A breaking change is made additively -- keep the old fields, add the new shape alongside -- and the supported-version window (a later phase) governs which may be used at which version. Deleting becomes legitimate only once min rises past the surface being dropped.

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

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

[Copilot]

Pull request overview

Adds a CI gate to prevent the development schema from becoming structurally more restrictive.

Changes:

• Adds the compatibility gate and eight integration tests.
• Runs the gate before corpus validation.
• Documents the additive schema-evolution policy.

Show a summary per file

File	Description
scripts/versioning/check-dev-schema-compat.js	Implements base-to-HEAD comparison.
scripts/versioning/tests/dev-schema-gate-integration.test.js	Adds end-to-end gate coverage.
scripts/versioning/package.json	Exposes the gate as an npm script.
.github/workflows/Versioning.Checks.Job.yml	Adds the CI check.
.github/copilot-instructions.md	Documents compatibility requirements.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

scripts/versioning/check-dev-schema-compat.js:89

• The gate never reads or compares versions.min, so advancing the supported floor does not make an expired field removable: detectBreaking will still report that deletion and fail. This contradicts the remediation printed below (and the documented policy that deletion becomes legitimate after min passes the field's window), leaving no working retirement path. Please make the comparison version-window-aware and add an integration case where min advances past an x-mxc-until field, or stop claiming that moving the window permits deletion.

const findings = detectBreaking(baseSchema, headSchema);

.github/copilot-instructions.md:143

• This new blanket rule conflicts with the existing experimental-schema contract in docs/versioning.md:120-125 and src/core/wxc_common/src/wire.rs:430-434, which says the experimental surface is in flux and may iterate without a stable compatibility promise. Because the gate compares the complete schema, narrowing a known experimental field now fails CI. Either scope compatibility enforcement to the stable surface or update the versioning policy and contributor documentation to explicitly establish the stronger experimental guarantee.

- **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.

• Files reviewed: 5/5 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

scripts/versioning/check-dev-schema-compat.js:99

• Raising min cannot actually make this remediation succeed. The gate passes only the two schema documents to detectBreaking; it never reads either min, and the detector explicitly ignores x-mxc-until. Therefore deleting an expired field still produces the same finding even if this change raises the supported-version window (and a follow-up PR also compares against a base schema that still contains it), so the new gate permanently prevents the documented deletion path. Please make the comparison account for fields whose until is below the new minimum, or define another safe baseline-rotation mechanism, and cover that lifecycle with an integration test.

    `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.`,

• Files reviewed: 5/5 changed files
• Comments generated: 0 new
• Review effort level: Balanced