[Backend] Cache invalidation: replace JSON.stringify equality with stable hash comparison

[Baskarayelu]

Description

invalidateCache in src/cache/invalidation.ts detects stale reads using JSON.stringify(staleCheck) !== JSON.stringify(freshData). This is fragile: key ordering, undefined vs missing keys, and BigInt/Date serialization produce false positive or false negative stale detections, and the default verifyFn therefore mis-reports recordStaleCacheRead. We should compare via a stable, type-aware hash (reuse src/utils/hash.ts) so stale-read metrics are trustworthy.

Requirements and context

• Replace JSON.stringify comparison in src/cache/invalidation.ts with a canonical hash from src/utils/hash.ts.
• Handle BigInt, Date, and key-order normalization in the canonicalizer.
• Keep the custom verifyFn override path working.
• Ensure recordStaleCacheRead only fires on genuine divergence.

Suggested execution

Create branch feature/stable-cache-stale-detection.

• Add a canonical serializer to src/utils/hash.ts.
• Modify src/cache/invalidation.ts.
• Add src/cache/invalidation.test.ts for ordering/BigInt/Date cases.
• Update docs/CACHE_INVALIDATION.md.

Test and commit

Run npm run test. Edge cases: reordered keys equal, BigInt fields, nested objects, null vs undefined. Security: no sensitive data logged in stale warnings.

Example commit message

feat: use stable canonical hash for cache stale-read detection

Guidelines

• Minimum 95% test coverage
• Clear documentation in docs/CACHE_INVALIDATION.md
• Timeframe: 96 hours

[paulinaapeh8]

@paulinaapeh8 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

I want to work on this issue because it focuses on improving the reliability and correctness of cache validation logic, which is critical for maintaining data consistency in backend systems. Using JSON.stringify for stale-read detection can introduce subtle bugs around key ordering, serialization differences, and unsupported data types like BigInt, so replacing it with a stable canonical hashing approach is an important improvement.

I have experience working with TypeScript backend systems, validation logic, utility functions, and automated testing. I’ve also worked with object comparison patterns, API caching behavior, and edge-case handling in JavaScript/Node.js applications, which gives me a strong foundation for implementing and testing deterministic hashing and comparison logic.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @paulinaapeh8 to this issue.

[drips-wave]

Congratulations, @paulinaapeh8! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @paulinaapeh8: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