mercadodevida/work/artifacts/F-027/implementer.md

Implementer — F-027 Caching layer with explicit contracts

Summary

Implemented cache module with read-through pattern, explicit contracts (key pattern, TTL, invalidation, source of truth) and metrics. In-memory adapter serves v1; Redis adapter can be added later without changing callers.

Files changed

• project/src/modules/cache/**
• project/src/app/build-app.ts

Acceptance evidence

• AC1 contracts documented: cache-service.test.ts verifies that the registered contract carries key pattern, TTL, source and invalidation fields; route exposes /cache/contracts.
• AC2 invalidation: CacheService.invalidateByName increments invalidations counter.
• AC3 Redis-down fallback: service swallows set errors after loader returns and increments miss counter.
• AC4 metrics: /cache/metrics returns hits/misses/invalidations/hitRatio.

Commands run

• cd project && npm run lint/typecheck/build/test passed
• cd project && TEST_DATABASE_URL='postgres://mdv:mdv_dev_only@localhost:5432/mdv_test' npm run test:integration -- migrations.itest passed; 14 files, 53 tests
• ./scripts/verify.sh passed

Notes

• No new runtime dependency.
• invalidateByName uses fragment-based invalidation on the in-memory adapter; a real Redis adapter can use SCAN.