cache: the Store admission/serve sidecar seam (RPZ phase 4 prerequisite)

[semihalev]

The seam docs/rpz-design.md §5.6 requires before the response-IP phase: policy state carried beside cache entries, stamped at admission, judged at the byte serve. This PR is deliberately policy-free — no RPZ logic, no behavior change while unwired — so the seam's design can be reviewed on its own, as the design doc prescribes.

Design

The sidecar. CacheEntry gains one atomic pointer beside its immutable payload (the same shape as the existing prefetch claim — a mutable atomic the entry carries without being copied). The cache never reads the value. nil is load-bearing: an absent sidecar means unknown, never clean — because a fourth admission door may exist someday, and the audit indeed found one the design's callsite list didn't (below).

Admission. One evaluator, wired into the Store, stamps every entry with the result of evaluating that entry's own stored records — the truth, post-filter, never the client's copy. The design named three doors (writer, resolver's direct store, prefetch replacement); reading the code found they funnel through three construction sites, and all three stamp:

• setFromResponseWithKey — the writer's SetFromResponseWithKey/Scoped and the resolver's SetFromResponseWithCut funnel here;
• ReplaceIfCurrent — the prefetch CAS replacement;
• Cache.Set → SetEntryWithKey — the compatibility door for prefetch write-backs and plugin callers, which the design's list did not carry.

An entry admitted before the seam was wired carries nil; the first decoded serve evaluates the message it already built and CAS-stamps it, so such an entry pays the Msg path once, not forever.

Serve. A WireHitGate is consulted before every record-bearing byte serve, with the sidecar(s) the reply would be built from:

• the wire-born exact hit (serveHitFromWire),
• the Msg-born inline byte path (handleCacheHit),
• the composed chase (serveChaseHit) — one sidecar per segment, in chain order: a whole-chain verdict on the alias entry would go stale the moment the target refreshed under it (§5.6 item 4).

A false verdict declines to the decoded path, where the policy middleware's own response writer sees a full message. Composite denial classes (subtree cuts, failure state) carry no stored records and are never gated. The gate signature is entry-only by design: per-query policy state stays in the policy middleware, which steers a query off the byte path entirely by withholding its writer's wire capability — so the gate never needs the request, and a verdict is a pure function of the stored state.

Wiring. Setup's marker pattern: SidecarPolicyProvider (rpz, in the next PR) → SidecarPolicySetter (cache), first provider wins with a warning, injected before the pipeline publishes so the atomic store is the happens-before barrier — same discipline as the existing Store/Queryer wiring.

Cost while unwired

One nil field check per hit and 8 bytes per entry. The existing zero-alloc hit-class pins (TestServeRawWireHitAllocatesNothing, the acquire pins) run unchanged and green.

Verification

• Seam tests: every door stamps (each pinned separately); unwired leaves entries unstamped; a declining gate is consulted with the entry's own sidecar and the decoded path answers correctly; an approving gate genuinely serves bytes (fast-served counter); the chase gate sees every segment in order; the decoded serve stamps an unevaluated entry; CAS restamp semantics; autoWire injects the provider (and never calls a setter without one).
• 8/8 guard mutations killed, one per stamp/gate/wiring point.
• Full suite, -race on middleware + cache, lint clean.

Phase 4 proper (rpz-ip triggers, the match-list sidecar values, serve-time merge, winner-bounded counting) follows in its own PR on top of this seam.

[codecov]

Codecov Report

❌ Patch coverage is 81.15942% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.88%. Comparing base (5fa514e) to head (4a78fe1).

Files with missing lines	Patch %	Lines
middleware/cache/cache.go	80.00%	6 Missing ⚠️
middleware/cache/entry_wire_chase.go	66.66%	4 Missing ⚠️
middleware/pipeline.go	83.33%	2 Missing ⚠️
middleware/sidecar.go	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #601      +/-   ##
==========================================
- Coverage   86.89%   86.88%   -0.02%     
==========================================
  Files         179      180       +1     
  Lines       22732    22801      +69     
==========================================
+ Hits        19754    19810      +56     
- Misses       2968     2981      +13     
  Partials       10       10              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.