[OmarAlJarrah]

Summary

A security requirement naming a scheme the document does not hold was dropped, and what was left said something else:

• an operation whose every option named one had auth absent, which reads as inheriting the service's security, so an SDK would send the account's credentials to an endpoint that names its own;
• a document whose every option named one had no Service.Auth, so every inheriting operation read as having no requirement;
• a list holding other options lost that one: [{a: []}, {b: []}, {}] with nothing declared lowered to [{}], which says no auth is needed;
• an option ANDing such a name with a declared scheme went whole;
• a name whose value reads as no list of strings was never read at all: - key: with nothing after the colon lowered to [{}], no auth needed, with key declared, and an AND lost that member;
• a list of scopes holding a plain date, which OpenAPI reads as a string, went the same way with nothing reported: {key: [read, 2021-01-01]} lowered to [{}].

Now every option lowers whole, with its other schemes, its scopes and its place in the list, and the name lowers to a scheme of the new kind unresolved, one per name, in a namespace of its own:

{"schemes": [{"scheme": "auth/unresolved/components/securitySchemes/pages_upload_token"}]}

No field is added, so OR-of-ANDs, priority order and scopes need no new reading. The kind says what the compiler holds, which is no mechanism, and not that the source states none: docs/ir/auth.md records that, the premise as measured, and each design rejected with the input it fails on. irverify holds the kind and the namespace together both ways, for documents no compiler here wrote as well, and reports such a scheme that states how to authenticate. The dangling-reference check stands: a minted scheme is a real entry. AuthKindUnresolved and the namespace sit in ir and compilers/compile because a second format needs them: AsyncAPI 2's Security Requirement names a scheme by its key under components the same way.

The finding stays an error. The specification requires the name to correspond to a scheme, and docs/compilers/openapi.md#validation makes a finding an error where the document's meaning is missing, as it is for a tag's parent or a path template variable that names nothing. So a document that drew this exits 1 as before, and a run a caller has not told otherwise still starts no emitter. The code changes, from openapi/unresolved-ref to openapi/unresolved-security-scheme, because after an unresolved reference what it named is gone, and here it is not: a caller accepting this finding need not accept a lost reference with it, which is what the per-code override #691 proposes.

An entry naming no mechanism keeps what it wrote. An entry with no type, an http entry with no scheme, and an entry resolving to no object lower to the same kind at their own pointer, whether or not a requirement names them. This departs from what #294 settled, on purpose: it dropped such an entry's text because no node could hold it, and now one does. The description and deprecated reach the scheme, its type and each mechanism field stay verbatim under Unmodeled, a $ref that reached nothing stays there too with only the error it already drew, and the error at the entry now says that the entry and its requirements are kept. An entry written as no object holds no field to keep. A $ref the model does not decode, such as a plain date, read as no reference and lowered to nothing with no report at all; it now draws openapi/unresolved-ref at the entry, so no scheme of this kind goes unreported, and the summary and description beside it stay, which the model does not hold either.

auth.Registry holds the schemes, the way servers.Registry holds servers, so the lowering context no longer carries them and Ctx.WithAuth and Ctx.DeclaresAuth go.

