backend-skeleton 1.0.0 → 1.1.0

package/contracts/openapi.mjs

@@ -28,10 +28,32 @@ const HTTP_METHODS = Object.freeze(new Set(['get', 'put', 'post', 'delete', 'opt
 // D-openapi-request-schema in DECISIONS.md for the full measurement.
 const MAX_COMPONENT_SCHEMAS = 5000;
 const MAX_SCHEMA_DEPTH = 32; // every recursion level (structural AND $ref), not just $ref-chain depth
-const MAX_SCHEMA_NODES = 2000; // shared counter per top-level inlineSchema() call, enum entries count
-const MAX_PATTERN_LENGTH = 300; // real max observed: 77
+// D-openapi-schema-keyword-recursion (CATALOG A15/A16 follow-up): widened 2000 -> 250000. The
+// original 2000 had no real-data citation (an uncited default). After A15/A16's own masking-
+// cascade fixes unmasked 30 real request/response schema resolutions genuinely needing more than
+// 2000 nodes, a real per-schema binary-search probe (not guessed) found needs ranging 2289-61304
+// against polarsource/polar. Investigated the worst case directly before widening anything (this
+// project's own "measure, don't guess" discipline applies doubly hard to a DoS-defensive cap, not
+// just an operational-default one): `GET /v1/events/`'s 200 response is `anyOf` of two list
+// wrappers (regular + cursor-paginated), each independently embedding a full copy of `Event` ->
+// `oneOf[SystemEvent, UserEvent]` -> `SystemEvent.oneOf` (36 REAL distinct event subtypes, a real
+// webhook/audit event taxonomy) -- roughly 2x one full Event tree's cost, from a genuinely wide
+// real API surface, not pathological duplication or a runaway loop. 250000 keeps this project's
+// own established "~4x real observed max" headroom convention (MAX_COMPONENT_SCHEMAS 4.8x,
+// MAX_PATTERN_LENGTH 3.5x, MAX_PARAMETERS_PER_OPERATION 3.8x) rather than a tight fit to 61304.
+const MAX_SCHEMA_NODES = 250000; // shared counter per top-level inlineSchema() call, enum entries count
+// D-oracle-corpus-openapi-remeasurement (ROADMAP Phase 5c): widened 300 -> 1000. Real max
+// observed against Team-IZ-Backend: 77. Re-measured against a second, much larger real
+// production document (polarsource/polar, 1046 component schemas vs Team-IZ-Backend's 308): real
+// max 286 (SupportCaseAttachmentFileCreate) -- 95% of the OLD 300 cap, headroom effectively gone.
+// 1000 restores >3.5x headroom over the new, larger real max.
+const MAX_PATTERN_LENGTH = 1000; // real max observed: 77 (Team-IZ-Backend), 286 (polarsource/polar)
 const JSON_MEDIA_TYPE = 'application/json';
 const SCHEMA_REF_PREFIX = '#/components/schemas/';
+// D-openapi-cyclic-refs: the ONLY $ref form this module's own output ever emits (a genuinely
+// cyclic component, resolved into a top-level `$defs` map -- see inlineSchema()). Distinct from
+// SCHEMA_REF_PREFIX, which is what this module RESOLVES on the way IN from a source document.
+const DEFS_REF_PREFIX = '#/$defs/';
 
 // A3: response/error JSON Schema projection. Reuses every inlineSchema() defense above
 // unchanged (keyword/format whitelist, MAX_SCHEMA_DEPTH/NODES/PATTERN_LENGTH) -- measured by
@@ -113,7 +135,22 @@ export const PATH_PREFIX_RE = /^(?:\/[A-Za-z0-9._~%-]+)+$/;
 // requirement kills `__proto__` on the first character alone, same as OPERATION_ID_RE; measured
 // against all 308 real Team-IZ-Backend component-schema names with zero rejections.
 export const COMPONENT_SCHEMA_NAME_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,199}$/;
-export const SCHEMA_PROPERTY_NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
+// D-oracle-corpus-openapi-remeasurement (ROADMAP Phase 5c): widened from
+// /^[A-Za-z][A-Za-z0-9_]{0,127}$/ after re-measuring against polarsource/polar's real production
+// document found 4 real property names the ORIGINAL pattern rejected: `_cost`, `_llm`
+// (single-leading-underscore, a real, common convention for "internal/computed field" this
+// corpus's own Team-IZ-Backend measurement never happened to exercise), `cf-turnstile-response`
+// (a real kebab-case name from a third-party integration), and `$ref` (a real domain property
+// LITERALLY named $ref, e.g. BenefitCustom.properties.$ref -- correctly still rejected below, not
+// a false positive to fix: $ starts neither the required leading letter nor the new optional
+// leading underscore). The widened pattern (`_?[A-Za-z][A-Za-z0-9_-]{0,127}`) allows AT MOST ONE
+// leading underscore followed immediately by a letter -- this still kills `__proto__` (two
+// underscores; after consuming one, the required next character is the SECOND underscore, not a
+// letter, so it fails either way the optional group backtracks) and every other real
+// Object.prototype dunder name (`__defineGetter__`, etc.), confirmed by a real regression test,
+// not reasoned about only in this comment. Hyphens added (matching COMPONENT_SCHEMA_NAME_RE's own
+// already-permissive character class) for the same real `cf-turnstile-response` case.
+export const SCHEMA_PROPERTY_NAME_RE = /^_?[A-Za-z][A-Za-z0-9_-]{0,127}$/;
 
 // A8: an OpenAPI response-object status key becomes an object key downstream, in both this
 // contract's sourceResponses and the exported document's responses -- same prototype-pollution
@@ -155,7 +192,13 @@ export const PER_STATUS_NO_DESCRIPTION_STANDIN = 'The source document documents
 // dropping an assertion (e.g. an unrecognized `pattern`-like keyword) would emit a schema WEAKER
 // than the real one, which is worse than emitting no schema at all -- see
 // D-openapi-request-schema in DECISIONS.md.
-const RECURSED_KEYWORDS = Object.freeze(new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf']));
+// A15: `propertyNames` added -- its value IS a schema (unlike every other RECURSED_KEYWORDS
+// sibling being a container OF schemas), so findUnsupportedAnnotations() must descend into it the
+// same way it already descends into `items`, or a dropped/unsupported keyword nested inside a
+// propertyNames sub-schema would go completely unreported.
+// A16: `prefixItems` added -- an ARRAY of schemas (same shape as oneOf/anyOf/allOf), already
+// covered by this function's existing `Array.isArray(value)` branch with zero further code change.
+const RECURSED_KEYWORDS = Object.freeze(new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'propertyNames', 'prefixItems']));
 // A7: `default` added -- annotation-only per 2020-12 (Ajv runs with useDefaults off here, so it's
 // inert for validation either way), but a real, human-authored fact from the source document worth
 // carrying through regardless. Measured across every real request-body and response schema in the
@@ -172,13 +215,49 @@ const COPIED_KEYWORDS = Object.freeze(new Set([
 // A11 (D-openapi-field-docs): `description`/`example` measured real and heavily used at the FIELD
 // level (3,982 / 2,077 occurrences across the oracle's request/response/parameter schemas,
 // 520,527 / 32,708 real bytes) -- moved out of DROPPED_KEYWORDS into their own conditionally-
-// copied set. `title`/`examples`(plural)/`externalDocs`/`xml`/`deprecated` stay unconditionally
-// dropped: 0 real occurrences for every one of them (measured, not assumed), so building any
-// copy path for them would violate this project's own "don't build for zero real cases"
-// discipline -- named here, not built, a permanent gap like A8's `non-json-response-schemas`/
-// `response-headers`.
-const DOCUMENTATION_KEYWORDS = Object.freeze(new Set(['description', 'example']));
-const DROPPED_KEYWORDS = Object.freeze(new Set(['title', 'examples', 'externalDocs', 'xml', 'deprecated']));
+// copied set.
+// A14 (D-openapi-field-metadata-passthrough): `title`/`examples`(plural)/`deprecated` join them.
+// A11's own "0 real occurrences, permanently unbuilt" verdict for all five held against the
+// original Team-IZ-Backend oracle (308 component schemas) but NOT against a real, much larger
+// second corpus (polarsource/polar, 1046 component schemas, ROADMAP Phase 5c's own
+// D-oracle-corpus-openapi-remeasurement): title 6,226 real occurrences (max 54 chars), examples
+// 602 real arrays (max 4 entries, max element 59 chars serialized), deprecated 31 real boolean
+// occurrences. `externalDocs`/`xml` remain confirmed 0 real occurrences even at this larger
+// scale -- those two alone still satisfy the "don't build for zero real cases" discipline A8's
+// `non-json-response-schemas`/`response-headers` also rest on.
+// A15 (D-openapi-schema-keyword-recursion): `readOnly` joins the documentation set -- 2020-12
+// section 9.4 marks readOnly/writeOnly as annotation-only (no effect on validation, same as
+// deprecated), and it has the identical boolean shape. Measured real (polarsource/polar): 40
+// occurrences, 0 malformed (non-boolean).
+const DOCUMENTATION_KEYWORDS = Object.freeze(new Set(['description', 'example', 'title', 'examples', 'deprecated', 'readOnly']));
+// A15: `x-speakeasy-enums`/`enumNames` join the dropped set. Both are vendor/non-standard codegen
+// metadata (Speakeasy's own enum-codegen hint; enumNames is a react-jsonschema-form-style
+// human-label convention) with zero JSON Schema validation weight -- the same risk tier as
+// externalDocs/xml. Real counts (polarsource/polar, measured AFTER the uuid4 masking fix below):
+// x-speakeasy-enums 59, enumNames 1. Both already reachable via the existing RECURSED_KEYWORDS
+// walk (they appear as direct schema children), so findUnsupportedAnnotations() needs no other
+// change to start reporting them.
+//
+// D-openapi-schema-keyword-recursion masking note: Phase 5c's own
+// D-oracle-corpus-openapi-remeasurement recorded "26 remaining failures (discriminator x2,
+// x-speakeasy-enums x4, propertyNames x20)" against this exact corpus. Re-measuring after the
+// uuid4 fix landed (this
+// file's SAFE_FORMATS/format handling below) revealed those Phase 5c counts were themselves an
+// undercount: walkSchemaNode() throws on the FIRST unsupported key it hits in a node and never
+// reaches the rest, so a node with BOTH format:uuid4 AND, say, a discriminator had its
+// discriminator failure permanently masked by the uuid4 failure firing first. Fixing uuid4 didn't
+// just fix uuid4 -- it unmasked failures that were always there. Real post-fix counts: x-speakeasy-
+// enums 59, readOnly 25 (not even named in Phase 5c -- fully masked), propertyNames 24,
+// discriminator 9, enumNames 1 (also unnamed in Phase 5c). `cycle-detected` (4, unrelated to
+// masking) stays out of scope -- a real circular schema reference, not a missing keyword; this
+// flatten-only architecture has no $ref-preserving output mode to represent one.
+const DROPPED_KEYWORDS = Object.freeze(new Set(['externalDocs', 'xml', 'x-speakeasy-enums', 'enumNames']));
+// A14: real max observed (polarsource/polar) -- title 54 chars, examples array 4 entries. Both
+// generously round, matching MAX_EXAMPLE_LENGTH's own "generously round, not a tight multiple"
+// precedent (a legitimately useful title/example set could reasonably run longer than any single
+// real value happened to here).
+const MAX_TITLE_LENGTH = 500;
+const MAX_EXAMPLES_ARRAY_LENGTH = 50;
 
 // D-unsupported-annotation-warning: 0 real occurrences on the ONE oracle this whole module's
 // caps/keyword sets were measured against does not mean 0 occurrences everywhere -- a genuinely
@@ -187,8 +266,9 @@ const DROPPED_KEYWORDS = Object.freeze(new Set(['title', 'examples', 'externalDo
 // for the broader "self-identified weaknesses" context this closes one instance of).
 //
 // Deliberately walks ONLY genuine Schema Object structure (via RECURSED_KEYWORDS, the exact same
-// `properties`/`items`/`additionalProperties`/`oneOf`/`anyOf`/`allOf` set inlineSchema() itself
-// recurses through) -- NOT a blanket "every key anywhere in the document" scan. That distinction
+// `properties`/`items`/`additionalProperties`/`oneOf`/`anyOf`/`allOf`/`propertyNames`/`prefixItems`
+// set inlineSchema() itself recurses through) -- NOT a blanket "every key anywhere in the document"
+// scan. That distinction
 // is load-bearing, not cosmetic: several of DROPPED_KEYWORDS' names collide with REAL, unrelated
 // OpenAPI concepts that live outside a Schema Object entirely -- an Operation Object's own
 // `deprecated` (marks a whole ENDPOINT deprecated) and a Parameter Object's own `deprecated`, both
@@ -273,7 +353,19 @@ export function findUnsupportedAnnotations(doc) {
 // Real Team-IZ-Backend format-value histogram (request-body-reachable schemas only): uuid(20),
 // int32(10), email(7), date(10), date-time(3), int64(2). `uuid` is handled separately (rewritten
 // to BARE_UUID_PATTERN, see inlineSchema) -- not in this set, since it never survives as `format`.
-const SAFE_FORMATS = Object.freeze(new Set(['int32', 'int64', 'email', 'date', 'date-time', 'double', 'float', 'binary', 'uri']));
+// D-oracle-corpus-openapi-remeasurement (ROADMAP Phase 5c): re-measured against
+// polarsource/polar's real production document (full histogram, all schema roots): uuid4(1063,
+// see inlineSchema's own uuid4 handling -- also not in this set for the same reason bare uuid
+// isn't), date-time(676), uri(41), email(28), uuid(27), date(7), ipvanyaddress(7), duration(2),
+// color(1). Every value already in SAFE_FORMATS before this measurement (date-time/uri/email/date)
+// is confirmed still real and safe at a much larger scale.
+// A15: `ipvanyaddress`/`duration`/`color` added despite being the rarest formats measured (7/2/1
+// occurrences) -- Phase 5c judged that too rare to justify adding on its own, but SAFE_FORMATS is
+// a pure passthrough whitelist (this module never validates a format VALUE, only decides whether
+// the format NAME is safe to keep), so the marginal cost of adding a real, if rare, format name is
+// low and the alternative (3 real fields permanently fail-closed) is a real, visible cost with no
+// offsetting benefit once a real occurrence exists at all.
+const SAFE_FORMATS = Object.freeze(new Set(['int32', 'int64', 'email', 'date', 'date-time', 'double', 'float', 'binary', 'uri', 'ipvanyaddress', 'duration', 'color']));
 
 // Thrown internally by inlineSchema()'s recursive walk and caught exactly once at the exported
 // boundary -- with 12+ distinct failure points, threading {ok:false} through every return would
@@ -573,14 +665,27 @@ export function inferPathPrefix(anchorDeltas) {
 }
 
 // A2: dereferences `node` (a schema fragment from a requestBody's application/json content) into
-// a single self-contained JSON Schema tree with NO `$ref` anywhere in the output. Pure, and NEVER
-// throws across this exported boundary (InlineFailure is caught here, anything else re-thrown --
-// it would be a real programming bug, not an untrusted-input failure, and must not be swallowed).
-// Full inlining (never registering a component with ajv by $id) for two independent reasons: ajv
-// would otherwise need every one of a document's component schemas registered just to validate
-// ONE operation's body, and bin/bskel.mjs's cmdContractToolSchema promises its `input_schema`
-// output is a JSON Schema subset "directly usable as-is" for Anthropic tool-use -- no $ref/$defs
-// is exactly what that promise requires; this function is what upholds it.
+// a single self-contained JSON Schema tree. Pure, and NEVER throws across this exported boundary
+// (InlineFailure is caught here, anything else re-thrown -- it would be a real programming bug,
+// not an untrusted-input failure, and must not be swallowed). Full inlining (never registering a
+// component with ajv by $id) for two independent reasons: ajv would otherwise need every one of a
+// document's component schemas registered just to validate ONE operation's body, and
+// bin/bskel.mjs's cmdContractToolSchema promises its `input_schema` output is a JSON Schema
+// subset "directly usable as-is" for Anthropic tool-use, which forbids RECURSIVE schemas
+// specifically (internal $ref/$defs to a non-recursive shared definition is fine, per Anthropic's
+// own documented JSON Schema limitations) -- this function is what upholds both promises.
+//
+// D-openapi-cyclic-refs: the ONE exception to "no $ref anywhere in the output" -- a genuinely
+// self-referential component (directly or via a mutual cycle, e.g. polarsource/polar's real
+// `Filter` and `Meter`<->`Subscription`<->`SubscriptionMeter`) can never terminate under full
+// inlining; walkSchemaNode() now emits `$ref: "#/$defs/<Name>"` at exactly the cyclic edge
+// (state.defsNeeded, populated during the walk) instead of failing closed, and this function
+// drains that set ONCE the top-level walk completes into a real, top-level `$defs` map attached
+// to the returned schema -- omitted entirely (this function's return shape is unchanged) for the
+// overwhelmingly common acyclic case. `cmdContractToolSchema` is the one real consumer this
+// genuinely cannot satisfy (Anthropic's own "recursive schemas not supported" limitation) --
+// it detects `$defs` on the projected schema and refuses explicitly rather than emitting
+// something that would only fail later at the real API call. See DECISIONS.md.
 export function inlineSchema(node, componentSchemas, opts = {}) {
 	const limits = {
 		maxDepth: opts.maxDepth ?? MAX_SCHEMA_DEPTH,
@@ -590,9 +695,40 @@ export function inlineSchema(node, componentSchemas, opts = {}) {
 		// byte-for-byte when the caller doesn't pass it) -- see D-openapi-field-docs.
 		includeFieldDocs: opts.includeFieldDocs ?? false,
 	};
-	const state = { nodes: 0 };
+	const state = { nodes: 0, defsNeeded: new Set() };
 	try {
 		const schema = walkSchemaNode(node, componentSchemas, 0, new Set(), state, limits);
+		if (state.defsNeeded.size > 0) {
+			const defs = {};
+			const resolved = new Set();
+			// Fixed-point drain: resolving one cyclic component's own body can discover ANOTHER
+			// cyclic component reachable from it (a mutual cycle, e.g. Meter -> Subscription ->
+			// SubscriptionMeter -> Meter) that state.defsNeeded didn't have yet -- one pass over a
+			// snapshot would miss it.
+			let pending = [...state.defsNeeded].filter((name) => !resolved.has(name));
+			while (pending.length > 0) {
+				for (const name of pending) {
+					resolved.add(name);
+					const target = componentSchemas.get(name); // presence already confirmed during the main walk
+					const def = walkSchemaNode(target, componentSchemas, 0, new Set([name]), state, limits);
+					// A component whose ENTIRE definition is nothing but a $ref chain back to
+					// itself (real content -- type/properties/etc -- never appears ANYWHERE in
+					// the cycle) resolves to a bare `{$ref: ...}` with no other real keys.
+					// Confirmed live: Ajv2020 itself stack-overflows trying to COMPILE such a
+					// schema (an infinite pure-indirection loop with no base case for its own
+					// compiler to terminate on) -- this is not a shape any real OpenAPI document
+					// produces (every real cyclic component measured has genuine structural
+					// content at every level, e.g. polarsource/polar's Filter/Meter/Subscription),
+					// so fail closed on this degenerate case rather than emit something that
+					// would break the very validator this whole mechanism exists to feed.
+					const realKeys = Object.keys(def).filter((k) => k !== '$ref' && k !== 'default');
+					if (realKeys.length === 0) fail('cycle-without-base-schema');
+					defs[name] = def;
+				}
+				pending = [...state.defsNeeded].filter((name) => !resolved.has(name));
+			}
+			schema.$defs = defs;
+		}
 		return { ok: true, schema, nodes: state.nodes };
 	} catch (err) {
 		if (err instanceof InlineFailure) return { ok: false, reason: err.reason };
@@ -629,7 +765,22 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 		// JSON-Pointer escapes (~0/~1) or percent-encoding in the name are never produced by
 		// springdoc for a plain component name -- reject rather than decode-and-guess.
 		if (name.includes('~') || name.includes('%') || !COMPONENT_SCHEMA_NAME_RE.test(name)) fail('unsupported-ref');
-		if (visiting.has(name)) fail('cycle-detected');
+		if (visiting.has(name)) {
+			// D-openapi-cyclic-refs: a genuine ancestor-chain cycle (name is currently being
+			// resolved higher up this same call stack) -- this is a deterministic property of
+			// `name`'s own structure (does it reach itself via ANY of its own oneOf/anyOf/allOf/
+			// properties/items branches, all of which are walked unconditionally, never
+			// simulating "one instance"), not of which reference site discovered it first: every
+			// occurrence of a self-referential component hits this same branch, every occurrence
+			// of a non-cyclic one fully inlines exactly as before -- no two-pass discovery needed.
+			// Recorded in state.defsNeeded and drained once, after the top-level walk completes
+			// (see inlineSchema()), into a real `$defs` map; this $ref stub is the only place in
+			// the whole module that ever emits an unresolved $ref in the OUTPUT.
+			state.defsNeeded.add(name);
+			const stub = { '$ref': `${DEFS_REF_PREFIX}${name}` };
+			if (Object.hasOwn(node, 'default')) stub.default = node.default;
+			return stub;
+		}
 		const target = componentSchemas.get(name);
 		if (!target) fail('component-not-found');
 		visiting.add(name);
@@ -657,7 +808,18 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 	// uuid+pattern conflict check below (inside the loop) sees `out.pattern` already set.
 	if (Object.hasOwn(node, 'format')) {
 		const format = node.format;
-		if (format === 'uuid') {
+		// D-oracle-corpus-openapi-remeasurement (ROADMAP Phase 5c): `uuid4` added alongside `uuid`
+		// -- real, measured data, not a speculative generalization. polarsource/polar's real,
+		// production OpenAPI document uses `format: "uuid4"` 1063 times (Pydantic's UUID4 type
+		// emits this non-standard-but-common format string) and NONE use bare `uuid` for the same
+		// field shape -- before this fix, every one of those 1063 fields failed inlineSchema()
+		// closed with `unsupported-format:uuid4` (161 of 568 real request/response schema
+		// resolutions attempted against this document failed, 86% of all failures, for this one
+		// reason). The RFC 4122 wire format is identical regardless of which UUID version
+		// generated the value, so the same BARE_UUID_PATTERN rewrite applies. Deliberately NOT
+		// generalized to `uuid1`/`uuid3`/`uuid5` -- no real corpus has measured those yet; add them
+		// if and when one does, per this project's own data-first-numerics discipline.
+		if (format === 'uuid' || format === 'uuid4') {
 			out.pattern = BARE_UUID_PATTERN;
 		} else if (typeof format === 'string' && SAFE_FORMATS.has(format)) {
 			out.format = format;
@@ -692,6 +854,33 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 				if (serialized !== undefined && serialized !== null && serialized.length <= MAX_EXAMPLE_LENGTH) {
 					out.example = node.example;
 				}
+			} else if (key === 'title') {
+				if (typeof node.title === 'string' && node.title.length <= MAX_TITLE_LENGTH) {
+					out.title = node.title;
+				}
+			} else if (key === 'examples') {
+				// A14: matches description/example's own "drop the WHOLE field, never partial" doctrine
+				// -- an examples array with one oversized entry is dropped entirely, not filtered down
+				// to the entries that happened to pass, since a caller reading a shortened array would
+				// have no way to tell "this is everything" from "this is what survived a silent cut".
+				if (Array.isArray(node.examples) && node.examples.length <= MAX_EXAMPLES_ARRAY_LENGTH) {
+					const allFit = node.examples.every((ex) => {
+						let serialized;
+						try { serialized = JSON.stringify(ex); } catch { serialized = null; }
+						return serialized !== undefined && serialized !== null && serialized.length <= MAX_EXAMPLE_LENGTH;
+					});
+					if (allFit) out.examples = node.examples;
+				}
+			} else if (key === 'deprecated') {
+				if (typeof node.deprecated === 'boolean') {
+					out.deprecated = node.deprecated;
+				}
+			} else if (key === 'readOnly') {
+				// A15: identical shape/validation to deprecated -- 2020-12 section 9.4 makes readOnly
+				// annotation-only, same as deprecated, so it gets the same boolean-typed copy-or-drop.
+				if (typeof node.readOnly === 'boolean') {
+					out.readOnly = node.readOnly;
+				}
 			}
 			continue;
 		}
@@ -721,6 +910,31 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 			continue;
 		}
 
+		if (key === 'discriminator') {
+			// A15 (D-openapi-schema-keyword-recursion): discriminator is annotation-only per the
+			// OpenAPI spec -- actual polymorphism validation is done by oneOf/anyOf itself, which
+			// this module already walks; discriminator is only a dispatch HINT for consumers, the
+			// same validation-inert-but-worth-carrying-through tier as `default` (A7). Real shape
+			// measured (polarsource/polar, 36/36 occurrences): always `{propertyName: string,
+			// mapping?: {[string]: string}}`, mapping present in all 36. Unlike `pattern`/`required`
+			// (real validation constraints, fail the WHOLE schema closed on a malformed value), a
+			// malformed discriminator can't silently weaken what the schema validates -- so an
+			// off-shape value drops just this field, matching DOCUMENTATION_KEYWORDS' own doctrine,
+			// not the fail-closed one. Kept OUTSIDE DOCUMENTATION_KEYWORDS/--descriptions on purpose:
+			// this is small structural dispatch metadata, not prose that could bloat contract size,
+			// so there's no reason to gate it behind the same flag that exists specifically to bound
+			// free-text documentation growth.
+			const disc = node.discriminator;
+			const propertyNameOk = disc && typeof disc === 'object' && !Array.isArray(disc) && typeof disc.propertyName === 'string';
+			const mappingOk = !disc || !Object.hasOwn(disc, 'mapping')
+				|| (disc.mapping && typeof disc.mapping === 'object' && !Array.isArray(disc.mapping)
+					&& Object.values(disc.mapping).every((v) => typeof v === 'string'));
+			if (propertyNameOk && mappingOk) {
+				out.discriminator = Object.hasOwn(disc, 'mapping') ? { propertyName: disc.propertyName, mapping: { ...disc.mapping } } : { propertyName: disc.propertyName };
+			}
+			continue;
+		}
+
 		if (COPIED_KEYWORDS.has(key)) {
 			if (key === 'enum' && Array.isArray(node.enum)) {
 				state.nodes += node.enum.length; // enum entries aren't separate schema nodes, but still cost budget
@@ -758,7 +972,31 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 			continue;
 		}
 
-		if (key === 'oneOf' || key === 'anyOf' || key === 'allOf') {
+		if (key === 'propertyNames') {
+			// A15: propertyNames is a REAL validation constraint (restricts what an object's own
+			// property NAMES may be) -- unlike discriminator/readOnly, dropping it would silently
+			// emit a schema weaker than the real one, the same correctness concern
+			// SCHEMA_PROPERTY_NAME_RE already exists to prevent elsewhere. Its value IS a schema, so
+			// it recurses exactly like `items`/`additionalProperties`. Real shapes measured
+			// (polarsource/polar, 66 occurrences, 3 unique): a plain length-constrained schema
+			// (`{maxLength, minLength}`), an already-supported format (`{format: "uuid4"}`), and a
+			// real `$ref`. All 3 are ordinary walkSchemaNode() territory already.
+			out.propertyNames = walkSchemaNode(node.propertyNames, componentSchemas, depth + 1, visiting, state, limits);
+			continue;
+		}
+
+		if (key === 'oneOf' || key === 'anyOf' || key === 'allOf' || key === 'prefixItems') {
+			// A16 (D-openapi-schema-keyword-recursion follow-up): `prefixItems` (JSON Schema 2020-12
+			// tuple validation) joins this array-of-schemas branch -- unlike `items`/`propertyNames`
+			// (a single schema), `prefixItems`' value is an ARRAY of schemas, one per tuple position,
+			// the same shape oneOf/anyOf/allOf already have. Real shape measured (polarsource/polar,
+			// all 9 occurrences identical): a strict 2-element tuple (`[{type:string},
+			// {$ref:.../TaxIDFormat}]`) alongside `type:array`/`maxItems:2`/`minItems:2`/`examples` --
+			// all already-handled COPIED_KEYWORDS/DOCUMENTATION_KEYWORDS siblings, nothing new needed
+			// for them. `items` never co-occurs with `prefixItems` in this corpus (0/9); if it ever
+			// did, both keys are still independently walked and copied here exactly as authored --
+			// this module doesn't itself enforce the "items applies beyond the prefix" interaction,
+			// it only needs to preserve both fields faithfully for whatever validates the output.
 			const arr = node[key];
 			if (!Array.isArray(arr) || arr.length === 0) fail(`unsupported-keyword:${key}`);
 			out[key] = arr.map((el) => walkSchemaNode(el, componentSchemas, depth + 1, visiting, state, limits));
@@ -896,7 +1134,34 @@ function projectResponseSchemas(responses, statusRe, componentSchemas, { include
 	// verified directly against the installed Ajv2020: a payload matching two overlapping
 	// branches is rejected by oneOf and accepted by anyOf. anyOf states precisely what's true
 	// given the envelope carries no status code: "matches at least one documented shape."
-	return { outcome: 'resolved', schema: { anyOf: distinct }, sources: distinct.length };
+	//
+	// D-openapi-cyclic-refs: any distinct[i] may carry its OWN top-level $defs (a cyclic
+	// component reachable from that branch). $ref: "#/$defs/X" resolves against the COMPILED
+	// DOCUMENT's own root, not wherever the branch happens to sit once nested inside this new
+	// `anyOf` wrapper (confirmed live against the installed Ajv2020: leaving $defs on the nested
+	// branch throws "can't resolve reference" once wrapped) -- so every branch's $defs must be
+	// hoisted onto the wrapper's own top-level $defs, stripped from the branch itself. A name
+	// collision with DIFFERENT content across branches is not expected in real data (never
+	// observed) and is genuinely ambiguous which shape a shared name should mean -- fails this
+	// resolution closed rather than silently picking one, the same doctrine A15's discriminator/
+	// propertyNames already apply to a malformed/ambiguous real-world shape.
+	const mergedDefs = {};
+	let defsCollision = false;
+	const branches = distinct.map((schema) => {
+		if (!Object.hasOwn(schema, '$defs')) return schema;
+		const { $defs, ...rest } = schema;
+		for (const [name, body] of Object.entries($defs)) {
+			if (Object.hasOwn(mergedDefs, name) && canonicalJson(mergedDefs[name]) !== canonicalJson(body)) {
+				defsCollision = true;
+			}
+			mergedDefs[name] = body;
+		}
+		return rest;
+	});
+	if (defsCollision) return { outcome: 'unresolved', reason: 'defs-name-collision' };
+	const schema = { anyOf: branches };
+	if (Object.keys(mergedDefs).length > 0) schema.$defs = mergedDefs;
+	return { outcome: 'resolved', schema, sources: distinct.length };
 }
 
 // A3: applies both response (2xx) and error (4xx/5xx) projection to a `matched`/`adopted` result,

package/contracts/validate.mjs

@@ -63,25 +63,44 @@ export function validateEnvelopeStructure(envelope) {
 // shape uniform across all three directions ("a named-parts object, additionalProperties:false")
 // -- see D-openapi-response-schema. An unrecognized `direction` also returns null (unconstrained),
 // matching the envelope schema's own enum being the actual gate on valid direction values.
+// D-openapi-cyclic-refs: every direction below NESTS the projected schema one level deeper
+// (`properties.body`) before the caller compiles the WHOLE wrapper with Ajv. `$ref: "#/$defs/X"`
+// is a JSON Pointer resolved against the COMPILED DOCUMENT's own root, not wherever the $ref
+// textually sits -- confirmed live against the installed Ajv2020: leaving a schema's own `$defs`
+// nested at `properties.body.$defs` throws "can't resolve reference #/$defs/X from id #" once
+// wrapped this way, even though the SAME schema compiles and validates correctly on its own
+// (contracts/export.mjs's placement of a schema at a document LEAF isn't affected by this -- only
+// this function's own extra wrapping is). Every call site below hoists a nested `$defs` onto the
+// wrapper's own top level and strips the now-redundant nested copy.
+function hoistDefs(wrapper, schema) {
+	if (!schema || !Object.hasOwn(schema, '$defs')) return schema;
+	const { $defs, ...rest } = schema;
+	wrapper.$defs = $defs;
+	return rest;
+}
+
 export function operationPayloadSchema(opContract, direction = 'request') {
 	if (direction === 'request') {
 		const properties = { pathParams: opContract.pathParams };
 		const required = ['pathParams'];
 		const bodySchema = opContract.requestBodySchema ?? { type: 'object' };
+		const result = { type: 'object', additionalProperties: false, properties, required };
 		if (opContract.body === true) {
-			properties.body = bodySchema;
+			properties.body = hoistDefs(result, bodySchema);
 			required.push('body');
 		} else if (opContract.body === 'unknown') {
-			properties.body = bodySchema;
+			properties.body = hoistDefs(result, bodySchema);
 		}
 		// body === false: deliberately absent from `properties` -- with additionalProperties:false
 		// below, a payload that includes a body for a known-bodyless operation is rejected outright.
-		return { type: 'object', additionalProperties: false, properties, required };
+		return result;
 	}
 	if (direction === 'response' || direction === 'error') {
 		const schema = direction === 'response' ? opContract.responseSchema : opContract.errorSchema;
 		if (!schema) return null;
-		return { type: 'object', additionalProperties: false, properties: { body: schema }, required: ['body'] };
+		const result = { type: 'object', additionalProperties: false, properties: {}, required: ['body'] };
+		result.properties.body = hoistDefs(result, schema);
+		return result;
 	}
 	return null;
 }