openapi: yaml-decoding misstates which deep-merging roots detection declines #1107

Problem

docs/compilers/openapi.md#yaml-decoding says which roots detection declines when their merges run past the depth it reads:

A root that merges deeper than that reading expands, writing no version of its own, is declined as an openapi/budget-exceeded error, since a version past the bound may outrank one found above it.

A root that writes a version of its own is declined too when that version is swagger's. This one merges 65 levels deep and writes swagger: '2.0' itself:

python3 -c '
print("l0: &a0 {x: 1}")
for i in range(1, 65): print(f"l{i}: &a{i} {{<<: *a{i-1}}}")
print("<<: *a64\nswagger: \"2.0\"\ninfo: {title: t, version: \"1\"}\npaths: {}")' > swagger-deep.yaml
go run ./cmd/morphic validate swagger-deep.yaml; echo "exit=$?"

error openapi/budget-exceeded swagger-deep.yaml: source cannot be recognized: its root mapping merges through `<<` deeper than 64 levels, past which a version it declares is not read
exit=1

The same root writing openapi: 3.1.0 in place of swagger is recognized and compiles. A reader of the rule would expect the swagger root to be recognized as swagger@2.0 as well.

The behaviour is right and the rule's wording is what falls short. Detection reads openapi before swagger, so an openapi key past the bound would outrank the root's own swagger. What the code requires is narrower than "a version of its own": the root's own keys must settle the answer, which they do when the root writes openapi with a version, or writes both keys.

Cause

settledByOwnPairs in compilers/openapi/detect.go (compilers/openapi/internal/detect/probe.go once #1104 lands): own["openapi"] && (isVersion(probe.OpenAPI) || own["swagger"]).

Direction

A draft: state the condition the code checks. "A root that merges deeper than that reading expands is declined as an openapi/budget-exceeded error unless its own keys settle the version: it writes openapi with a version, or writes both keys. A version past the bound may outrank one found above it."

Out of scope

The behaviour, which stays as it is.

Related: #1104

Priority: P4, rule 1 (a docs task that changes no lowering, validation, IR or emit-contract behaviour). morphic validate swagger-deep.yaml → openapi/budget-exceeded, exit 1 (morphic @2683dee3).