fix(compilers/openapi): scope the key scan, keep the read's error

[fuad-daoud]

Breaking — see the last section. Fixes the defects two adversarial reviews of the whole stack found in stack PR 1, which the per-commit gates could not see.

#420's fix missed malformed JSON

decodeFlowEntries returned (probe, true) whenever the input opened with {, swallowing a mid-stream JSON error. That contract is correct for a cut prefix (the cut always errors) and wrong for a whole document, which the new sniffWhole reuses it for. So a >64 KiB JSON document whose openapi key sat behind a syntax error still reported unrecognized-format — the outcome PR 1 says it replaced.

Correction to an earlier version of this description, from the review on PR 1: this was never the motivating case. Valid JSON — Stripe's spec3.json — worked in PR 1 from the start: the cut prefix yields an empty probe, and sniffWhole then reads the whole document successfully. Only malformed JSON was missed.

The key scan was not top-level-scoped

"openapi": matched at any nesting depth, anywhere in the buffer. On main that was bounded to 64 KiB; PR 1 removed the bound without tightening the predicate. So a foreign document nesting an "openapi" key paid a full parse, and one that also failed to parse could be reported as openapi/undecodable-source — this compiler claiming bytes that are not its own, which detect.go's own comments forbid.

declaresProbeKey is now declaresBlockKey (bare name at column 0, unchanged) OR declaresFlowKey, the latter requiring the source to open a flow mapping and matching only at depth 1. The 64 KiB bound was not reinstated.

Measured before/after on six >64 KiB inputs, and against a main binary — every case is at least as good as main, and four are better. Both fixes were mutation-checked: swallowing the error again reddens the new flow test; restoring the unscoped scan reddens 7 subtests.

One deliberate loss, for your judgement: a block YAML document quoting its top-level key ("openapi": 3.0.0 at column 0) past the cap is no longer detected. Admitting that would re-open the hole for zero-indent JSON, which json.MarshalIndent(v, "", "") really produces. Against main nothing regresses — that shape was declined there too.

Detection parsed the whole document to find one key

sniffWhole ran yaml.Unmarshal over everything past the cap, ahead of the loader's size and node budgets and with no context to cancel it. Measured inside Detect: 32 MB cost 805 ms and 333 MB, for a file the node budget then refused anyway; main declines it in 11 ms. The earlier commit on this branch scoped the key search but deliberately did not reinstate a bound.

The scan the guard already ran now reads the value beside the key, which answers the whole question without building a tree:

	before	after
8 MB	209 ms / 82 MB	1.9 ms / 0 allocations
32 MB	805 ms / 333 MB	4.1 ms / 0 allocations

Reading the value closes two more holes the review found:

• Key order no longer decides the format. The prefix answered on whichever key it reached and returned, so {"swagger":"2.0", …64 KiB…, "openapi":"3.0.3"} read as swagger@2.0 above the cap and openapi@3.0 below it — one document, two answers, which is exactly the property TestDetect_KeyOrderDoesNotDecideTheFormat claims to pin.
• A key alone is no longer a declaration. Prose beside the word — openapi: is a format at column 0 in a Markdown file, at any size — is declined in silence instead of claimed and reported under this compiler's parse error. That also fixes the same shape below the cap, which predates the stack: main reports such a file as openapi@is a format.

BREAKING. Detection past the cap no longer emits undecodable-source; it cannot, having read one key rather than the document. A source it names and the loader cannot parse is now the compile's finding, so openapi.Compile turns load.ErrParse into that diagnostic instead of returning a Go error. That conversion is not cosmetic: engine.Run wraps a compiler's Go error in its own, and the CLI maps that to exit 2 — the code it uses for being invoked wrong — so without it a broken spec would be reported as a misuse of morphic. Exit 1 and the diagnostic are preserved end-to-end, and the message now carries the loader's own position instead of a throwaway parse's. A document past the cap that declares the key with no version beside it is declined rather than claimed: a scan cannot tell that from another format's file, and claiming the wrong one of those two is the costlier mistake.

The prefix machinery goes with the parse it existed to avoid — sniffPrefix, sniffWhole, decodeFlowEntries, wholeLines and the entry cap.

On the review's test finding. All six mutations the review planted stayed green on this branch. Twelve against the new code — including all six where they still apply — are all caught. Adds the engine.Run case the review asked for, over a generated >64 KiB JSON with the version last: nothing else in the suite reaches that path, the corpus's largest spec being 7 KiB. Adds the cap-boundary cases too, where a broken document is what tells the two readings apart — a document both can read cannot, which is why an off-by-one there survived until now.

A doc sentence

ir-design.md §12 rule 4 read as if the rule had no live instances after PR 3 gave Parameter its Provenance. Variant and EnumMember still are ones; they are now named.

---

Stack 7 of 8. Base stack/6-constraints — review and merge bottom-up. Every commit here passed make gate when it landed, and the full gate was re-run on the top of the stack. Run it as GOTOOLCHAIN=go1.26.3 make gate; this machine's Go 1.27 fails it for reasons unrelated to any change (#431).

🤖 Generated with Claude Code

https://claude.ai/code/session_01SYeBgDsskwnyitLgPGCPn1