backend-skeleton 1.0.0-beta.2 → 1.0.0-beta.4

package/contracts/openapi.mjs

@@ -53,6 +53,20 @@ const MAX_SECURITY_SCHEMES = 64;
 // 9). MAX_REQUEST_MEDIA_TYPES is new: real max observed on one operation's requestBody.content is
 // 1 (always either application/json alone or multipart/form-data alone in the oracle).
 const MAX_REQUEST_MEDIA_TYPES = 16;
+// A10: operation-level `description`, same "generous multiple of the real observed max" style as
+// every cap above -- real max observed on the Team-IZ-Backend oracle (148 operations, 146 carry a
+// non-empty description) is 9,083 (`.length`, UTF-16 code units, same measure MAX_PATTERN_LENGTH
+// already uses -- NOT a UTF-8 byte count, which runs higher for this oracle's real multi-byte
+// Korean text: 13,758 bytes for the same longest description).
+const MAX_DESCRIPTION_LENGTH = 40000;
+// A11: a FIELD-level `example` value, inside a schema this whole file resolves -- unlike
+// MAX_DESCRIPTION_LENGTH's single operation-level string, `example` is an arbitrary JSON value
+// (string/number/array/object all occur for real, see D-openapi-field-docs), so the cap applies to
+// its serialized (`JSON.stringify(value).length`) size, not `.length` directly. Real max observed
+// on the oracle: 70. A generously round bound, not a tight multiple, since a legitimately useful
+// example (e.g. a full sample response object) could reasonably run longer than any single real
+// value happened to here.
+const MAX_EXAMPLE_LENGTH = 2000;
 // A6 (D-openapi-export): widened from `/^2[0-9]{2}$/` and `/^[45][0-9]{2}$/` to also accept
 // OpenAPI's own RANGE keys. These are ordinary in real hand-written documents and legal per the
 // official 3.1 meta-schema, whose `responses` object accepts exactly `^[1-5](?:[0-9]{2}|XX)$` plus
@@ -130,12 +144,16 @@ export const PER_STATUS_NO_DESCRIPTION_STANDIN = 'The source document documents
 
 // inlineSchema()'s keyword policy: RECURSED keywords are walked into; ASSERTION keywords are
 // copied verbatim (their values are scalars/arrays of scalars, not schema nodes -- nothing to
-// recurse); DROPPED keywords carry no validation meaning and are silently discarded (their
-// absence changes nothing about what a schema accepts); anything else fails that schema closed.
-// The FORMAT set is checked separately (see inlineSchema's format handling) since `uuid` gets
-// rewritten rather than either copied or dropped. A missing-and-therefore-fail-closed keyword is
-// deliberate: silently 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
+// recurse); DOCUMENTATION keywords (A11) are copied verbatim ONLY when opted in
+// (`includeFieldDocs`), dropped otherwise -- unlike an ASSERTION keyword, dropping one never
+// changes what a schema VALIDATES, only how well-documented it is, so there is no fail-closed
+// concern either way; DROPPED keywords carry no validation meaning AND have zero real occurrences
+// on the oracle (measured, not assumed -- see D-openapi-field-docs), so they are unconditionally
+// discarded regardless of any flag; anything else fails that schema closed. The FORMAT set is
+// checked separately (see inlineSchema's format handling) since `uuid` gets rewritten rather than
+// either copied or dropped. A missing-and-therefore-fail-closed keyword is deliberate: silently
+// 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']));
 // A7: `default` added -- annotation-only per 2020-12 (Ajv runs with useDefaults off here, so it's
@@ -151,7 +169,107 @@ const COPIED_KEYWORDS = Object.freeze(new Set([
 	'minItems', 'maxItems', 'uniqueItems',
 	'minProperties', 'maxProperties',
 ]));
