Built-in schema version: is never bumped when rules change — drift surfacing (#431) and any future pin/gate are uninformative without a bump discipline

[avrabe]

Friction (found while implementing #431 / REQ-205)

I added schema-version surfacing to rivet validate and rivet schema sources (#431 option 3, PR #483) — but then noticed the surfaced version is uninformative, because the version: field is effectively dead: it's never bumped when a schema's rules change.

Evidence (verified)

• Every built-in schema reports version: 0.1.0 — except aspice (0.2.0). So the bump discipline exists in exactly one schema and nowhere else.
• schemas/common.yaml has been changed by 8 commits, several of which materially changed validation (e.g. f2ecf31 REQ-162 status lifecycle / status-allowed-values; bfebc59 federation fields; 1741bbf external-anchor cited-source field) — yet 0 commits changed its version: line. git log -S'version: 0.1.0' -- schemas/common.yaml → 0.

So a consumer on the embedded common schema went from "no status-allowed-values rule" to "status-allowed-values enforced" with the version staying common@0.1.0 the whole way. The exact silent-change #431 is about — and the version field that should signal it didn't move.

Why it matters

This blunts the fixes layered on top of it:

• Embedded (builtin) schemas are binary-versioned, not pinned — upgrading rivet silently changes validation (new diagnostics on unchanged artifacts) #431 option 3 (surfacing, now shipped): Schemas: common@0.1.0 (embedded) looks reassuring even across a release that tightened common — because the version didn't change.
• Embedded (builtin) schemas are binary-versioned, not pinned — upgrading rivet silently changes validation (new diagnostics on unchanged artifacts) #431 option 2 (pin + gate): pinning common@0.1.0 in rivet.yaml would never trip, because the embedded copy is also 0.1.0 despite different rules.

The version needs to actually track schema content for either to work.

Suggested fix

1. Bump discipline: bump a schema's version: (semver: minor for new/tightened rules, patch for fixes) in the same commit that changes its rules.
2. CI gate (the durable enforcement): a check that fails (or warns) when a PR's diff touches schemas/<name>.yaml rules but leaves schemas/<name>.yaml version: unchanged — analogous to the existing docs-check / commit-traceability gates. rivet already parses the version (embedded::schema_version_of), so the check can compare against the merge-base.
3. Optionally, a content hash in the surfacing (common@0.1.0#a1b2c3) so even an un-bumped change is visible — belt-and-suspenders if the bump is forgotten.

Found in the hourly dogfooding loop while shipping #483. Related: #431 (the surfacing this depends on).

[avrabe]

Implemented the enforcement half in PR #486… correction: PR for this is up — scripts/check-schema-version-bump.sh + a warn-only schema-version-bump CI job (pull_request, fetch-depth 0). Verified locally: it warns on the real common.yaml no-bump case (commit f2ecf31), exits 1 under STRICT=1, and passes a no-schema-change range. Warn-only to start (a comment/whitespace edit needs no bump), matching the docs-check coverage gate; flip to STRICT once versions are disciplined. The remaining data fix (actually bumping the schemas that have already drifted) is left as a follow-up since it's a semver judgment per schema.