refactor(api): split OpenAPI by module and enforce route-operation-security parity #695

Parent epic: #679
CI orchestration: #685

Evidence

The public OpenAPI contract is a single roughly 13k-line document. The current checker covers basic validity but does not prove every route method, operation ID, request schema, and security requirement matches implementation.

Objective

Maintain module-owned OpenAPI sources with one deterministic bundled public artifact and bidirectional parity checks.

Scope

• Split source contracts by module/tag without changing the published API path/version.
• Bundle deterministically for consumers and release artifacts.
• Compare route files and HTTP methods with OpenAPI operations.
• Validate unique operation IDs, standard error/correlation schema, auth/security metadata, and path parameters.
• Define handling for internal/non-public routes and conditional features.

Acceptance criteria

• Bundled contract is semantically compatible unless an intentional changeset says otherwise.
• Missing/extra route method, missing security, or duplicate operation ID fails.
• Module ownership is clear.
• Bundle and lint commands run locally/offline.
• API spec tests and docs are updated.