docs(downgrader): note that a mutualTLS-only security list is removed in 3.1 to 3.0

packages/downgrader/README.md

@@ -170,7 +170,7 @@ Schema Objects inside the document convert as in [Schema](#schema-downgradeschem
 - `$ref`s into removed parts are recognized by their `#/webhooks/` or `#/components/pathItems/` prefix as written, not percent-encoded.
 - Links and discriminator `mapping` values that point into a removed part, and Links that name a webhook operation by `operationId`, are left as written.
 - Encoding Objects pass through, although 3.0 serializes `multipart` parts by other defaults: it ignores `style`, `explode`, and `allowReserved` there, and gives an untyped part no `application/octet-stream` default.
-- An operation whose only `security` alternatives use mutual TLS loses its `security`, so it falls back to the document's.
+- A `security` list whose alternatives all use only mutual TLS is removed. On an operation it then falls back to the document's `security`, and on the document it leaves none, so no security is required.
 
 ### Schema (`downgradeSchemaV31ToV30`)
 

packages/downgrader/src/v3.1-to-v3.0.ts

@@ -741,9 +741,11 @@ function schemeType(scheme: unknown, ctx: Context): unknown {
 }
 
 // 3.0 has no mutual TLS, so security requirements lose the schemes that use
-// it. A requirement left empty is removed, and so is a list left empty,
-// because an empty one would mean that no security is needed. 3.0 also
-// allows scopes only for OAuth2 and OpenID Connect.
+// it. A requirement left empty is removed, because an empty one would mean
+// that no security is needed. A list left empty is removed too, so an
+// operation falls back to the document's `security`, though the document's
+// own list then needs no security either way. 3.0 also allows scopes only for
+// OAuth2 and OpenID Connect.
 function convertSecurity(value: unknown, ctx: Context): unknown {
   if (!Array.isArray(value)) {
     return clone(value)