The emitter contract gains what an SDK does (docs/emitters/operations/auth.md#unresolved-schemes, T-28): the option stays in place, its credential comes from an Authenticator the caller writes, and unconfigured it is an unsatisfied credential, so the selector takes the next option and with none left refuses the request unsent, naming the scheme. It never sends the service's credentials in its place, and a request goes with none only where the list itself offers {}.

Left as they are, each stated where it lives:

• A 3.2 requirement naming a scheme by URI is valid and lowers as unresolved, with the same error, until openapi: a 3.2 security requirement naming a scheme by URI is reported as unresolved #1212. The kind's definition is written to stay true of it.
• A list of entries that are no object, such as security: [null], lowers to no option: such an entry names nothing to keep, so it collapses to nil beside the loader's error, and [] stays public. A security that is no list, such as security: {key: []}, reads as left out beside the loader's finding.
• A requirement whose only key is a << naming no mapping, such as - <<: 5, lowers to the empty option beside its error, as on main. It names nothing to keep, so it is openapi: a requirement whose only key is a << naming no mapping lowers to the empty option #1244's rather than this change's.
• A plain date at any other string field, and a $ref so written anywhere but a security scheme, still reads as left out with nothing reported, which is openapi: a plain date at a string field reads as empty, with no diagnostic #1280's. So does a security list under a local tag, security: !local [{k: []}], so that operation inherits. This change reads a requirement's scopes and a scheme's $ref from the node because what it keeps depends on them.
• A $ref written as null, at a security scheme as at any Reference Object but a schema, refuses the whole document, as on main, which is openapi: a $ref written as null makes the whole document undecodable #1284's.
• Whether a webhook or callback operation inherits the service's auth is ir: decide whether webhook and callback operations inherit the service's auth #626's; its own requirement is kept here like any other.
• test: pin the four states of a security requirement in the conformance corpus #690, a conformance case for the four states of a requirement, stays open: security-unresolved holds them beside names that reach no mechanism, not on their own.

Landing beside other PRs. #1219 took IRVersion 0.24.0, so this change moved to 0.25.0, after main's row and history entry. #1229 and #1302 also bump, and conflict with main at the version already: whichever lands after this keeps this change's row and entry and takes the next version. Every golden declares idSpaces.auth, so a golden an open PR adds merges clean and then fails, as the ones #1229, #1269, #1277, #1278, #1302 and #1307 add do: whichever lands after this reruns go test ./compilers/openapi/e2e -run 'TestGolden|TestConformance' -update, and the diff is that one line in each, as it was for the five goldens #1217 and #1219 added when main was merged here. #1227, #1229, #1269, #1278 and #1302 conflict with main already, and this change adds to that only in #1229, at the promotion call in lowerSecurityScheme, where the resolution keeps both sides. #1199, #1233, #1235, #1277, #1301, #1304, #1307, #1311 and #1313 merge clean.

Closes #633

Breaking

• IRVersion moves to 0.25.0, and a consumer built against 0.24.0 is refused the document. It has no reading for the kind, on operations it read as inheriting.
• Every OpenAPI document declares unresolved under idSpaces.auth, whether or not it mints there: 136 goldens change by that one line and nothing else.
• A requirement naming no mechanism draws openapi/unresolved-security-scheme where it drew openapi/unresolved-ref, so a consumer keyed on the old code at that site must move.
• {key: null} names key, where it read as {}, and the warning beside it says it lists no scopes. A document writing it for a name it does not declare exits 1 where it exited 0, with the requirement's error.
• A securitySchemes entry whose $ref is a plain date draws openapi/unresolved-ref, so a document writing one exits 1 where it exited 0.
• Document.Auth can hold a scheme no declaration states, and one for an entry that used to lower to nothing.

Test plan

Golden spec, cloudflare/api-schemas @319dc756 (OpenAPI 3.0.3), main @39afce9b against this branch @0043549e:

$ morphic compile --verify openapi.json -o ir.json 2> diags.txt; echo $?
1                                                   # both builds
$ awk '{print $1, $2}' diags.txt | sort | uniq -c
   9 error openapi/unresolved-ref                   # main
   9 error openapi/unresolved-security-scheme       # branch
  34 info openapi/composition-lowering              # this and the rest, both builds
1439 info openapi/degraded-construct
 194 info openapi/inferred-nullable
  10 info openapi/validation-only-keyword
 121 warning openapi/degraded-construct
   3 warning openapi/inapplicable-location-keyword
   5 warning openapi/reserved-header-name
$ jq -c '.services[].groups[].operations[]? | select(.id == "op/openapi/paths/~1pages~1assets~1upload/post") | .auth' ir.json
null                                                                                                  # main
[{"schemes":[{"scheme":"auth/unresolved/components/securitySchemes/pages_upload_token"}]}]            # branch

The nine operations that name a scheme the spec does not declare change, and nothing else does. Of 3,763 operations, 43 have auth absent and 2 are public on both builds, and these nine go from absent to naming APIToken, assets_jwt or pages_upload_token, the three schemes that join Document.Auth. jq -cS .types and jq -cS .unmodeled hash alike on both builds, so the Unmodeled census and the empty models are unmoved. A recursive diff of the two documents finds the nine auth fields, the three schemes, idSpaces.auth, irVersion, and the nine diagnostics' code and text, and nothing else.

Corpus, the 1,954 specs .claude/skills/morphic-verifying-changes/scripts/sweep.py reads from the reference corpus, of which 1,862 lower to a document, main @608a5a46 against this branch @7561bcce, each by compile and by compile --verify. Merging main since changed no line of this change's production code but the version constant, so the two patches differ only there and the sweep was not rerun:

	main	branch
exit 0 / exit 1 / exit 2, in each mode	1,482 / 472 / 0	1,482 / 472 / 0
specs whose exit differs, in either mode		0
these requirements' errors	286 openapi/unresolved-ref	286 openapi/unresolved-security-scheme
every other diagnostic, by severity and code, spec by spec		no difference
IR, beyond idSpaces.auth and irVersion		the auth of the 57 specs that name such a scheme, those schemes and the 286 diagnostics

The 286 options sit in 57 specs, 272 in document lists and 14 on operations. 50 list scopes, and none ANDs with a declared scheme. In 45 specs the document's list also holds {}, and lowered to [{}] on main. No spec in the corpus or the golden spec writes a name whose value reads as no list of strings, or a date among its scopes, so those fixes move nothing measured here; a grid of 326 edge specs, 167 JSON and 159 YAML, and the tests hold it.

• CI's gate passed on 0043549, which holds main @39afce9b, and go test ./... passes there locally.
• At 7561bcc, morphic-harness over testdata: outcome by outcome the same as main, but for f30, whose first error moves to the new code. Over the reference corpus, 2,079 files: 1,481 ok, 511 stopping at an error and 87 unrecognized on both builds, and 6 of the 511 move their first error to the new code. Over the golden spec it stops at the first error, as main does, so harness.Check reaches irverify but not the order oracle. orderInvariant is therefore called directly, by TestOrderInvariant_ReachesARequirementNamingNoMechanism on the conformance case, and once by hand over the 57 specs, the golden spec and the edge specs: every one passes.
• The oracle now compares Document.Auth, which it never read, and a flow's scopes as a set. A build in which the first requirement to reach a scheme writes into it goes red there. It reads no operation, so at 7561bcc 229 specs, the 167 JSON edge specs, the 57 specs, the golden spec and a two-entry $ref cycle (openapi: a reference on a failing chain is reported only if the walk reaches it first #767) among them, also went through a reversal of every mapping, comparing the registry, each operation's auth and the service's, and the diagnostics as a multiset. The registry and each auth show no difference; the diagnostics differ on two specs, each on main too: that cycle and the golden spec's keyword list in a message.
• security-unresolved, a new conformance case, holds every shape: AND, OR, {}, scopes, names with no scopes written, document, operation, webhook, callback, an entry naming no mechanism, one no requirement names and a broken $ref, beside an operation that inherits and one that is public. It witnesses per-op-auth and joins invalidCases and knownInvalid.
• A requirement in another document mints the source's scheme, in both declaration orders.
• 80 defects planted one at a time in a throwaway worktree at 7561bcc, one for each branch of the mechanism, each field the verifier reads, each new read and each list that names the new vocabulary, each drew a named failing test, and a no-op control survived. A further plant, in which the first requirement to reach a scheme writes into it, turns TestSecurityUnresolved_ANameTwoDocumentsUseIsOneSchemeOfTheSource and TestOrderInvariant_ReachesARequirementNamingNoMechanism red. One more is equivalent on this compiler: moving the deprecation promotion back into the return leaves the provenance written, though Go does not promise that order, and losing the write goes red in TestConformance/extension-promotion.
• At 0043549, 38 defects planted the same way across the requirement and scheme lowerings, the registry, nodeview.Strings, the rule table's null reading, the verifier, the namespace list, the run's order and the oracle each drew a named failing test, and a no-op control survived.