[OmarAlJarrah]

Summary

A schema keyword reached the IR only on some of the outcomes a schema lowers through. Three outcomes returned before the keyword census ran, the gate that gives a shared position a node of its own never asked about what the census keeps, and a null was read a different way depending on the keyword and the node it sat on. On Cloudflare's schema this loses minimum and maximum beside the oneOf of spectrum-config_origin_port.

Every outcome now answers the census:

• A Union keeps what it has no field for, a value bound included.

• A type array and a distributed union ask their variants, since each variant is built from the schema itself. What a variant consumes is neither kept nor reported, and anything else is kept on the union. A format beside a distributed properties is kept; the properties are not.

• An expanded $dynamicRef lowers to a reference, so it takes a $ref site's census with a collapsed union (referenceOutcomeKeywords), and a carrier reaches the same function.

• A parameter keeps what a property and a header keep. Its filler carried its own copy of that list, which had lost the content vocabulary and an unexpanded $dynamicRef, so both vanished without a report. All three carriers now go through schema.PreserveCarriedKeywords, so they cannot drift again.

The hoist gate reads what the census would keep (annotation.WritesUnknownKeyword, undefinedKeywords) rather than a second list, so an unknown keyword, and a nullable the dialect does not define, lands on an alias at a position with no node or carrier.

