---
id: review-001-openapi-import-integrity
name: Resolve parameter/requestBody $refs; detect import collisions (OAI-04, OAI-05)
status: pending
depends_on: [review-001-ref-cycle-guard]
scope: narrow
risk: medium
impact: component
level: implementation
tags: [adapters, review-001, from-openapi]
---

## Description

Review 001 findings OAI-04 + OAI-05 — import produces ops that misbehave
silently at call time:

- **OAI-04** (`openapi_spec.rs:236-262`): parameter entries of the form
  `{"$ref": "#/components/parameters/Id"}` (extremely common in real
  specs) have no `name`, are silently skipped, and never reach
  `resolve_refs_recursive`; same for `requestBody: {"$ref": …}`. Only
  `components/schemas` is indexed (`:162-174`). Result: the op registers
  with `{id}` in the template but `id` absent from the schema; at call
  time the placeholder is substituted with the literal `{owner}` text and
  percent-encoded (`%7Bowner%7D`) — a well-formed request to a nonsense
  path, with credentials attached. No error at import or call time.
  Fix: index `components/parameters` + `requestBodies`, resolve the ref
  forms, and fail loudly on unresolved path placeholders (import and/or
  call time).
- **OAI-05** (`from_openapi.rs:51-65,160`): generated operation IDs
  collide by construction (`/x/{id}/y` and `/x/y` both → `get_x_y`);
  the registry silently replaces, so one op shadows another and
  `/search` under-reports. Detect duplicates within the import batch and
  fail loudly (or deterministically disambiguate + warn — pick one and
  document).

## Acceptance Criteria

- [ ] `{"$ref": "#/components/parameters/…"}` params and `requestBody` refs resolve into the op's schema (test)
- [ ] Unresolved path placeholders fail loudly (import-time, or call-time with a loud error — tested, not silently `%7Bowner%7D`)
- [ ] Duplicate operation IDs in one import batch are detected and rejected (or deterministically disambiguated + warned — tested)
- [ ] `cargo test` and `cargo clippy --all-targets -- -D warnings` pass

## References

- docs/reviews/001-initial-implementation-review.md (Part E, OAI-04, OAI-05)

## Notes

> Agent fills during implementation. Follows the cycle-guard task so
> the resolver is already hardened when the new ref kinds are wired
> through it.

## Summary

> Filled on completion.