Introduce centralized zod request validation middleware with a consistent error envelope

[ekwe7]

closes #474

Overview
This PR introduces a standardized, type-safe validation layer using Zod across the Express routing framework. Previously, route-level input validation was handled in an ad-hoc manner, leading to inconsistent error shapes, unchecked type assumptions inside handlers, and edge-case security risks (e.g., type-confusion, payload injection).

By implementing a unified validate() chokepoint middleware, we guarantee that all incoming payloads, query variables, and path parameters match strict schemas before any downstream handler business logic executes.

What's Changed

• Core Middleware (src/middleware/validate.ts): Built an Express validation middleware accepting Zod schemas for body, query, and params. It intercepts invalid inputs early, formatting field-level validation errors into a stable, system-wide 400 response envelope.
• Strict Parsing Downstream: Replaces raw unvalidated payloads with parsed, fully-typed data objects attached directly to the Express req pipeline to eliminate implicit any patterns.
• Route Migration: Migrated the GET /api/reports/:jobId schema framework and dependencies (reportJobParamsSchema, ReportJobParams) out of isolated blocks and integrated them through a unified schema barrel export system.
• Error Taxonomy Integration: Standardized on a unified error_code structure, converting Zod nested validation issues using an internal custom formatting layer (formatZodErrors).

Test Coverage & Verification

• Re-tested core middleware edge cases including:
  • Unknown/extra field stripping vs strict rejection.
  • Parameter coercion rules (handling stringified numeric route params like jobId).
  • Edge cases targeting custom error overrides (including stellar and address structural format rules).
• Test Metrics Achieved:
  • Middleware Branches: 93% ──> 97.67% ✅
  • Middleware Statements: 96.49% ──> 98.24% ✅

Checklist

• Middleware handles body, query, and params schemas dynamically
• Uniform 400 envelope response structure verified
• Initial batch of target routes successfully migrated
• Middleware unit and integration test coverage meets or exceeds ≥ 95% target
• docs/request-validation.md architecture guide added/updated
• Codebase passes npm run lint and npm run build locally

[Baskarayelu]

centralizing request validation behind one zod middleware with a consistent error envelope is exactly the chokepoint we wanted - removes a whole class of ad-hoc validation drift. merging 👍