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

* cache: the sidecar seam — policy state beside entries, judged at the byte serve

The admission/serve seam RPZ's response-IP phase builds on, policy-free
by itself (docs/rpz-design.md §5.6 item 6). Three pieces:

- CacheEntry carries an atomic sidecar pointer beside its immutable
  payload, the same shape as the prefetch claim: opaque policy state a
  wired evaluator computed from the entry's own stored records. nil is
  load-bearing — unknown, never clean.
- Admission: a single evaluator wired into the Store stamps every entry
  at every door — the SetFromResponse funnel, the prefetch CAS
  replacement, and the compatibility Set (the audit found three doors
  where the design counted on the writer alone). An entry that predates
  the wiring is evaluated and stamped by the first decoded serve.
- Serve: a WireHitGate is consulted before every record-bearing byte
  serve — the wire-born exact hit, the Msg-born inline byte path, and
  the composed chase, which shows the gate one sidecar per segment in
  chain order (a whole-chain verdict on the alias would go stale when
  the target refreshed under it). A false verdict declines to the
  decoded path; composite denial classes carry no records and are not
  gated.

Wired through Setup's marker pattern (SidecarPolicyProvider ->
SidecarPolicySetter), first provider wins. Unwired, the seam is one nil
field check per hit: the existing zero-alloc hit-class pins run
unchanged, and every stamp and gate call is mutation-pinned by the seam
tests.

* review: a three-way verdict — pure judgment, restamp on the decoded serve, counting after the commit

Both findings land on the same joint and one contract change closes them:
the gate's boolean became a verdict, and accounting left it entirely.

- Judge{WireHit,WireChase} return Serve, Decode, or Restamp, and are
  pure decisions over the sidecars. Decode means policy wants the full
  message and the sidecar itself was fine; Restamp means the sidecar is
  unusable — unevaluated, or stamped under a generation the gate no
  longer accepts. The decoded serve acts on Restamp by re-evaluating the
  entry's records and CASing over the judged pointer, stale and nil
  alike, so a policy reload no longer strands live entries on the
  decoded path until eviction. The verdict is judged once per hit,
  before the byte/decoded split, internal serves included — the
  Msg-path chase reaches its segments through internal sub-queries,
  which is where a stale segment gets its restamp.
- Count{WireHit,WireChase} fire once per byte-served hit, after the
  transport accepted the bytes — past the last point a serve can still
  fall back to the decoded path (writer readiness, chain mismatch,
  build, the fallback sentinel) and be counted a second time by the
  policy writer there. A transport failure after the commit counts,
  matching the response-counts-as-written parity the serve paths
  already keep.

Every placement is pinned: stale-restamp against a nil-only CAS,
fallback-after-approval counting nothing on both the Msg-born and
wire-born paths, committed serves counting exactly once on both, and
the chase count with its segments.

* cache: build the chase sidecar slice only when a gate is wired

Moving the segment array out of the gate branch for the commit-time
count made it visible to escape analysis through the interface call, so
every ungated chase paid a heap allocation the hit-class pins forbid —
CI caught it. The slice is now made on the gated branch only and stays
in scope for the count; an ungated chase touches nothing.

* cache: the chase sidecars travel by value, and a pin holds the gated path to the ungated cost

The gated chase still allocated: the slice handed to JudgeWireChase
escaped through the interface call, so wiring the gate put a heap
allocation on every cache-contained chase hit — the zero-allocation hit
contract holds with policy live, not only without it. The chain is now a
bounded value type (SidecarChain, capacity asserted against the chase
depth at compile time) passed by value through Judge and Count, which
closes the slice-escape class in the type system rather than in review.

The new pin closes the blind spot the finding named: the allocation CI
never wires a gate, so a baseline-relative AllocsPerRun test serves the
exact and chase hits against two caches — one bare, one behind an
allocation-free Serve gate — and refuses any gated surplus. Verified to
fire: an escaping allocation planted on the gated branch reads 3.0
against a 2.0 baseline.

