[codex] Harden public API contracts

[ewlarson]

Summary

This PR finishes the v1 public API contract hardening pass for the current public surface.

It adds named Pydantic response models for the stable public response families, centralizes public error handling around the {"errors": [...]} envelope, documents shared error schemas in OpenAPI, and updates public routes to declare success/error contracts without changing successful wire payloads.

What Changed

• Added app/api/schemas.py with named response models for root, search, suggest, facets, resources, resource subroutes, home/blog posts, map/H3, OGC, OGM status, MCP metadata, citations, downloads, metadata, relationships, similar items, viewer payloads, and data dictionaries.
• Added centralized HTTP/validation/generic error handling with request IDs and safe 5xx bodies.
• Applied response models and shared documented error responses to public JSON routes.
• Kept gazetteer, admin, feedback, Slack, Turnstile, webhook, analytics, and shapefile compatibility routes hidden from public OpenAPI.
• Replaced public ad hoc error JSON with the shared error envelope where applicable.
• Sanitized search/Elasticsearch error paths so public responses do not expose raw backend details.
• Expanded API contract/OpenAPI regression tests to reject generic success schemas for public routes.
• Updated internal and public docs for the error envelope, request ID behavior, and response-contract policy.

Why

Before this change, the API had safe behavior in many paths but lacked an explicit, testable public contract across the v1 surface. Several public responses were still effectively documented as generic dictionaries, and error bodies were not uniformly represented in OpenAPI.

This PR makes the public API safer and more predictable ahead of a v1.0.0 release while intentionally keeping dynamic OGM/Aardvark/B1G metadata fields extensible.

Validation

• python -m pytest tests/api/test_error_contracts.py
• Focused route regression suite: 198 passed, 9 skipped
• make lint-check
• COMPOSE_PROJECT_NAME=data-api WALLCLOCK_TIMEOUT_SECONDS=300 make test
  • 1759 passed, 129 skipped, 1 xpassed
  • Coverage: 61.42%

Follow-Up Before v1.0.0

This PR closes the public HTTP API contract hardening work, but I would still address these before tagging v1.0.0:

• Sanitize MCP JSON-RPC internal error payloads so they cannot expose raw str(exc).
• Put database migrations on rails with a schema ledger or Alembic baseline.
• Update release identity/version metadata from 0.7.0 to the final v1 version when ready.
• Run final k6 smoke/stress checks against a production-like deployment.