perf: cache slow list APIs for lower TTFB

[thowar2]

Why

The frontend TTFB deployment is live and warm Netlify/ISR traffic is already fast, but production measurements isolate query-bearing archive pages as the remaining bottleneck. Representative direct API TTFB was about 0.6s for block/transaction lists and 3.4–3.6s for shielded history; the historical shielded archive tail had roughly 1.25s median HTML TTFB. Many page-number URLs collapse to the same cursor/filter API identity, so a shared list-response cache is the highest-leverage next step.

What changed

• Add an opt-in, network-namespaced Redis cache for block, transaction, shielded-flow, and rich-list responses.
• Use 15s freshness for latest lists, 300s for cursor/archive lists, and 60s for the rich list, with bounded last-known-good stale retention.
• Coalesce cold misses in-process, refresh stale entries under a short distributed lock, retain stale data on refresh failure, and fail open to PostgreSQL on Redis errors or a 50ms Redis deadline.
• Bound every route family's key cardinality and normalize/validate cache identities so ignored or malformed query fields cannot create duplicate entries.
• Emit X-CipherScan-Cache: HIT|MISS|STALE plus Server-Timing on covered API responses and expose those headers through CORS.
• Add unit, route-contract, and real-Redis integration coverage; CI now runs the backend suite against Redis 7 using the committed lockfile.
• Document the separate backend rollout, public API verification, rollback, and subsequent HTML/Ahrefs measurement order.

Safety and rollout

The feature defaults off. Production enables it with API_LIST_CACHE_ENABLED=1 in server/api/.env only after confirming Redis is private and persistent. Setting the flag back to 0 and restarting the API is the rollback. This PR does not deploy or alter the frontend cache policy.

After the backend deploy, verify paired public API requests show MISS then HIT or STALE with identical JSON, rerun the archive-aware HTML TTFB probe, then start a fresh full-population Ahrefs crawl. Next does not forward the upstream API cache header, so API and HTML evidence remain separate.

Validation

• API suite: 24 passed; the gated real-Redis case is the only default skip.
• Real Redis 8.8 release gate: 1 passed, 0 skipped, including TTL, stale refresh, distributed locking, bounded eviction, and fail-open behavior.
• Route-contract tests prove cache hits preserve JSON and skip PostgreSQL for all four covered families.
• Backend syntax checks and git diff --check passed.
• Existing slow-page tests: 9/9.
• Sitemap/security tests: 19/19.
• TTFB probe tests: 12/12.
• ISR warm-up tests: 17/17.
• Lint and TypeScript checks passed.
• Offline production build passed with the CI network/fallback environment; route-cache build checks: 4/4.

[netlify]

✅ Deploy Preview for cipherscan ready!

Name	Link
🔨 Latest commit	c997d9c
🔍 Latest deploy log	https://app.netlify.com/projects/cipherscan/deploys/6a62441ee5883b0008cfefc1
😎 Deploy Preview	https://deploy-preview-52--cipherscan.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for cipherscan-crosslink ready!

Name	Link
🔨 Latest commit	c997d9c
🔍 Latest deploy log	https://app.netlify.com/projects/cipherscan-crosslink/deploys/6a62441e5dcd260008e2b5e9
😎 Deploy Preview	https://deploy-preview-52--cipherscan-crosslink.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[thowar2]

@Kenbak this is a database performance optimization for page loading. It may be too heavy for deployment at this time since its touching database logic.