feat(#416): real OpenAPI 3.0 spec at /api/openapi

[woahwhattheheck]

Summary

Closes #416.

/docs pointed Swagger UI at /api/openapi, but that route did not exist, so the docs page failed for every visitor. This PR:

• Adopts the existing routeDoc convention across every app/api/**/route.ts
• Adds GET /api/openapi that aggregates those docs into a valid OpenAPI 3.0 document with security schemes, shared component schemas, and request/response shapes
• Fixes middleware.ts PUBLIC_ROUTES: replaces the mangled /api/ingest-historical/openapi entry with /api/openapi
• Adds drift/validator coverage so newly added API routes must remain represented in the generated spec
• Preserves the repository's legacy Event source: null response compatibility while continuing to document live and historical as the non-null source values

Acceptance

• /api/openapi returns a valid OpenAPI 3.0 document
• /docs can fetch /api/openapi as a public route
• Every route under app/api/ exports routeDoc
• Drift coverage fails if a route is added without documentation
• Middleware allowlist no longer contains the mangled path
• Generated spec passes the OpenAPI validator
• Actual list/search response validation accepts legacy source: null plus live / historical, while rejecting unknown strings and numeric source values

Focused validation

The current-head validation receipt is documented in docs/validation/openapi-event-source-20261004.md.

A source-bound selection passed 21 tests, 0 failures, 0 pending:

npm exec -- vitest run \
  lib/openapi/__tests__/event-responses.test.ts \
  lib/openapi/__tests__/openapi-spec.test.ts \
  app/api/v1/events/export/route.test.ts \
  --maxWorkers=1 --reporter=json --outputFile=after.json

That selection includes the new list/search compatibility cases, maintained OpenAPI validator/drift cases, and export schema regressions. It calls the actual handlers and obtains schemas from the actual public OpenAPI handler; database/authentication collaborators are controlled.

Formatting follow-through ran Prettier write/check successfully on the final files. The hosted workflow's overall result was not green because a later byte-for-byte emitted-JavaScript comparator treated a whitespace-only line-wrap change as significant. Independent TypeScript parsing found zero diagnostics and identical syntax trees excluding positions/trivia. No functional rerun is claimed for that whitespace-only formatting edit.

Evidence boundary

No full-suite, full application typecheck/build, live database, deployed Swagger browser, authentication, upstream CI approval, or maintainer-acceptance result is asserted by this focused continuation. The original PR, branch, and contributor are preserved.

Notes

• Hand-written routeDoc objects only; drift coverage keeps the registry honest
• Out of scope: client SDK generation