spec: general referential-integrity gate — every $ref must resolve

[mdheller]

Closes the pending register item: make spec pointer-resolution a general validator that excludes itself.

The gap

334 schemas, ~135 $ref links — but the per-example validators only exercise schemas that ship examples. A schema declaring a $ref to a moved / renamed / mistyped target sails straight through: nothing loads it, so nothing notices the reference resolves to a hole. That is the declared-not-enforced defect at the spec's own reference layer.

The gate

tools/validate_schema_references.py asserts, for every schemas/*.json:

1. valid JSON and a structurally valid JSON Schema (Draft 2020-12 metaschema check_schema);
2. every $ref — internal #/…, relative File.json (optionally #/fragment), or canonical $id URI — resolves to a real schema and a real pointer target inside it.

Self-excluding + teeth

• Excludes itself: scan targets schemas/ only; the validator lives in tools/, never in the scanned set.
• Proves its own teeth every run: an inline synthetic negative control (dangling file ref, dangling internal pointer, file+fragment miss, malformed schema, + valid counterparts), built in memory, never touching schemas/. If it fails to trip, the gate exits 2 and certifies nothing.
• Fails closed on an empty scan.

Result

OK: 334 schemas structurally valid; all 135 $refs resolve to a real target

Wired into make validate (CI runs it via validate-ops-history.yml), so the spec enforces its own referential integrity going forward — same shape as the moving-tag ratchet: clean today, kept clean by a gate that can actually fail.