[stack 6/8] feat(trace): cover compact and response-cache hits

[OnlineChef (ChefGroep)]

Stacked re-landing of #301 (feat/trace-compact-cache). Position 6/8; base: stack/20261005-05-trace-reader. Merge bottom-up; each layer is a real merge of the original PR head, so the diff shows only that PR plus any conflict resolution (noted in the merge commit message).

Stack

#	Layer	Original
1/8	#304 feat: make prompt cache behavior measurable	#296
2/8	#305 feat: expand providers and make native model discovery account-aware	#297
3/8	#306 feat(gui): start auth-inspired OpenCodex redesign	#299
4/8	#307 feat(trace): opt-in trace store linked to usage.jsonl	#298
5/8	#308 feat(trace): add safe local trace reader	#300
6/8	#309 feat(trace): cover compact and response-cache hits	#301
7/8	#310 feat(trace): cover Responses WebSocket turns	#302
8/8	#311 feat(trace): cover live call-create HTTP	#303

---

Original description:

Summary

Extends the opt-in trace store from #298 to the two remaining HTTP/cache paths that materially affect cache debugging:

• trace /v1/responses/compact
• trace proxy response-cache HITs without duplicating cached response bodies

This PR is intentionally stacked on feat/trace-store / #298. It does not add WebSocket/live/realtime tracing, a remote reader, Redis, or a new persistence format.

Cache-hit trace model

A response-cache entry now keeps the request id that originally populated it. On a later HIT the new request trace records:

• cacheHit: true
• cacheSourceTraceId when known
• response byte count
• response hash

The cached response body is not copied again into trace.sqlite. In redacted / full mode only the hit request's own inbound body may be stored under its new trace id.

The persisted cache source id is allowlisted before it can enter usage/request-log metadata.

Compact coverage

/v1/responses/compact now uses the same trace lifecycle as the other HTTP data-plane routes:

beginTrace -> runWithTrace -> response observation -> addFinalRequestLog

The compact implementation already has a 32 MiB hard response-buffer bound; the trace store still applies its own lower configurable per-body cap.

Verification

Exact clean-tree head 84f105ba56240f31ca57f8e348bcc7290c6cc7bd:

• focused trace/cache/request-log suite: 105 pass, 0 fail
• real server response-cache e2e: 4 pass, 0 fail
• full repository suite: 7030 pass, 11 explicit skips, 0 fail across 523 files
• 34,915 assertions
• bun x tsc --noEmit ✅
• bun run privacy:scan ✅
• git diff --check ✅
• clean-tree client-artifact build/guard tests ✅

The earlier dirty-tree full-suite attempt hit only the repository's intentional client-artifact clean-tree guard before this lane was committed. The clean exact-head rerun passed that guard and the complete suite.

Remaining boundary

WebSocket/live/realtime traffic is intentionally not included here. That lifecycle needs per-session/frame bounds and separate finalization semantics rather than being bolted onto the HTTP trace path.

Dependency

Stacked on #298. Merge/rebase only after the trace-store parent lands.

Summary by CodeRabbit

• New Features
  • Request tracing now covers compact Responses requests and proxy response-cache hits across Responses, Claude Messages, and Chat Completions.
  • Cache-hit trace metadata includes a response hash, byte count, and—when available—a link to the request that populated the cache, without duplicating the cached response body.
• Documentation
  • Updated request-trace coverage details, including traffic types that remain unsupported.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}