mbproxy: add opt-in response cache (Phase 11)

Layers a per-PLC, per-tag response cache on top of Phase 10's coalescing.
Cache is OFF by default per tag (CacheTtlMs = 0); a fresh deployment with no
TTL config behaves identically to Phase 10. Operators opt tags in by setting
CacheTtlMs > 0 on a BcdTagOptions entry (or DefaultCacheTtlMs > 0 on a
PlcOptions entry), explicitly acknowledging the staleness window.

Cache lookup order: cache -> coalesce -> backend. A cache hit short-circuits
both Phase 10's coalescing path and Phase 9's backend send. Cache stores
POST-rewriter PDU bytes so hits never re-invoke the BCD rewriter. FC06/FC16
write responses invalidate every cached entry whose address range overlaps
the write (half-open interval math).

New types (Mbproxy.Proxy.Cache, all internal):
- CacheKey (record-struct, same shape as CoalescingKey but kept SEPARATE so
  the two phases evolve independently).
- CacheEntry, ResponseCache (IDisposable; LRU + PeriodicTimer eviction
  loop), CacheInvalidator (pure overlap matcher), CacheLogEvents (stable
  mbproxy.cache.* names).

Multi-tag range TTL = min(TTLs); any tag with TTL = 0 in the range disables
caching for the whole read (conservative-by-design).

Options surface:
- BcdTagOptions.CacheTtlMs (nullable int; null = fall through to PLC default)
- PlcOptions.DefaultCacheTtlMs
- MbproxyOptions.Cache.{AllowLongTtl, MaxEntriesPerPlc, EvictionIntervalMs}
- TTL > 60_000 ms requires Cache.AllowLongTtl = true (reload validation).

Admin counters (Tier 1.8 + Tier 2 cache-memory KPIs from docs/kpi.md):
- CacheHitCount, CacheMissCount, CacheInvalidations on ProxyCounters.
- CacheEntryCount, CacheBytes via a new ICacheStatsProvider snapshot path.
- /status.json and the HTML page surface a new Cache cell per PLC row.

Hot-reload: any tag-list change to a PLC reseats the per-PLC context with a
fresh cache; the old cache is disposed inside ReplaceContextAsync. Per-tag
flush granularity is intentionally not implemented in v1.

PLCs with no cache-eligible tags (every resolved tag has CacheTtlMs = 0)
get Cache = null on the context and skip the eviction timer entirely, so
the no-cache path is byte-identical to Phase 10.

Tests (32 new unit + 5 new E2E = 37 new; suite now 314 unit + 48 E2E):
- CacheKeyTests, CacheEntryTests (records + boundary semantics).
- CacheInvalidatorTests: full overlap, both partials, adjacent-not-
  overlapping, disjoint, different unit ID + auxiliary FC-filter / zero-qty.
- ResponseCacheTests: round-trip, lazy expiry, range invalidation,
  unit-id filter, LRU bound, LRU access tracking, concurrent get/set,
  dispose, clear, approximate-bytes accounting.
- ResponseCacheMultiplexerTests (stub-backend): hit short-circuits
  coalescing, BCD-decoded bytes are cached not raw, FC06 invalidates
  overlapping, non-overlapping write does not invalidate, multi-tag
  TTL=min rule, regression-cache-disabled-by-default-is-Phase-10, hit
  works even when backend unreachable.
- ResponseCacheE2ETests (pymodbus DL205 sim, sequential reads):
  * Headline: 10 reads with TTL=1000 ms -> 9 hits, 1 miss, 1 backend trip.
  * TTL expiry path with sleep > TTL.
  * Write invalidation through the proxy on a scratch register.
  * BCD-decoded bytes are cached, not raw BCD nibbles.
  * Regression: Cache disabled by default -> behaviour byte-identical to
    Phase 10.

Pre-existing flake hardened: BackendDisconnect_CascadesToAllUpstreams now
polls briefly for the cascade counter to absorb the inherent scheduling
gap between "upstream EOF observed" and "counter incremented inside
TearDownBackendAsync." Counter semantics unchanged.

Phase doc updated with implementation clarifications discovered during
this work (CacheKey kept separate from CoalescingKey, LastUsedTick is
long, FC06/FC16 startAddr/qty parsing extension, cache-pre-connect
short-circuit, write-invalidation only on successful responses).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mbproxy/src/Mbproxy/Proxy/ProxyWorker.cs

@@ -1,6 +1,7 @@
 using Mbproxy.Bcd;
 using Mbproxy.Configuration;
 using Mbproxy.Options;
+using Mbproxy.Proxy.Cache;
 using Mbproxy.Proxy.Multiplexing;
 using Mbproxy.Proxy.Supervision;
 using Microsoft.Extensions.Options;
@@ -70,7 +71,7 @@ internal sealed partial class ProxyWorker : BackgroundService
 
         foreach (var plc in opts.Plcs)
         {
-            var result = BcdTagMapBuilder.Build(opts.BcdTags, plc.BcdTags);
+            var result = BcdTagMapBuilder.Build(opts.BcdTags, plc.BcdTags, plc.DefaultCacheTtlMs);
 
             foreach (var warn in result.Warnings)
                 _logger.LogWarning("[{Plc}] BCD tag map warning: {Message}", plc.Name, warn.Message);
@@ -85,12 +86,22 @@ internal sealed partial class ProxyWorker : BackgroundService
                 continue;
             }
 
+            // Phase 11 — construct a per-PLC response cache only when at least one
+            // resolved tag opts in (CacheTtlMs > 0). Skipping cache construction for a
+            // PLC with no cacheable tags keeps the no-cache path free of the eviction
+            // timer and the per-call resolution cost, preserving "default behaviour =
+            // Phase 10 unchanged" when no operator has opted any tag in.
+            var cache = HasAnyCacheableTag(result.Map)
+                ? new ResponseCache(opts.Cache.MaxEntriesPerPlc, opts.Cache.EvictionIntervalMs)
+                : null;
+
             plcContexts[plc.Name] = new PerPlcContext
             {
                 PlcName  = plc.Name,
                 TagMap   = result.Map,
                 Counters = new ProxyCounters(),
                 Logger   = _loggerFactory.CreateLogger($"Mbproxy.Proxy.BcdRewriter.{plc.Name}"),
+                Cache    = cache,
             };
         }
 
@@ -213,6 +224,20 @@ internal sealed partial class ProxyWorker : BackgroundService
 
     // ── Logging ───────────────────────────────────────────────────────────────────────────
 
+    /// <summary>
+    /// Phase 11 — returns <c>true</c> when at least one BcdTag in the resolved map has a
+    /// positive <see cref="BcdTag.CacheTtlMs"/>. A PLC with no cacheable tags skips the
+    /// <see cref="Mbproxy.Proxy.Cache.ResponseCache"/> entirely (no eviction timer, no
+    /// per-call cache resolution cost), so the default-OFF deployment is byte-identical
+    /// to a Phase-10 deployment.
+    /// </summary>
+    private static bool HasAnyCacheableTag(BcdTagMap map)
+    {
+        foreach (var t in map.All)
+            if (t.CacheTtlMs > 0) return true;
+        return false;
+    }
+
     [LoggerMessage(EventId = 1, EventName = "mbproxy.startup.ready",
         Level = LogLevel.Information,
         Message = "mbproxy service ready — ListenersBound={ListenersBound} PlcsConfigured={PlcsConfigured}")]