feat: openapi spec cleanup for schemathesis fuzzing and cleaner API error responses

[simone-stacks]

Description

Improves OpenAPI schema definitions for better API documentation accuracy and validation.

Also introduces proper 405/404/400 HTTP error responses with allow headers.

These changes improve schema accuracy for tools like Schemathesis and ensure the OpenAPI spec matches actual API behavior.

A summary of the findings can be found here.

Applicable issues

• Fixes https://github.com/stx-labs/core-epics/issues/75

Additional info (benefits, drawbacks, caveats)

Benefits:

• More accurate API documentation
• Better client code generation from OpenAPI spec
• Enables automated API testing with Schemathesis
• Clearer error responses for API consumers:
  • 400 for invalid path parameters (e.g. /v3/blocks/NOTAHEX) - previously returned 404
  • 404 for paths that don't exist
  • 405 with Allow header for wrong HTTP methods - helps clients discover correct methods
• The 400 approach tells consumers "you found the right endpoint, fix your parameter" rather than "this doesn't exist"

Caveats:

• Stricter schemas may flag previously "working" requests that were technically invalid
• Some endpoints with complex parameter patterns (contract names, principals) still return 404 for invalid params instead of 400 - this matches previous behavior

Checklist

• Test coverage for new or modified code paths
• Changelog is updated
• Required documentation changes (e.g., docs/rpc/openapi.yaml and rpc-endpoints.md for v2 endpoints, event-dispatcher.md for new events)
• New clarity functions have corresponding PR in clarity-benchmarking repo

[codecov]

Codecov Report

❌ Patch coverage is 47.91667% with 75 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.56%. Comparing base (3da96c1) to head (5b299a7).

Files with missing lines	Patch %	Lines
stackslib/src/net/httpcore.rs	63.46%	38 Missing ⚠️
stackslib/src/net/http/error.rs	0.00%	32 Missing ⚠️
stackslib/src/net/http/mod.rs	0.00%	5 Missing ⚠️

❌ Your project check has failed because the head coverage (72.56%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

❗ There is a different number of reports uploaded between BASE (3da96c1) and HEAD (5b299a7). Click for more details.

HEAD has 27 uploads less than BASE

Flag	BASE (3da96c1)	HEAD (5b299a7)
	88	61

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6756      +/-   ##
===========================================
- Coverage    78.18%   72.56%   -5.62%     
===========================================
  Files          580      580              
  Lines       361096   361211     +115     
===========================================
- Hits        282312   262115   -20197     
- Misses       78784    99096   +20312     

Files with missing lines	Coverage Δ
stackslib/src/net/http/request.rs	82.21% <100.00%> (-0.36%)	⬇️
stackslib/src/net/http/mod.rs	49.51% <0.00%> (-2.53%)	⬇️
stackslib/src/net/http/error.rs	41.55% <0.00%> (-13.00%)	⬇️
stackslib/src/net/httpcore.rs	80.96% <63.46%> (-1.78%)	⬇️

... and 292 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3da96c1...5b299a7. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[BowTiedRadone]

@simone-stacks Thanks for opening the PR! I've just wrapped up an initial review focused on the specification changes. More reviews to come, as I am trying to check them carefully and ensure we maximize the impact of this effort.