-const DROPPED_KEYWORDS = Object.freeze(new Set(['description', 'title', 'example', 'examples', 'externalDocs', 'xml', 'deprecated']));
+// 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']));
+
+// 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
+// different real-world document could use any of DROPPED_KEYWORDS, and silently dropping them
+// with no signal at all is a real honesty gap (see D-contract-history/D-gate-export's own backlog
+// 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
+// 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
+// legitimate 3.1 fields with nothing to do with inlineSchema()'s keyword handling. A blanket walk
+// would misreport those as "an unsupported schema keyword found," which is false. This function
+// only descends from confirmed schema roots (a `$ref`-or-inline `schema` under `content.<media>`
+// or `parameters[].schema`, or a named entry in `components.schemas`), the same roots
+// inlineSchema() itself is ever called on.
+//
+// NOT routed through walkSchemaNode()'s fail-closed machinery -- it must never throw on a shape
+// inlineSchema() itself would reject, since its only job is presence detection, not validation.
+// Bounded for free by loadOpenApiDocument()'s own MAX_DOCUMENT_BYTES check upstream.
+function collectUnsupportedAnnotationKeys(node, found, seen) {
+	if (node === null || typeof node !== 'object' || Array.isArray(node) || seen.has(node)) return;
+	seen.add(node);
+	for (const key of Object.keys(node)) {
+		if (DROPPED_KEYWORDS.has(key)) found.add(key);
+		if (RECURSED_KEYWORDS.has(key)) {
+			const value = node[key];
+			// `properties` is a field-NAME -> schema map (its VALUES are schemas, its keys are not
+			// schema keywords at all) -- a real bug caught live before merge: recursing into the
+			// map object itself, instead of `Object.values(value)`, silently walked past every
+			// property's actual schema and found nothing beneath `properties` ever. `items`/
+			// `additionalProperties` ARE schemas directly; `oneOf`/`anyOf`/`allOf` are arrays of
+			// schemas, already handled by the branch below.
+			if (key === 'properties' && value && typeof value === 'object' && !Array.isArray(value)) {
+				for (const propSchema of Object.values(value)) collectUnsupportedAnnotationKeys(propSchema, found, seen);
+			} else if (Array.isArray(value)) {
+				for (const item of value) collectUnsupportedAnnotationKeys(item, found, seen);
+			} else {
+				collectUnsupportedAnnotationKeys(value, found, seen);
+			}
+		}
+	}
+}
+
+function collectSchemaRootsFromMediaTypes(content, roots) {
+	if (!content || typeof content !== 'object' || Array.isArray(content)) return;
+	for (const mediaEntry of Object.values(content)) {
+		const schema = mediaEntry && typeof mediaEntry === 'object' && !Array.isArray(mediaEntry) ? mediaEntry.schema : null;
+		if (schema && typeof schema === 'object' && !Array.isArray(schema)) roots.push(schema);
+	}
+}
+
+// Every real schema root a document can offer `inlineSchema()`: named `components.schemas`
+// entries, every operation's requestBody/response content schemas, and every operation's
+// parameter schemas -- deliberately NOT `info`/`servers`/`tags`/security schemes, none of which
+// are ever schema-shaped.
+export function findUnsupportedAnnotations(doc) {
+	const roots = [];
+	const schemas = doc.components?.schemas;
+	if (schemas && typeof schemas === 'object' && !Array.isArray(schemas)) roots.push(...Object.values(schemas));
+
+	const paths = doc.paths;
+	if (paths && typeof paths === 'object' && !Array.isArray(paths)) {
+		for (const item of Object.values(paths)) {
+			if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+			for (const [verbOrKey, operation] of Object.entries(item)) {
+				if (!HTTP_METHODS.has(verbOrKey) || !operation || typeof operation !== 'object' || Array.isArray(operation)) continue;
+				collectSchemaRootsFromMediaTypes(operation.requestBody?.content, roots);
+				if (operation.responses && typeof operation.responses === 'object' && !Array.isArray(operation.responses)) {
+					for (const resp of Object.values(operation.responses)) {
+						collectSchemaRootsFromMediaTypes(resp?.content, roots);
+					}
+				}
+				if (Array.isArray(operation.parameters)) {
+					for (const p of operation.parameters) {
+						if (p && typeof p === 'object' && !Array.isArray(p) && p.schema && typeof p.schema === 'object' && !Array.isArray(p.schema)) {
+							roots.push(p.schema);
+						}
+					}
+				}
+			}
+		}
+	}
+
+	const found = new Set();
+	const seen = new Set();
+	for (const root of roots) collectUnsupportedAnnotationKeys(root, found, seen);
+	return [...found].sort();
+}
 // 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`.
