test(backend): add error-envelope coverage matrix and fix e2e suite (…

[Lansa-18]

Summary

Closes #286.

Adds a coverage matrix meta-test that guarantees every 4xx/5xx error status documented in the OpenAPI spec has a corresponding error-envelope test — so a new documented error status can never silently ship without a test proving it returns the global envelope (code, message, details?, traceId?, timestamp, path) produced by AllExceptionsFilter.

How it works

• app/backend/test/error-envelope-coverage.spec.ts (new) — a static-analysis test with no app bootstrap, DB, or Redis dependency, so it runs under the unit jest config on every CI push/PR:
  1. Reads the committed spec app/frontend/openapi.json (source of truth — controllers use shorthand decorators like @ApiBadRequestResponse, and CI's spec:export drift check keeps the file fresh).
  2. Collects the distinct 4xx/5xx statuses across all endpoints (currently 400, 401, 403, 404, 500, 503).
  3. Scans test/error-handling.e2e-spec.ts for literal .expect(NNN) assertions (comments stripped, so status codes mentioned in docs don't count as tested).
  4. Fails loudly listing each uncovered status and sample endpoints that document it.
• Granularity is distinct status codes, not per-endpoint pairs, since one global filter produces the envelope — one test per status proves the shape for every endpoint returning it.

Gap closed: 503

503 was documented (health endpoints) but had no envelope test. Rather than allowlisting it, this PR adds a real one: new GET /test-error/service-unavailable endpoint throwing ServiceUnavailableException (with @ApiServiceUnavailableResponse), a matching e2e case, and the regenerated openapi.json (+15 lines, only the new path).

Pre-existing e2e suite repairs (required)

error-handling.e2e-spec.ts could not run at all on main, which would have made the coverage guarantee hollow. Three minimal fixes:

1. test/jest-e2e.json — added the missing ^cache/(.*)$ module mapping (aid.module.ts imports cache/redis.service, resolved by tsconfig baseUrl but not by jest).
2. Auth — the global ApiKeyGuard 401'd every request before reaching the controller; the suite now authenticates via the guard's env-key fallback (process.env.API_KEY + x-api-key header), the same pattern as verification-lifecycle.e2e-spec.ts.
3. Route drift — the test requested /test-error/generic-error but the controller route has always been generic; the test was fixed to match the controller (the published API surface), not the other way around.

Housekeeping

• pnpm-lock.yaml: backfilled missing @sendgrid/* entries from Implement email receipt delivery via SendGrid #146 (dependency was added to package.json without a lockfile update).

Testing

# Coverage matrix (runs in CI via `npm test`)
cd app/backend
npm test -- --testPathPatterns=test/error-envelope-coverage
# → 1 passed

# Negative check — temporarily swapped the 503 assertion to .expect(999):
# → FAIL: "Documented error status(es) with no envelope test …
#          - 503 — documented on: GET /api/v1/health/ready, GET /api/v1/health/onchain"
# (restored afterwards)

# Full envelope e2e suite (local Redis + sqlite dev DB)
npm run test:e2e -- --testPathPatterns=error-handling
# → 11 passed, 11 total

# CI steps replicated locally against latest main (cf8bea4):
pnpm --filter backend run lint    # 0 errors
pnpm --filter backend run test    # 438 passed; only test/idempotency.spec.ts fails
                                  # locally (needs live Postgres) — pre-existing,
                                  # fails identically on clean main, green in CI
pnpm --filter backend run build   # passes
npm run spec:export               # regenerating again produces zero drift

Screenshots

N/A — backend test infrastructure only.

Checklist

- [x] Tests added or updated for new/changed behavior
- [x] Existing tests pass (sole local failure is the pre-existing Postgres-dependent idempotency.spec.ts, green in CI)
- [x] No secrets, keys, or seed phrases committed (the e2e API key is a dummy test value consumed via the guard's env fallback)
- [x] Follows the coding conventions in the relevant service README
- [x] PR is focused on a single concern (error-envelope test coverage; the e2e suite repairs were prerequisites for the coverage guarantee to be meaningful)

[Lansa-18]

@kilodesodiq-arch Kindly review the changes. Would be expecting your feedback.

[kilodesodiq-arch]

Awesome work on this! Thanks for the contribution 🚀 Merging now.