Author: semihalev

middleware/autowire_test.go

@@ -193,3 +193,43 @@ func TestPutChain_NilSafe(t *testing.T) {
 	Setup(&config.Config{})
 	GlobalPipeline().PutChain(nil) // nil chain must not panic either
 }
+
+// sidecarPolicyHandler implements SidecarPolicyProvider.
+type sidecarPolicyHandler struct{ n string }
+
+func (h *sidecarPolicyHandler) Name() string                            { return h.n }
+func (h *sidecarPolicyHandler) ServeDNS(ctx context.Context, ch *Chain) { ch.Next(ctx) }
+func (h *sidecarPolicyHandler) SidecarEvaluator() SidecarEvaluator {
+	return func(*dns.Msg) *Sidecar { return nil }
+}
+func (h *sidecarPolicyHandler) WireHitGate() WireHitGate { return nil }
+
+// sidecarSetterHandler implements SidecarPolicySetter.
+type sidecarSetterHandler struct {
+	n   string
+	got SidecarPolicyProvider
+}
+
+func (h *sidecarSetterHandler) Name() string                             { return h.n }
+func (h *sidecarSetterHandler) ServeDNS(ctx context.Context, ch *Chain)  { ch.Next(ctx) }
+func (h *sidecarSetterHandler) SetSidecarPolicy(p SidecarPolicyProvider) { h.got = p }
+
+// TestAutoWire_SidecarPolicy pins the seam's wiring: the provider is
+// discovered and injected into the setter before the pipeline publishes,
+// and with no provider registered the setter is never called.
+func TestAutoWire_SidecarPolicy(t *testing.T) {
+	provider := &sidecarPolicyHandler{n: "policy"}
+	setter := &sidecarSetterHandler{n: "cache"}
+	p := &Pipeline{handlers: []Handler{provider, setter}}
+	p.autoWire()
+	if setter.got != SidecarPolicyProvider(provider) {
+		t.Fatal("the sidecar policy provider was not wired into the setter")
+	}
+
+	lone := &sidecarSetterHandler{n: "cache"}
+	p2 := &Pipeline{handlers: []Handler{lone}}
+	p2.autoWire()
+	if lone.got != nil {
+		t.Fatal("a setter was called with no provider registered")
+	}
+}

middleware/cache/cache.go

