openapi3: store field locations in a slice, not a map

[reuvenharrison]

Why

Origin.Fields is map[string]Location. A collection carries a handful of scalar fields, but a Go map allocates a whole bucket per collection whatever it holds, so these maps dominate the retained size of a parsed document.

Profiling a 16.8 MB spec loaded with IncludeOrigin, originFromSeq (where the inserts happen) allocated 339 MB, 13.9% of the total. With the slice it drops out of the top six entirely.

What

FieldLocations, a slice in document order. Each Location already carries its Name, so the lookup key costs nothing extra, and a linear scan beats a map at these sizes.

• Get(name) returns a location or the zero value; Lookup(name) also reports presence.
• MarshalJSON / UnmarshalJSON keep the serialized shape a name-keyed object, so output is unchanged.
• Lookup is a hand-written loop rather than slices.IndexFunc on purpose: the closure does not inline, so IndexFunc pays a call per element. Measured on 3/6/12 fields it is 5-100% slower on a hit and 2-3x slower on a miss, and misses dominate (most fields carry no recorded location). A comment says so, to save the next reader from "modernising" it.
• sort.Slice becomes slices.SortFunc at the two name-ordering sites, since sort.Slice swaps through reflection.
• A small copy is removed: recordMapKeyLocations built a whole *Origin purely to read its Fields, then copied that slice into a second one and discarded the rest. Nothing else holds it, so it is sorted in place and handed over.
• Sequences deliberately stays a map; the reasoning is on the Origin type.

Results

16.8 MB spec, IncludeOrigin, median of 3 (peak from 7 runs):

	peak RSS	total allocated	retained
before	933 MB	2401 MB	478 MB
after	918 MB	2176 MB	253 MB
	-1.6%	-9.4%	-47%

Retained is the target. A differ holds two documents resident for the duration of a comparison, so this halves the floor of the whole operation rather than of one load.

What about the largest allocator?

Fair question, since originFromSeq is the second flat entry, not the first. The ranking on master:

362 MB 14.8%  encoding/json.(*decodeState).objectInterface
339 MB 13.9%  openapi3.originFromSeq                        <- this PR
272 MB 11.2%  reflect.unsafe_New
224 MB  9.2%  yaml3.(*parser).node
162 MB  6.6%  reflect.mapassign_faststr0
134 MB  5.5%  encoding/json.Unmarshal  (cumulative 1005 MB, 41%)

The leader is the JSON decode, and cumulatively it is far larger than anything here: json.Unmarshal accounts for 41% of allocation. That is the YAML -> map[string]any -> JSON bytes -> json.Unmarshal round trip the yaml wrapper performs to reach types that implement UnmarshalJSON. It is a real target, but a much larger change to how documents are decoded, not to how origins are stored, so it is deliberately out of scope here and filed separately as getkin#1236 for discussion.

The two also compete for different resources, which is the substantive reason not to sequence one behind the other. The JSON decode's allocations are transient -- garbage by the time the load returns. The origin maps are retained for the document's lifetime. That is visible in this PR's own numbers: retained falls 47% while peak moves 1.6%, because peak is dominated by the transient parse and decode that this change does not touch. Fixing the round trip would move peak and throughput; it would not move retained.

Breaking change

Origin.Fields changes type, so origin.Fields[name] no longer compiles. The mechanical replacement is origin.Fields.Lookup(name), same (Location, bool) shape. for range over Fields and len(Fields) are unaffected.

For scale: adapting oasdiff, a heavy consumer of this API, took 5 call sites and 13 test fixtures.