A null for a Schema Object keyword reads as the keyword left out. That is decided once, in annotation.RawPropertyNode, which every keeper goes through, rather than per keeper, with const, default and example excepted because their value is an instance. schema.writesType and effectiveTypes do the same for type, which the parser decodes as a type spelled "" (docs/parser-library.md#null-type-is-empty, with its canary). unmergedBranchKeys lists keys rather than asking for one, so it asks annotation.WritesKeywordLeftOut. The two readers of the raw tree that decide whether a $dynamicRef expands read it the same way: a null $id starts no resource, and a null $dynamicAnchor is no anchor named null. The table grades every such null as a field left out, numeric bounds included, whose shape it otherwise leaves to the lowering.

Why #847 and #764 are in here

An unknown keyword beside a $ref now hoists an alias, and an alias is exactly what a mapping misses, so a document that compiled with the keyword silently dropped would have started failing pass/discriminator-missing-variant. Two shapes reach it, and fixing only the first would make this PR worse than main on the second.

A mapping naming a component a branch aliases (#847). A mapping target now routes to the variant whose branch names it (referencedVariants). That reads the branches, not the registry, so it turns on no lowering order. Two options were open in the issue: route in the lowering, or teach validation to read through aliases. The lowering is the right side because an emitter routes by Mapping, which has to name a variant.

A type two branches name maps to neither, in either branch order. If one of them is the type itself the mapping stays on that variant, and if both alias it the pass reports it, which is the stated rule the issue asked for, though it refuses a valid document (below).

A mapping naming a position whose $ref has something beside it (#764). readsThrough used to stop there, keeping an alias that is no variant or subtype. It no longer asks what is beside the $ref, only whether the position is itself a variant, so the mapping means what the $ref names. That also retires refSiteHomesNothing.

Behaviour to check on review

• type: null is the keyword left out, as openapi: a null schema keyword is read three ways and draws an error #1069 proposed. Real documents write this unquoted in an anyOf branch, most likely meaning "null". openapi-generator's 3_1/null_schema_test.yaml and 3_1/simplifyOneOfAnyOf_test.yaml go from exit 1 to exit 0 under a warning that says how it was read, and such a branch lowers to the top type. An author who meant "null" gets a wider type and a warning, not a refusal.
• A position with an unknown keyword now owns an alias where it used to resolve to the shared node, which is what Expected in openapi: an unknown schema keyword at a position with no node or carrier is dropped #1053 asks for.
• A mapping to a type two branches alias stays refused, and more documents reach that. oneOf: [{$ref: X, k: 1}, {$ref: X, k: 2}] with a mapping to X goes from exit 0 to exit 1: main drops an unknown keyword, which now gets an alias as a description already does, and main refuses the description spelling the same way. No spec in testdata or morphic-references goes to exit 1, and openapi: a mapping to a type two union branches alias is refused #1298 tracks the refusal.
• A type array's value bound is homed on any variant with a Constraints field. type: [integer, object] with minimum: 1 puts min on the object variant and none on the integer, on main as here; the census counts that as homed rather than keeping it on the union (openapi: a type array's bound lands on a variant it cannot constrain #1310).
• A keyword written null beneath itself still misreads. items: {type: string, items: null} turns the outer items into the false schema, on main as here, since the parser decodes that body as a boolean (openapi: a keyword failing to decode beneath itself turns the outer schema false #1299).

Test plan

• For every keyword of the schema table at 3.0.3, 3.1.0 and 3.2.0, at 17 positions and 24 outcomes, 58,786 pairs compiled with the keyword and without it, comparing IR and diagnostics past the source hash and line numbers, with irverify on each. Identical output means it vanished silently: 6,015 pairs on main and 3,078 here, with 2,937 fixed and no pair worse, and no violation on either. The 3,078 are 2,888 for the four exemptions docs/compilers/openapi.md#vocabulary-coverage names, and 190 where the keyword says nothing new: a type a string enum already implies, an allOf: [{type: object}] on an object, and a 3.0 nullable on a component nothing references. This check is a throwaway script; the conformance cases and operation.TestParams_KeepWhatAnyCarrierKeeps hold the shapes.
• e2e.TestCompile_ANullKeywordLowersAsTheKeywordLeftOut reads every keyword off the table at 3.0.3, 3.1.0 and 3.2.0, in four positions and several contexts, and requires the IR to equal the same document with the key removed. It found what a list of the issue's examples would not: a 3.0 exclusiveMinimum: null, a 3.0 $ref: null still reading its siblings as beside a $ref, dependentRequired and $vocabulary, which have no model field, and an allOf branch counting a null as residue. e2e.TestCompile_ANullIdentifierLowersAsTheKeywordLeftOut holds the two readers that sweep cannot reach, as it writes no $dynamicRef. A wider throwaway run of 54,740 pairs, adding a union, a type array and a $ref as what each keyword sits beside, differs only under not and in an allOf branch, which keep the schema verbatim, and at openapi: a keyword failing to decode beneath itself turns the outer schema false #1299's shape. A third run of 136,568 pairs adds outcomes (type arrays mixing scalars with objects, a discriminated union, a distributed union with allOf or required, a tuple, a 3.0 nullable), positions (component parameters, headers, bodies and responses, path-level parameters, callbacks, encoding headers, propertyNames, if, contentSchema) and a second value per keyword, each empty or falsy: none is worse than main, 6,414 are fixed, and what both builds leave alike is a value that states nothing, such as title: '' or deprecated: false, or openapi: unevaluatedProperties false on a position lowering to no model is dropped #1283's shape.
• New conformance cases with goldens: keywords-at-every-outcome, unknown-keywords-at-shared-nodes, null-keywords, discriminator-aliased-branch.
• 44 planted defects across the guards this adds, each confirmed compiling and each reddened by a named test. Survivors along the way showed four redundant guards in the mapping code, since removed, and gaps in the sweep and in the tests of a routed defaultMapping and of a null $ref outside a Schema Object, since filled.
• sweep.py with --verify against main over testdata and morphic-references (2,175 specs): 1,652 stay 0, 519 stay 1, 4 go 1→0 (the two specs above and two of the new cases, which main refuses), and none get worse. 16 specs differ. I read the 12 real-world ones and each is one of: a bound beside a union kept (api_constrained, anyOf.json), $recursiveRef at a branch kept, a null error turned warning, or an invalid type, such as an unquoted type: [string, null], no longer lowering a variant for the empty type.
• Injecting a keyword beside every $ref, beside every type, and a bound and a format beside every oneOf, anyOf and type array, into 1,396 documents drawn from those two corpora, through harness.Check on both builds: nothing panics, nothing breaks irverify, determinism or order-invariance, and the one spec going ok to error is the openapi: a mapping to a type two union branches alias is refused #1298 shape above. Compared with the same spec before injection, with each alias the keyword minted read through to its target and its own entry set aside, every type, property, parameter and mapping is unchanged.
• Cloudflare's openapi.json @319dc756af: one new info, at spectrum-config_origin_port, and that type's unmodeled is the only change to the type registry.
• BenchmarkCompile_Petstore: 52 more allocations of about 12,051 (0.4%), and on Cloudflare's schema 0.3% more instructions retired, medians of three alternating runs whose ranges overlap. A first version returned a slice from a helper, which pushed GetType's stack-allocated slice to the heap at every read; a profile diff found it, and the predicate that replaced it does not.
• CI's gate on the final head: go test ./... -race with morphic-covergate at 100% of statements, vet, build, lint and the planted-lint check.
• A trial merge with feat(compilers/openapi): read each document's schema identifiers #1227, which deletes internal/anchors and declaresResourceIDAbove, passes go test ./compilers/openapi/internal/schema ./compilers/openapi/internal/bind and the e2e conformance, lowering-spec and null tests, as bind already reads a null identifier as left out. It conflicts in five files, the dynamic-ref rule among them, and needs two fixes no conflict marks, which that PR lists. TestBuild_ANullAnchorNamesNothing and its citation in null-keywords go with the package. fix(compilers/openapi)!: lower allOf by what its conjuncts say #1269 conflicts in five files and adds a caller of collapsedUnhomedKeywords, which this removes, feat(ir)!: type the secrecy and stability a document states #1229 conflicts in three, and fix(compilers/openapi): treat a restated union branch as bare #1278 in docs/compilers/openapi.md.

Closes #848
Closes #852
Closes #1053
Closes #1069
Closes #847
Closes #764