@@ -121,6 +121,12 @@ type Cache struct {
 	// get a slot is a cache miss, never a client-visible error.
 	dnssecCryptoLimiter middleware.DNSSECCryptoLimiter
 
+	// wireHitGate is the serve half of the sidecar seam: consulted before
+	// any record-bearing byte serve with the sidecar(s) the reply would be
+	// built from. Wired at Setup alongside the store's evaluator; nil (no
+	// policy middleware registered) costs one field check per hit.
+	wireHitGate middleware.WireHitGate
+
 	config  CacheConfig
 	metrics *CacheMetrics
 
@@ -1324,6 +1330,12 @@ func (c *Cache) serveHitFromWire(
 		// lives inside, past the chase's own decline gates.
 		return c.serveChaseHit(ctx, ch, entry, capability, leaser, spent)
 	}
+	gate := c.wireHitGate
+	sc := entry.sidecar.Load()
+	if gate != nil && gate.JudgeWireHit(sc) != middleware.WireHitServe {
+		wireSkipPolicy.Inc()
+		return false
+	}
 	if mismatch := entry.wireChainMismatch(capability); mismatch != nil {
 		mismatch.Inc()
 		return false
@@ -1349,6 +1361,9 @@ func (c *Cache) serveHitFromWire(
 	}
 	switch err := leaser.CommitWire(body, info); {
 	case err == nil:
+		if gate != nil {
+			gate.CountWireHit(sc)
+		}
 		boundRequestToEntryLifetime(ctx, entry)
 		c.metrics.Hit()
 		wireFastServed.Inc()
@@ -1360,6 +1375,9 @@ func (c *Cache) serveHitFromWire(
 	default:
 		// Transport-level failure after commit: the bytes left the
 		// process; the response counts as written (Msg-path parity).
+		if gate != nil {
+			gate.CountWireHit(sc)
+		}
 		boundRequestToEntryLifetime(ctx, entry)
 		c.metrics.Hit()
 		ch.Cancel()
@@ -1457,6 +1475,24 @@ func (c *Cache) handleCacheHit(
 		}
 	}
 
+	// The policy verdict is judged once per hit, before the byte/decoded
+	// split, because both halves read it: the byte path serves only on
+	// WireHitServe, and the decoded fallback restamps on WireHitRestamp.
+	// It is judged for internal serves too — the verdict is a pure
+	// function of the stored state, and the Msg-path chase reaches its
+	// segments through internal sub-queries, which is where a stale
+	// segment gets its restamp.
+	policyVerdict := middleware.WireHitServe
+	var policySC *middleware.Sidecar
+	if g := c.wireHitGate; g != nil {
+		policySC = entry.sidecar.Load()
+		policyVerdict = g.JudgeWireHit(policySC)
+	} else if c.store.sidecarEvaluator != nil && entry.sidecar.Load() == nil {
+		// An evaluator without a gate still owes pre-wiring entries
+		// their stamp.
+		policyVerdict = middleware.WireHitRestamp
+	}
+
 	// Byte fast path: serve the stored wire directly. The entry-local gate
 	// runs first, then the writer chain's preflight — both allocation-free
 	// and together complete, so a request bound for the Msg path never
@@ -1470,6 +1506,9 @@ func (c *Cache) handleCacheHit(
 		if !entry.wireEligibleFor(req) {
 			return wireSkipEntry
 		}
+		if policyVerdict != middleware.WireHitServe {
+			return wireSkipPolicy
+		}
 		ww, ok := w.(middleware.WireWriter)
 		if !ok {
 			return wireSkipWriter
@@ -1487,6 +1526,9 @@ func (c *Cache) handleCacheHit(
 		}
 		switch err := ww.WriteWire(body, info); {
 		case err == nil:
+			if g := c.wireHitGate; g != nil {
+				g.CountWireHit(policySC)
+			}
 			// The answer is out, so bind the request tree to this entry's
 			// lifetime. The byte path is normally reached only by external
 			// clients, whose responses nothing derives from — but Queryer is
@@ -1510,6 +1552,9 @@ func (c *Cache) handleCacheHit(
 			// still gets this entry's answer: it binds like any other
 			// terminal outcome. Only a fallback stays unbound, because
 			// there the message path binds instead.
+			if g := c.wireHitGate; g != nil {
+				g.CountWireHit(policySC)
+			}
 			boundRequestToEntryLifetime(ctx, entry)
 			ch.Cancel()
 			served = true
@@ -1529,6 +1574,21 @@ func (c *Cache) handleCacheHit(
 		return false
 	}
 
+	// The decoded serve is where an unusable sidecar gets replaced: the
+	// gate judged Restamp — unevaluated, or stamped under a generation it
+	// no longer accepts — and this message, TTL-adjusted but
+	// record-identical to the stored truth, before the chase below
+	// appends other entries' records, is exactly what the admission
+	// evaluator would have seen. The CAS is against the judged pointer,
+	// stale or nil alike, so the entry rejoins the byte path instead of
+	// decoding until eviction; losing the CAS means someone else already
+	// restamped the same records.
+	if policyVerdict == middleware.WireHitRestamp {
+		if ev := c.store.sidecarEvaluator; ev != nil {
+			entry.CompareAndStampSidecar(policySC, ev(msg))
+		}
+	}
+
 	// The message materialized, so the entry was live: bind the request tree
 	// to its lifetime before the chase below can derive anything from it.
 	boundRequestToEntryLifetime(ctx, entry)
@@ -1649,10 +1709,23 @@ func (c *Cache) Set(key uint64, msg *dns.Msg) {
 	if ttl > 0 {
 		entry.origTTL = uint32(ttl.Seconds())
 	}
+	c.store.stampSidecar(entry, filtered)
 
 	c.store.SetEntryWithKey(key, entry, mt)
 }
 
+// SetSidecarPolicy wires both halves of the sidecar seam
+// (middleware.SidecarPolicySetter, injected by Setup before the pipeline
+// publishes): the evaluator stamps entries at every admission door, the
+// gate judges record-bearing byte serves.
+func (c *Cache) SetSidecarPolicy(p middleware.SidecarPolicyProvider) {
+	if p == nil {
+		return
+	}
+	c.store.SetSidecarEvaluator(p.SidecarEvaluator())
+	c.wireHitGate = p.WireHitGate()
+}
+
 // (*Cache).Stats stats returns cache statistics.
 func (c *Cache) Stats() map[string]any {
 	hits, misses, evictions, prefetches := c.metrics.Stats()

middleware/cache/entry_wire_chase.go

@@ -31,6 +31,10 @@ import (
 // chase re-resolves and re-admits it — self-healing at the cost of one
 // decoded serve.
 
+// The chase depth must fit the sidecar chain the gate receives; a
+// negative constant here fails the build.
+const _ = uint(middleware.SidecarChainCap - maxWireChaseHops)
+
 const (
 	// maxWireChaseHops mirrors the Msg-path chase depth.
 	maxWireChaseHops = 10
@@ -73,6 +77,25 @@ func (c *Cache) serveChaseHit(
 		return false
 	}
 
+	// The reply would compose every segment's records, so the gate sees
+	// every segment's sidecar, in chain order — the per-segment principle:
+	// a whole-chain verdict on the alias would go stale the moment a
+	// target entry refreshed under it. The chain travels by value: a
+	// slice here escapes through the interface call and puts a heap
+	// allocation on every gated chase hit, which the zero-allocation hit
+	// contract forbids with the gate wired no less than without it.
+	gate := c.wireHitGate
+	var chain middleware.SidecarChain
+	if gate != nil {
+		for i := range n {
+			chain.Append(segs[i].entry.sidecar.Load())
+		}
+		if gate.JudgeWireChase(chain) != middleware.WireHitServe {
+			wireSkipPolicy.Inc()
+			return false
+		}
+	}
+
 	size := wire.HeaderLen + (ch.Request.WireQuestionEnd() - wire.HeaderLen)
 	for i := range n {
 		size += len(segs[i].body) + segs[i].anCount*wireChaseHeadroom
@@ -106,6 +129,9 @@ func (c *Cache) serveChaseHit(
 
 	switch err := leaser.CommitWire(body, info); {
 	case err == nil:
+		if gate != nil {
+			gate.CountWireChase(chain)
+		}
 		// The reply contains every segment's records, so the request
 		// inherits every segment's cache-lifetime bound — the wire twin of
 		// the Msg chase's lineage inheritance.
@@ -120,6 +146,9 @@ func (c *Cache) serveChaseHit(
 		wireFastFallback.Inc()
 		return false
 	default:
+		if gate != nil {
+			gate.CountWireChase(chain)
+		}
 		for i := range n {
 			boundRequestToEntryLifetime(ctx, segs[i].entry)
 		}

middleware/cache/prometheus.go

@@ -61,6 +61,7 @@ var (
 	wireSkipEntry     = wireFastPath.Register("skip_entry")
 	wireSkipWriter    = wireFastPath.Register("skip_writer")
 	wireSkipDNSSEC    = wireFastPath.Register("skip_dnssec")
+	wireSkipPolicy    = wireFastPath.Register("skip_policy")
 	wireSkipSize      = wireFastPath.Register("skip_size")
 	wireSkipBuild     = wireFastPath.Register("skip_build")
 	wireSkipChase     = wireFastPath.Register("skip_chase")