validator,converter,driftguard: generate the version gates from the matrix

[erraggy]

Epic D — Derive the field/version matrix and generate from it · Size XL · Release v1.61.0 · Blocked by: 438

Problem

The 3.2 field inventory is currently maintained twice by hand, in validator/oas32_gate.go and converter/detectOAS32Features. #420 and #424 were both drift between the two copies. Separately, the parser structs are a third hand-maintained statement of the same knowledge — #397 (16 fields across 11 objects), #411, #414 and #422 were all "a field exists in the spec, not in the model".

D1 produces the matrix. This issue makes the matrix the single source and generates the rest.

This is the multi-package bite this repo is built for.

Scope

1. Drift-guard parser structs against the matrix. Closes failure mode A permanently — OAS 3.2.0 fixed fields are unmodeled across 11 objects, and are silently dropped from JSON documents on round trip #397, validator: OAS 3.2-only fields are accepted in 3.0 and 3.1 documents #411, parser/schemautil: nine more fields dropped on JSON round trip, and three more hash collisions #414 and fix(validator): report OAS 3.2 fields used by documents that predate them #422 become unrepeatable. A field in the published schema with no corresponding struct field fails the build.
2. Generate validator/oas32_gate.go, replacing 23+ hand-written report(field, ref) calls.
3. Generate converter/detectOAS32Features, retiring the second hand-maintained copy.

Watch

#430 — detectOAS32Features allocates a visited map per media type and per component schema. The generated replacement must not reintroduce it. Generating a slower version of a function that already has a known allocation bug would be a regression dressed as an improvement.

Acceptance

• validator/oas32_gate.go and converter/detectOAS32Features are generated, with a go:generate directive and a CI check that the committed output matches a fresh run.
• A parser struct missing a field the matrix lists fails a drift guard, naming the object and field.
• The conformance suite from B2 stays green, and the corpus verdict changes are reviewed rather than assumed — a big expected-error delta is evidence to verify, not a regression to panic about.
• No new per-item allocation in the generated detectOAS32Features; benchmark allocs/op is not worse than the hand-written version.

Release note framing

Generated gates will surface fields the hand-written ones missed, so expect verdict changes again — tightening this time, the opposite direction from v1.60.0.

Files

validator/oas32_gate.go (becomes generated), converter/oas32_features.go (becomes generated), internal/driftguard/, internal/codegen/

---

Design: 2026-08-01-spec-conformance-gap-design.md · Plan: 2026-08-01-spec-conformance-gap-plan.md