Shared cache backend (Postgres) for multi-server consistency

[megamattron]

Summary

Adds an opt-in shared cache backend so Cache is consistent across a horizontally-scaled deploy, without changing the per-process default. One line opts in:

app.cache(CacheBackend.postgres(dbFactory));   // shared, durable, cross-server-consistent
// default stays in-process if you never call this

The in-process default is unchanged and stays first-class (live objects, zero serialization). The choice is per use case, not per deployment — you can run both (in-process for hot read-through pages, a shared Cache for counters/invalidation that must be consistent).

Design + rationale: docs/2026-06-04-brace-shared-cache.md.

What's included (by phase)

• Phase 1 — SPI + Postgres backend. Extract a CacheBackend SPI; Cache becomes a facade owning stats, TTL parsing, and Jackson value serialization. InMemoryBackend (default, live objects) + PostgresBackend (bytes via JDBC). Atomic incr (INSERT … ON CONFLICT … RETURNING), GIN-backed clearTag over TEXT[], read-time expiry. Postgres-only migration_pg/V8 (H2 never sees it).
• Phase 2 — Rendered page caching. CachedHandler caches a serializable RenderedResponse snapshot, so a page rendered on one server is replayed by any other. No BraceHandler surgery needed (View renders eagerly).
• Phase 3 — Ops + docs. shared flag on /ops/cache + /ops/status, scope: instance|fleet on clear, dashboard [clear fleet] label. BRACE-AGENTS.md + README.md updated.

Backends at a glance

Use	Backend
Single server	in-process (default)
Read-through of expensive compute, per-server copies OK	in-process
Counters / rate limits / invalidation across servers	shared
Cached pages that must match across the fleet	shared

Shared-backend constraints (the in-process default has none): values must be Jackson-round-trippable and non-null; getOrSet single-flight is per-server, not global. The near-cache (L1/L2) tier is deferred by design — see the doc.

Code review

Ran a high-effort multi-agent review on the branch before this PR and fixed all 10 findings (commit 9c0b177). Notable real bugs caught:

• Value/counter key collision on Postgres → split into a separate brace_cache_counters table (parity with the in-memory two-map design).
• deserialize crash on corrupt/truncated bytes → bounds-checked; unreadable entries (incl. a class removed across a rolling deploy) are treated as a cache miss, not a 500.
• Reuse Json.mapper() (consistent date handling); vary page key on HX-Request; stop the sweep thread on Brace.stop(); reject null values; size() cached ~5s; PostgresBackend uses DatabaseFactory.withSession.

Behavior / compatibility notes

• Additive, no breaking changes. Existing apps that never call app.cache(backend) are unaffected.
• Cache values must now be non-null on both backends (set(key, null) throws) — null is reserved for "missing". This was previously inconsistent (a permanent miss).
• cache.wrap(...) hits now return a materialized (raw-bytes) Result; the response bytes are identical, but custom middleware reading result.body() should read the response bytes instead.
• Page caching now varies on HX-Request.

Migration guide

docs/migrations/brace-0.1.6-to-0.1.7.md documents the optional opt-in. Separately, this branch adds a CLAUDE.md rule requiring a migration guide per version step and a docs/migrations/README.md index that flags a pre-existing gap (no guides for 0.1.1→0.1.6) — tracked for a separate backfill, not addressed here.

Tests

• 601 unit tests (H2, Docker-free) — includes serialization, corruption→miss, null-rejection, htmx-key separation, value/counter independence.
• 7 Postgres IT tests (Testcontainers, mvn verify) — same CacheBackendContract against real Postgres, plus atomic-incr-under-concurrency, GIN clearTag, read-time expiry, cross-instance page caching through BYTEA, and value/counter no-collision.

All green.