alkhttp/tasks/adapters/review-002-oai13-path-item-wildcards.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-002-oai13-path-item-wildcards	Path-item parameters, 2XX/4XX/5XX wildcards, webhooks handling (OAI-13)	completed	review-002-oai11-ref-memoization	moderate	medium	component	implementation	adapters review-002 from-openapi openapi-spec

Description

Review 002 OAI-13 [major]. Three common real-world OpenAPI shapes are still silently mishandled (verified at openapi_spec.rs:276-336 + from_openapi.rs:136-145):

1. Path-item-level parameters (shared params declared next to the path key — extremely common in real specs) never merge into operations → {id} unbound → the whole import fails with a misleading diagnosis (the skip filter at :314-320 explicitly whitelists "parameters" out of the unsupported-methods warning, so nothing names the cause).
2. Response wildcard keys: "2XX" is missed by the SSE-detection success sweep (an SSE stream under 2XX imports as a giant-text Mutation — the exact OAI-06 misbehavior, one spelling away); "4XX"/"5XX" error keys drop silently with the generic warn (the test at from_openapi.rs:840 enshrines silent 5XX dropping).
3. Top-level webhooks silently vanish from mixed documents.

Acceptance Criteria

• Path-item parameters merge into each operation under the path (operation-level entries override per OpenAPI spec semantics); the import no longer fails with "unbound placeholder" for shared-param specs
• Success sweep accepts "2XX" (SSE detection + output schema) and error sweep accepts "4XX"/"5XX" (HTTP_-class mapping per the wildcard's implied status range — choose the mapping, e.g. 4XX → the strongest available code, and document it)
• webhooks: import (as Mutations/Webhook-kind ops or a decided visibility) or reject the key loudly — pick per ADR-066's single-endpoint adapter philosophy and record the decision
• The misleading-diagnosis fix: when import fails after skipping path-item parameters, the error names the actual cause (the skip-filter whitelist must not hide the parameter key from the unsupported-features warning)
• Tests: shared-path-params spec imports correctly (incl. operation-override precedence); 2XX-declared SSE imports as Sub; 5XX-declared error lands in error schemas; webhooks-only and mixed docs behave per the decision
• cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check pass

References

• docs/reviews/002-post-remediation-review.md (Part E', OAI-13; Test-gaps: Petstore-with-shared-params)
• src/adapters/openapi_spec.rs:276-336 (method sweep + skip filter), from_openapi.rs:131-151 (success sweep), :248-270 (error sweep), :840 (the enshrining test)
• docs/architecture/decisions/066-from-jsonschema-as-http-adapter.md, /051-yaml-input-for-from-openapi.md
• tasks/adapters/review-001-openapi-loud-degradation.md (the OAI-06 matrix this extends)

Notes

Slice suggestion: (1) path-item parameters + diagnosis fix, (2) wildcard sweeps, (3) webhooks decision. The wildcard-to-error-status mapping is the one judgment call worth a line in ADR-066 (e.g. "4XX wildcards project to their range's first legal HTTP_ code per error dedup rules"). Sequence after review-002-oai11-ref-memoization (same file, resolver shape changes first) — or rebase-verify.

Summary

Path-item parameters merge (op-level override wins by last-insert), 2XX/4XX/5XX wildcards (4XX->HTTP_400, 5XX->HTTP_500 class representatives; 2XX authoritative for SSE/output when no concrete 2XX), webhooks rejected loudly at parse time. Unbound-placeholder diagnosis improved.