fix(openapi): enforce stable unique operationIds

[seonghobae]

Objective

Advance issue #315 with a bounded machine-readable API contract invariant: every HTTP operation in the repository-owned buyer OpenAPI must declare one explicit, unique operationId so standalone and naruon-compatible generated clients cannot acquire ambiguous method identities.

Fresh exact state — 2026-08-10

• exact source head: f4b08dc83f972f7ea98027b0a1d9209e33496873;
• exact protected main: 55d7ae8647208e301f282350f076eeddaba61d11;
• clean reconstruction: two commits, two changed files, mergeable and Ready;
• exact-head CI 31387420565: success;
• Buyer-readiness scripts, Maven test/coverage/Javadocs acceptance, and synthetic-merge compatibility all succeeded;
• exact-head Security Scan 31387420476: success;
• exact-head SAST Semgrep 31387420373: success;
• the fuzz workflow is not applicable to this Python contract-only path and was not presented as passing evidence;
• no check, status, comment, or model output is qualifying independent approval.

RCA and test-first reconstruction

Predecessor #332 exact head 8ae7cbcf109633c866dd3330638ecdf0d4d8ccee contained the correct checker and tests, but its stale ancestry lacked scripts/verify_maven_test_reports.py. Maven itself passed; CI then failed at the protected-main report-verification step. Updating PR base metadata did not rewrite branch ancestry.

A clean test-only branch was therefore created directly from protected main and first proved the checker module was absent. The already-reviewed stdlib implementation was then copied without importing predecessor build/security history.

Fresh blob comparison confirms the clean branch preserves the exact predecessor semantics:

• scripts/openapi_operation_id_contract.py: 700ed07d10fcd67f5a3dfdc8f4dc8547f87bc4e3;
• scripts/test_openapi_operation_id_contract.py: 0b2fe4179374062652271c5a1899b59660a0b96d.

#332 is closed as superseded.

Contract

The checker:

• recognizes only actual HTTP methods under OpenAPI path items;
• requires every operation to have a non-empty string operationId;
• rejects duplicate operationIds and reports both method/path identities;
• does not misclassify path-level metadata such as parameters as an operation;
• validates the current buyer OpenAPI through deterministic offline tests;
• uses only Python standard-library parsing logic already accepted by this repository's script-test boundary.

Scope / non-completion boundary

This is one acceptance item under issue #315. It does not claim complete route/DTO/error/schema parity, API version negotiation, breaking-change detection, generated clients, release provenance, or standalone+naruon compatibility. PR #305 remains the canonical documentation writer and PR #316 remains a separate bounded license/example/delete-route integrity slice.

Merge gate

Keep this exact head unchanged. Auto-merge may complete only after live repository protection still sees every applicable required check passing, zero valid unresolved findings, and the counted approving review from a qualifying independent reviewer with write access. Automated evidence is not approval.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 58 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: af008545-a127-4d53-946d-8b88467f8a50

📥 Commits

Reviewing files that changed from the base of the PR and between 55d7ae8 and f4b08dc.

📒 Files selected for processing (2)

• scripts/openapi_operation_id_contract.py
• scripts/test_openapi_operation_id_contract.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

@opencode-agent @cwl-noema-review Please independently review exact current head f4b08dc83f972f7ea98027b0a1d9209e33496873 against protected main 55d7ae8647208e301f282350f076eeddaba61d11. Exact-head CI 31387420565, Security Scan 31387420476, and SAST 31387420373 are successful. Verify the offline stdlib checker recognizes only HTTP operations, requires non-empty unique operationIds, reports both duplicate identities, ignores path-level metadata, and remains a bounded issue-#315 invariant rather than API-completeness evidence. Advisory review only; do not mutate, count as human approval, merge, or weaken gates.