@@ -374,7 +492,11 @@ export function indexOpenApiDocument(doc) {
 			const security = Array.isArray(operation.security) ? operation.security : null;
 			const summary = typeof operation.summary === 'string' ? operation.summary : null;
 			const tags = Array.isArray(operation.tags) ? operation.tags : null;
-			const entry = { verb, path: routeKey, operationId, requestBody, responses, parameters, security, summary, tags };
+			// A10: same "raw, no size cap at index time" reasoning as summary above -- MAX_DESCRIPTION_
+			// LENGTH is enforced only at applyDescription() (the point of actually copying it into the
+			// contract), matching where every other length/count cap in this file is enforced.
+			const description = typeof operation.description === 'string' ? operation.description : null;
+			const entry = { verb, path: routeKey, operationId, requestBody, responses, parameters, security, summary, tags, description };
 
 			const routeMatchKey = `${verb} ${normalizedRoute}`;
 			const existingRoute = byRoute.get(routeMatchKey);
@@ -438,6 +560,9 @@ export function inlineSchema(node, componentSchemas, opts = {}) {
 		maxDepth: opts.maxDepth ?? MAX_SCHEMA_DEPTH,
 		maxNodes: opts.maxNodes ?? MAX_SCHEMA_NODES,
 		maxPatternLength: opts.maxPatternLength ?? MAX_PATTERN_LENGTH,
+		// A11: opt-in only (default false, matching every prior call site's existing behavior
+		// byte-for-byte when the caller doesn't pass it) -- see D-openapi-field-docs.
+		includeFieldDocs: opts.includeFieldDocs ?? false,
 	};
 	const state = { nodes: 0 };
 	try {
@@ -464,11 +589,14 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 		// module doesn't attempt to MERGE $ref with a sibling assertion, with ONE exception (A7):
 		// `default` is a real, human-authored override worth carrying through (the exact real shape
 		// `{"$ref": ".../ProjectListSort", "default": "READINESS"}` -- a $ref-typed parameter
-		// schema with its own default value, 9 real occurrences). A DROPPED_KEYWORDS sibling (e.g. a
-		// documentation-only `description`) is harmless and ignored; anything else would need merge
-		// semantics this vertical slice doesn't implement, so it fails closed.
+		// schema with its own default value, 9 real occurrences). A DROPPED_KEYWORDS or
+		// DOCUMENTATION_KEYWORDS sibling (e.g. a documentation-only `description`) is harmless and
+		// ignored -- NOT merged onto the resolved schema even when includeFieldDocs is on (A11: 0
+		// real occurrences of a $ref carrying a sibling description/example, measured directly, so
+		// there is no real case to build merge semantics for, unlike `default`'s 9); anything else
+		// would need merge semantics this vertical slice doesn't implement, so it fails closed.
 		const siblingKeys = Object.keys(node).filter((k) => k !== '$ref');
-		if (siblingKeys.some((k) => !DROPPED_KEYWORDS.has(k) && k !== 'default')) fail('ref-with-siblings');
+		if (siblingKeys.some((k) => !DROPPED_KEYWORDS.has(k) && !DOCUMENTATION_KEYWORDS.has(k) && k !== 'default')) fail('ref-with-siblings');
 		const ref = node['$ref'];
 		if (typeof ref !== 'string' || !ref.startsWith(SCHEMA_REF_PREFIX)) fail('unsupported-ref');
 		const name = ref.slice(SCHEMA_REF_PREFIX.length);
@@ -516,6 +644,32 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 		if (key === '$ref' || key === 'format') continue; // format already handled above
 		if (DROPPED_KEYWORDS.has(key)) continue;
 
+		// A11: description/example are DROPPED (same as before this item) unless includeFieldDocs is
+		// on -- when it is, copy verbatim IF the value passes a defensive length check, else drop
+		// (silently, same as if the flag were off for this one field) rather than failing the whole
+		// schema closed. Unlike an ASSERTION keyword's fail-closed policy, dropping an annotation
+		// NEVER changes what the schema validates -- only how well-documented it is -- so there is no
+		// correctness reason to fail the operation over one oversized documentation string, and a
+		// per-FIELD warning here would be unusably noisy (a single schema can carry dozens of these,
+		// unlike A10's one-per-operation description). Real data never exercises this path (measured
+		// max: 3,148 for description, 70 for example -- both far under their caps), so this is a
+		// defensive bound against a hostile/malformed --openapi-file, not an expected real branch.
+		if (DOCUMENTATION_KEYWORDS.has(key)) {
+			if (!limits.includeFieldDocs) continue;
+			if (key === 'description') {
+				if (typeof node.description === 'string' && node.description.length <= MAX_DESCRIPTION_LENGTH) {
+					out.description = node.description;
+				}
+			} else if (key === 'example') {
+				let serialized;
+				try { serialized = JSON.stringify(node.example); } catch { serialized = null; }
+				if (serialized !== undefined && serialized !== null && serialized.length <= MAX_EXAMPLE_LENGTH) {
+					out.example = node.example;
+				}
+			}
+			continue;
+		}
+
 		if (key === 'pattern') {
 			// Two patterns can't be expressed without allOf, which this slice doesn't attempt to
 			// synthesize -- a node with BOTH format:'uuid' and an explicit pattern fails closed
@@ -597,7 +751,7 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 // let alone body shape. `docEntry` is the OpenAPI-side entry (from byOperationId or byRoute) whose
 // `.requestBody` indexOpenApiDocument() retained. Never treats "nothing to project" as a failure --
 // only an actual unresolvable schema increments schema_unresolved / sets schemaUnresolvedReason.
-function applyRequestBodySchema(result, docEntry, componentSchemas, stats) {
+function applyRequestBodySchema(result, docEntry, componentSchemas, stats, includeFieldDocs) {
 	const requestBody = docEntry.requestBody;
 	if (!requestBody || Object.hasOwn(requestBody, '$ref')) {
 		stats.schema_none++;
@@ -614,7 +768,7 @@ function applyRequestBodySchema(result, docEntry, componentSchemas, stats) {
 		stats.schema_none++;
 		return;
 	}
-	const resolved = inlineSchema(schemaNode, componentSchemas);
+	const resolved = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
 	if (resolved.ok) {
 		result.requestBodySchema = resolved.schema;
 		result.requestBodyRequired = requestBody.required === true;
@@ -666,7 +820,7 @@ function canonicalJson(value) {
 // nothing it had before (nothing read `default` at all until now); one whose `default` describes an
 // error -- the overwhelmingly common case, and the only case `bskel contract export` itself emits --
 // gains a real error schema it previously dropped silently.
-function projectResponseSchemas(responses, statusRe, componentSchemas, { includeDefault = false } = {}) {
+function projectResponseSchemas(responses, statusRe, componentSchemas, { includeDefault = false, includeFieldDocs = false } = {}) {
 	if (!responses) return { outcome: 'none' };
 	const statusKeys = Object.keys(responses);
 	if (statusKeys.length > MAX_RESPONSES_PER_OPERATION) {
@@ -693,9 +847,14 @@ function projectResponseSchemas(responses, statusRe, componentSchemas, { include
 		return { outcome: sawContentWithoutJson ? 'skipped-media-type' : 'none' };
 	}
 
+	// A11: includeFieldDocs can make two previously-identical-looking resolved schemas turn out
+	// distinct (different field-level description/example), which correctly increases `sources` --
+	// see D-openapi-field-docs for why this is a self-consistent consequence of being more precise
+	// about equality, not a bug, and the real measurement confirming it never actually happens on
+	// the Team-IZ-Backend oracle.
 	const resolvedByCanonical = new Map();
 	for (const node of rawNodesByKey.values()) {
-		const resolved = inlineSchema(node, componentSchemas);
+		const resolved = inlineSchema(node, componentSchemas, { includeFieldDocs });
 		if (!resolved.ok) return { outcome: 'unresolved', reason: resolved.reason };
 		const canonicalKey = canonicalJson(resolved.schema);
 		if (!resolvedByCanonical.has(canonicalKey)) resolvedByCanonical.set(canonicalKey, resolved.schema);
@@ -719,10 +878,10 @@ function projectResponseSchemas(responses, statusRe, componentSchemas, { include
 // schemaProjection.enabled guard). Fields are set ONLY when resolved -- omitted, not null/false,
 // so an operation with nothing to project stays byte-identical to pre-A3 output (same discipline
 // as A2's requestBodySchema).
-function applyResponseSchemas(result, docEntry, componentSchemas, stats) {
-	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, SUCCESS_STATUS_RE, componentSchemas), stats, 'response');
+function applyResponseSchemas(result, docEntry, componentSchemas, stats, includeFieldDocs) {
+	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, SUCCESS_STATUS_RE, componentSchemas, { includeFieldDocs }), stats, 'response');
 	// A6: `default` contributes to the ERROR side only -- see projectResponseSchemas' own comment.
-	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, ERROR_STATUS_RE, componentSchemas, { includeDefault: true }), stats, 'error');
+	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, ERROR_STATUS_RE, componentSchemas, { includeDefault: true, includeFieldDocs }), stats, 'error');
 }
 
 function applyProjectionOutcome(result, projected, stats, kind) {
@@ -811,7 +970,7 @@ function collectNonPathParameters(rawParameters) {
 // The middle+last cases both add the parameter to sourceParameters (every OTHER field it carries is
 // real and safe); the last case additionally drives CONTRACT_OPENAPI_PARAMETERS_UNRESOLVED, exactly
 // the "found but couldn't project" distinction applyRequestBodySchema already draws for a body.
-function copyParameter(raw, componentSchemas) {
+function copyParameter(raw, componentSchemas, includeFieldDocs) {
 	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, reason: 'not-a-parameter-object' };
 	if (Object.hasOwn(raw, '$ref')) return { ok: false, reason: 'ref-parameter' };
 	if (Object.hasOwn(raw, 'content')) return { ok: false, reason: 'content-parameter' };
@@ -829,7 +988,7 @@ function copyParameter(raw, componentSchemas) {
 	}
 
 	if (Object.hasOwn(raw, 'schema')) {
-		const resolved = inlineSchema(raw.schema, componentSchemas);
+		const resolved = inlineSchema(raw.schema, componentSchemas, { includeFieldDocs });
 		if (resolved.ok) {
 			parameter.schema = resolved.schema;
 		} else {
@@ -846,7 +1005,7 @@ function copyParameter(raw, componentSchemas) {
 // `result`: parametersTotal/parametersCleanCount (reconciliation-internal bookkeeping consumed only
 // by snapshotFromReconciliation, never copied into the contract itself), parametersSkippedDialect,
 // sourceParameters (omitted when empty), parametersUnresolved (omitted when empty).
-function applyParameters(result, docEntry, index, stats, schemaProjectionEnabled) {
+function applyParameters(result, docEntry, index, stats, schemaProjectionEnabled, includeFieldDocs) {
 	const candidates = collectNonPathParameters(docEntry.parameters);
 	if (candidates.length === 0) {
 		stats.parameters_none++;
@@ -871,7 +1030,7 @@ function applyParameters(result, docEntry, index, stats, schemaProjectionEnabled
 		}
 	} else {
 		for (const raw of candidates) {
-			const outcome = copyParameter(raw, index.componentSchemas);
+			const outcome = copyParameter(raw, index.componentSchemas, includeFieldDocs);
 			if (!outcome.ok) {
 				unresolved.push({ name: safeParamName(raw), in: safeParamIn(raw), reason: outcome.reason });
 				continue;
@@ -954,6 +1113,34 @@ function applySummaryAndTags(result, docEntry, stats) {
 	}
 }
 
+// A10 (D-openapi-description): the one A7/A8/A9 sibling that is NOT default-on -- gated behind
+// `includeDescriptions`, opt-in only, because the measured cost (2,442.7 bytes/operation average
+// across the real oracle, re-confirmed exactly at this item's own implementation) is larger than
+// every other field this whole passthrough effort copies COMBINED. Copied verbatim, no
+// transformation (unlike a schema, there is no keyword whitelist to apply to a plain string) --
+// fails closed only on length, via MAX_DESCRIPTION_LENGTH, the same defensive posture every other
+// unbounded-size field in this file has (same defensive-cap class as D-security-1/D-security-2) --
+// protecting the contract file/gate-token hashing cost from a malformed or hostile --openapi-file,
+// not a normal document.
+function applyDescription(result, docEntry, stats, includeDescriptions) {
+	if (!includeDescriptions) {
+		stats.description_skipped_flag++;
+		return;
+	}
+	const raw = docEntry.description;
+	if (typeof raw !== 'string' || raw.length === 0) {
+		stats.description_none++;
+		return;
+	}
+	if (raw.length > MAX_DESCRIPTION_LENGTH) {
+		result.descriptionUnresolvedReason = 'too-long';
+		stats.description_unresolved++;
+		return;
+	}
+	result.sourceDescription = raw;
+	stats.description_copied++;
+}
+
 // A8: per-status responses -- additive to (never replacing) the responseSchema/errorSchema union
 // projection above; contracts/validate.mjs is untouched by this item, see D-openapi-per-status.
 // Gated on schemaProjectionEnabled, same reasoning as applyParameters -- a JSON Schema resolved
@@ -971,7 +1158,7 @@ function applySummaryAndTags(result, docEntry, stats) {
 // at it instead of re-resolving. When sources>1 (never observed on real data, but structurally
 // possible) or the status sits outside both buckets (a 1xx/3xx key), the status's own schema is
 // resolved individually into an inline `schema` instead.
-function applyPerStatusResponses(result, docEntry, componentSchemas, stats, schemaProjectionEnabled) {
+function applyPerStatusResponses(result, docEntry, componentSchemas, stats, schemaProjectionEnabled, includeFieldDocs) {
 	if (!schemaProjectionEnabled) {
 		result.perStatusResponsesSkippedDialect = true;
 		stats.per_status_skipped_dialect++;
@@ -1020,7 +1207,7 @@ function applyPerStatusResponses(result, docEntry, componentSchemas, stats, sche
 					} else if ((ERROR_STATUS_RE.test(key) || key === DEFAULT_STATUS_KEY) && result.errorSchema && result.errorSchemaSources === 1) {
 						entry.schemaFrom = 'error';
 					} else {
-						const resolved = inlineSchema(schemaNode, componentSchemas);
+						const resolved = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
 						// unresolved here just leaves `schema` absent -- `description` alone (if any) stays
 						// valid, same "copied without schema" posture copyParameter() already takes.
 						if (resolved.ok) entry.schema = resolved.schema;
@@ -1050,7 +1237,7 @@ function applyPerStatusResponses(result, docEntry, componentSchemas, stats, sche
 // schemas/feature-contract.schema.json too). Gated on schemaProjectionEnabled for the same reason
 // as applyPerStatusResponses above -- a media-type schema resolves through the same inlineSchema()
 // path.
-function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schemaProjectionEnabled) {
+function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schemaProjectionEnabled, includeFieldDocs) {
 	if (!schemaProjectionEnabled) {
 		result.requestMediaTypesSkippedDialect = true;
 		stats.request_media_types_skipped_dialect++;
@@ -1086,7 +1273,7 @@ function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schem
 		const entry = {};
 		const schemaNode = mediaEntry && typeof mediaEntry === 'object' && !Array.isArray(mediaEntry) ? mediaEntry.schema : null;
 		if (schemaNode && typeof schemaNode === 'object' && !Array.isArray(schemaNode)) {
-			const resolved = inlineSchema(schemaNode, componentSchemas);
+			const resolved = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
 			if (resolved.ok) { entry.schema = resolved.schema; cleanCount++; }
 		} else {
 			cleanCount++; // no schema declared for this media type at all is not a failure -- same
@@ -1105,18 +1292,73 @@ function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schem
 	}
 }
 
+// A9 (D-openapi-path-params): the real fix for A7's own disclosed `batchRequestId` finding --
+// contracts/emit.mjs's pathParamsSchema() names a path segment by NAME ONLY (`/id$/i` ->
+// BARE_UUID_PATTERN), a heuristic that is provably wrong for at least one real path parameter
+// (`batchRequestId`, a plain string despite the "Id" suffix). Unlike A7's own parameters (query/
+// header/cookie, which stay ADDITIVE alongside pathParams' own separate story), this one REPLACES
+// the heuristic's guess in place for any segment the source document can answer -- the same
+// "positive information overrides a guess" principle A8's `hasSourceMediaTypeInfo` already
+// established, applied here to path-param TYPE instead of request media type.
+//
+// Returns a Map (never a plain object -- this is `--openapi-file`-sourced, untrusted data keyed by
+// parameter NAME, the exact class RESPONSE_STATUS_KEY_RE/MEDIA_TYPE_RE exist to defend against
+// elsewhere in this file; a Map sidesteps prototype pollution entirely rather than needing a third
+// whitelist regex) from resolved path-parameter name to its inlined schema, stashed transiently on
+// `result` for contracts/emit.mjs's pathParamsSchema() call to consult -- never itself persisted to
+// the contract; only the corrected `pathParams` (and, when at least one segment still falls back to
+// the heuristic, `pathParamsHeuristic`) are.
+function applyPathParameterSchemas(result, docEntry, componentSchemas, stats, schemaProjectionEnabled, includeFieldDocs) {
+	const rawParameters = Array.isArray(docEntry.parameters) ? docEntry.parameters : [];
+	const pathParams = rawParameters.filter((p) => p && typeof p === 'object' && !Array.isArray(p) && p.in === 'path');
+	if (pathParams.length === 0) {
+		stats.path_params_none++;
+		return;
+	}
+	if (!schemaProjectionEnabled) {
+		result.pathParamsSkippedDialect = true;
+		stats.path_params_skipped_dialect++;
+		return;
+	}
+	const resolved = new Map();
+	for (const p of pathParams) {
+		const name = safeParamName(p);
+		if (name === null || !Object.hasOwn(p, 'schema')) continue; // no name, or source declared no schema -- nothing to prefer over the heuristic for this one segment
+		const schemaNode = p.schema;
+		if (!schemaNode || typeof schemaNode !== 'object' || Array.isArray(schemaNode)) continue;
+		const out = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
+		if (out.ok) resolved.set(name, out.schema);
+	}
+	if (resolved.size > 0) {
+		result.pathParamSchemas = resolved;
+		stats.path_params_copied++;
+	} else {
+		stats.path_params_unresolved++;
+	}
+}
+
 // A7: the single entry point called from reconcileModule()'s two matched/adopted call sites --
 // exactly the placement A2/A3's own helpers already occupy, which IS the refusal mechanism for
 // every other resolution kind (drift/missing/ambiguous/unresolved never reach this function at
 // all, see reconcileModule below).
-function applyPassthrough(result, docEntry, index, stats, schemaProjectionEnabled, referencedSchemeNames) {
-	applyParameters(result, docEntry, index, stats, schemaProjectionEnabled);
+function applyPassthrough(result, docEntry, index, stats, schemaProjectionEnabled, referencedSchemeNames, includeDescriptions) {
+	// A11 (D-openapi-field-docs): includeDescriptions doubles as includeFieldDocs here -- reusing
+	// the existing --descriptions flag rather than adding a second one, since it already governs
+	// "copy source-authored documentation prose" at the operation level (A10); field-level
+	// description/example is the same policy applied one level deeper into the same schemas.
+	applyParameters(result, docEntry, index, stats, schemaProjectionEnabled, includeDescriptions);
 	applySecurity(result, docEntry, index, stats, referencedSchemeNames);
 	applySummaryAndTags(result, docEntry, stats);
 	// A8: same matched/adopted-only placement as the three calls above -- this IS the refusal
 	// mechanism for every other resolution kind, extended unchanged for the two new fields.
-	applyPerStatusResponses(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled);
-	applyRequestMediaTypes(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled);
+	applyPerStatusResponses(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled, includeDescriptions);
+	applyRequestMediaTypes(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled, includeDescriptions);
+	// A9: same placement again, for the path-parameter schema fix.
+	applyPathParameterSchemas(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled, includeDescriptions);
+	// A10: same placement again -- applyDescription() itself decides whether includeDescriptions
+	// gates it off, matching how applyParameters decides its own schemaProjectionEnabled gate
+	// internally rather than being skipped by the caller.
+	applyDescription(result, docEntry, stats, includeDescriptions);
 }
 
 // The core reconciliation, pure (no I/O). `module` is a scanReport related_modules entry (as
@@ -1124,7 +1366,7 @@ function applyPassthrough(result, docEntry, index, stats, schemaProjectionEnable
 // selection buildContract() will use, so endpointKey(ci,ei) lines up). `pathPrefix`, if given
 // (from --path-prefix), overrides inference entirely but the anchor pass still runs so its
 // deltas are recorded for audit in the snapshot.
-export function reconcileModule({ index, module, pathPrefix = null }) {
+export function reconcileModule({ index, module, pathPrefix = null, includeDescriptions = false }) {
 	const anchorDeltas = [];
 	for (const controller of module.controllers) {
 		for (const ep of controller.endpoints) {
@@ -1164,6 +1406,11 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 		// the A7 counters above.
 		per_status_copied: 0, per_status_skipped_unresolved: 0, per_status_none: 0, per_status_skipped_dialect: 0,
 		request_media_types_copied: 0, request_media_types_unresolved: 0, request_media_types_none: 0, request_media_types_skipped_dialect: 0,
+		// A9: source-backed path-parameter schema counters, same per-operation-tally shape.
+		path_params_copied: 0, path_params_unresolved: 0, path_params_none: 0, path_params_skipped_dialect: 0,
+		// A10: operation-level description counters. skipped_flag is the common case when
+		// --descriptions was not passed -- distinct from `none` (flag WAS passed, source had nothing).
+		description_copied: 0, description_unresolved: 0, description_none: 0, description_skipped_flag: 0,
 	};
 	// A7: accumulates every security-scheme name any operation's COPIED security requirement
 	// actually referenced, across the WHOLE module -- becomes the contract-root sourceSecuritySchemes
@@ -1206,14 +1453,14 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 						// A2/A3: matched/adopted ONLY -- schema enrichment never applies to drift/missing/
 						// ambiguous/unresolved, same "don't guess" rule A1 established for path/verb.
 						if (schemaProjection.enabled) {
-							applyRequestBodySchema(result, docEntry, index.componentSchemas, stats);
-							applyResponseSchemas(result, docEntry, index.componentSchemas, stats);
+							applyRequestBodySchema(result, docEntry, index.componentSchemas, stats, includeDescriptions);
+							applyResponseSchemas(result, docEntry, index.componentSchemas, stats, includeDescriptions);
 						}
 						// A7: same matched/adopted-only placement -- this IS the refusal mechanism for
 						// every other resolution kind. Called unconditionally (not gated on
 						// schemaProjection.enabled): parameters gate internally (schema-bearing);
 						// security/summary/tags are dialect-independent and always attempted.
-						applyPassthrough(result, docEntry, index, stats, schemaProjection.enabled, referencedSecuritySchemeNames);
+						applyPassthrough(result, docEntry, index, stats, schemaProjection.enabled, referencedSecuritySchemeNames, includeDescriptions);
 					} else {
 						result = {
 							kind: 'drift', reason: 'path',
@@ -1239,10 +1486,10 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 					};
 					stats.adopted++;
 					if (schemaProjection.enabled) {
-						applyRequestBodySchema(result, hits[0], index.componentSchemas, stats);
-						applyResponseSchemas(result, hits[0], index.componentSchemas, stats);
+						applyRequestBodySchema(result, hits[0], index.componentSchemas, stats, includeDescriptions);
+						applyResponseSchemas(result, hits[0], index.componentSchemas, stats, includeDescriptions);
 					}
-					applyPassthrough(result, hits[0], index, stats, schemaProjection.enabled, referencedSecuritySchemeNames);
+					applyPassthrough(result, hits[0], index, stats, schemaProjection.enabled, referencedSecuritySchemeNames, includeDescriptions);
 				} else if (hits.length === 1) {
 					// A single route match, but the document itself never gave that operation an
 					// operationId -- nothing to route by, so this can't become an addressable
@@ -1277,7 +1524,7 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 
 // Convenience entry point: load + index + reconcile in one call, propagating the first failure.
 // This is what bin/bskel.mjs's cmdContractEmit calls.
-export function buildReconciliation({ filePath, module, pathPrefix = null }) {
+export function buildReconciliation({ filePath, module, pathPrefix = null, includeDescriptions = false }) {
 	if (pathPrefix != null && !PATH_PREFIX_RE.test(pathPrefix)) {
 		return { ok: false, error: `--path-prefix "${pathPrefix}" is not a valid path prefix (expected e.g. "/api/v0")` };
 	}
@@ -1301,7 +1548,7 @@ export function buildReconciliation({ filePath, module, pathPrefix = null }) {
 	}
 	const indexed = indexOpenApiDocument(loaded.doc);
 	if (!indexed.ok) return indexed;
-	const recon = reconcileModule({ index: indexed, module, pathPrefix });
+	const recon = reconcileModule({ index: indexed, module, pathPrefix, includeDescriptions });
 	return {
 		ok: true,
 		document: {
@@ -1325,6 +1572,10 @@ export function buildReconciliation({ filePath, module, pathPrefix = null }) {
 		// A7: only schemes actually referenced by at least one copied sourceSecurity requirement --
 		// contracts/emit.mjs attaches this at the contract root when non-empty.
 		sourceSecuritySchemes: recon.sourceSecuritySchemes,
+		// D-unsupported-annotation-warning: computed once per document, not per-operation -- a
+		// module-wide presence signal, not a per-operation fact, so contracts/emit.mjs pushes at
+		// most one warning per keyword name for the whole module, not one per operation.
+		unsupportedAnnotations: findUnsupportedAnnotations(loaded.doc),
 	};
 }
 
@@ -1365,6 +1616,18 @@ function requestMediaTypesDecision(result) {
 	if (result.requestMediaTypesUnresolvedReason) return `unresolved:${result.requestMediaTypesUnresolvedReason}`;
 	return 'none';
 }
+// A9: same decision-only audit-trail shape, for the path-parameter schema fix.
+function pathParamSchemasDecision(result) {
+	if (result.pathParamsSkippedDialect) return 'skipped:dialect';
+	if (result.pathParamSchemas) return `copied:${result.pathParamSchemas.size}`;
+	return 'none';
+}
+// A10: same decision-only audit-trail shape as every field above.
+function descriptionDecision(result) {
+	if (result.sourceDescription) return 'copied';
+	if (result.descriptionUnresolvedReason) return `unresolved:${result.descriptionUnresolvedReason}`;
+	return 'none';
+}
 
 // `sourceFile`: {file, outsideRepo} precomputed by the caller (bin/bskel.mjs knows the repo
 // root; this module deliberately doesn't) -- keeps machine-specific absolute paths out of a
@@ -1405,6 +1668,10 @@ export function snapshotFromReconciliation(reconciliation, { featureId, sourceFi
 				// A8: same decision-only audit trail, for the two new passthrough fields.
 				per_status_responses: perStatusResponsesDecision(result),
 				request_media_types: requestMediaTypesDecision(result),
+				// A9: same decision-only audit trail, for the path-parameter schema fix.
+				path_param_schemas: pathParamSchemasDecision(result),
+				// A10: same decision-only audit trail, for the opt-in operation-level description.
+				description: descriptionDecision(result),
 			};
 		}
 	}