openapi: move document lowering and detection's byte reading out of the root package #1091

Problem

docs/micro-compiler-design.md §5.1 lays out compilers/openapi as "the public face, and nothing else": openapi.go (Compiler, New, Formats, Compile) and options.go (Options, GroupingStrategy). At ff8330ba the package also holds:

• meta.go (290 lines): document-level lowering. That is the info object, the extensions and unknown keys of the root and its tags, the retained component sections, the JSON Schema dialect and component media types. It has one entry, lowerMeta, which run calls. It imports ir, the parser library's openapi package and five internal packages (annotation, diag, ids, lowering, nodeview), and from its own package it calls only lowerServers.
• Most of detect.go (488 lines): how detection reads a source. Detect is the face. Beside it sit a byte scan of an unreadable source for a discriminating key (declaresProbeKey through versionAfterColon) and the probe of a decoded tree (sniff through majorMinor, with the sniffProbe type).

The next compiler copies this package's shape (#469, #470), so its root shows what a root holds.

wc -l compilers/openapi/*.go
grep -n 'lowerServers\|lowerMeta' compilers/openapi/meta.go compilers/openapi/openapi.go

Direction

A draft; the package names are placeholders.

• internal/document takes meta.go.
  • lowerMeta calls lowerServers, which stays in the root package (below). A package beneath the root cannot call it, so the server lowering is handed in. run calls document.Lower(c, lowerServers), and the entry's signature gains servers func(lowering.Ctx) ([]ir.Server, []ir.Diagnostic).
  • That keeps the diagnostics in the order they are reported today. run calling lowerServers itself would move the server diagnostics after the dialect, media-type and unknown-key ones.
  • §5.1 put meta under operation/. It is a package of its own instead, for two reasons. auth, which §5.1 also put there, already left for a package of its own. And document-level metadata is no part of lowering an operation.
• internal/detect takes the byte scan and the decoded-tree probe.
  • It exports what Detect reads: sniff, declaresProbeKey, majorMinor, and the sniffProbe type, whose Cut, OpenAPI and Swagger fields Detect switches on.
  • Detect, detectionBudget and recognized stay in detect.go, because they read the compiler's Options and return its Recognition.
• Each new package gets its rule in internal/archtest/arch_test.go, with a comment saying where it sits and why. internal/document's allowlist names ir, the library's openapi package, annotation, diag, ids, lowering and nodeview.
• Tests follow the code.
  • Tests that drive the public API stay in compilers/openapi.
  • Tests in package openapi that call a moved function (detect_test.go, detect_reading_test.go, meta_test.go) move with it, or reach it through the package's exported entry.
• References that name the old files are updated:
  • docs/architecture.md §2's "version sniffing (detect.go)" points at the new path. Sniffing still stays in the OpenAPI compiler, as that section decides.
  • The two overlay_test.go cases labelled meta.go documentExtensions and meta.go documentUnknownKeys name the new file.
• servers.go stays, as openapi: move server lowering out of meta.go into servers.go #1055 records: path-item and operation servers will need lowerServer once ir: decide whether four no_ir_home operation constructs get real fields #285 gives them a field, and that change decides its home.

Done when

• Goldens, the harness sweep over testdata/ and every diagnostic, in order, are unchanged.
• Apart from the exported names, their qualifiers and the entry's added parameter, each moved declaration is byte-identical with its doc comment.
• ls compilers/openapi/*.go (tests aside) lists doc.go, openapi.go, options.go, detect.go (holding Detect and its two helpers) and servers.go.

Priority: P4, rule 1 (housekeeping: moves code between packages and changes no lowering, validation, IR or emit-contract behaviour). wc -l compilers/openapi/meta.go compilers/openapi/detect.go → 290 and 488 (morphic @ff8330ba).