HydraCache 0.37.0

HydraCache 0.37.0

0.37.0 is a database production-hardening release. It turns database
invalidation from an after-commit best-effort pattern into explicit durable
intent, adds bounded read-after-write waiting, makes oversized DB results
visible before insertion, and gives the hot read/write paths criterion bench
targets.

Highlights

• Durable invalidation outbox primitives with stable target hashing,
  idempotency by commit position and target hash, in-memory adapter, SQLx
  SQLite/Postgres adapter, and copyable SQLite/Postgres/MySQL migrations.
• Outbox drain worker with retry backoff, dead-lettering, reset, status
  snapshots, and cumulative worker diagnostics.
• Local and best-effort read-after-write barriers with explicit timeout,
  degraded outcomes, receipts, and wait diagnostics.
• Postgres LISTEN/NOTIFY intent source over sqlx PgListener; notifications
  are latency hints only, with the durable outbox/polling path as the backstop.
• Real pre-insert max_entry_bytes rejection for encoded cache entries, plus
  an oversize_rejections counter distinct from backend evictions.
• query_cache_policy! required_dimensions = [...] static check for
  reviewable search/list key dimensions.
• ADR and compatibility guardrails for ownership, replication, consistency,
  transport, durability, and runtime dependency boundaries.
• Criterion bench targets for local cache hot path and outbox write
  amplification, with a checked-in performance budget descriptor.

Changes

• Add InvalidationIntent, InvalidationIntentBatch, CommitPosition, and
  stable SHA-256 target hashing for durable invalidation rows.
• Add property tests covering hash stability and delimiter/length-prefix
  collision resistance.
• Add the InvalidationOutbox trait and InMemoryInvalidationOutbox for tests,
  demos, and custom durable adapters.
• Add InvalidationOutboxWorker with claim, apply, mark-published,
  retry/backoff, dead-letter, reset, and diagnostics behavior.
• Add SqlxInvalidationOutbox behind sqlx-outbox, including SQLite and
  Postgres runtime paths, schema checks, transaction enqueue helpers, and
  idempotent insert behavior.
• Add copyable migrations under crates/hydracache-db/migrations/{sqlite,postgres,mysql}.
• Add PgNotifyIntentSource and PgNotifyIntent for Postgres wake-up
  notifications. The API deliberately does not apply invalidation by itself;
  workers still drain the durable outbox.
• Add ConsistencyMode, InvalidationReceipt, InvalidationWait, wait
  outcomes, and wait diagnostics for local/best-effort read-after-write flows.
• Enforce HydraCacheBuilder::max_entry_bytes before insertion. Direct put
  returns an error for oversized encoded values; loader-based get_or_load
  returns the loaded value but does not cache it.
• Add CacheStats::oversize_rejections and expose it through observability and
  sandbox diagnostics.
• Add QueryCachePolicy::required_dimensions_value,
  required_dimensions(...), and required_dimension(...).
• Extend query_cache_policy! with required_dimensions = [...]. The macro
  requires key_segments and fails compile-time when a required label is absent
  from static key-segment labels.
• Add docs/COMPAT.md and ADR skeletons for ownership, replication,
  consistency, transport, and durability.
• Add a deny.toml runtime ban for sqlparser and a release-37 docs test that
  verifies the compatibility/ADR files exist.
• Add criterion benches:
  • crates/hydracache/benches/cache_hot_path.rs
  • crates/hydracache-db/benches/outbox_write.rs
• Add benches/budget.toml as the first performance-budget contract. A
  machine comparator remains a nightly/pre-release follow-up rather than a
  per-PR gate.
• Bump the workspace crates to 0.37.0.

Verification

This release should pass:

• cargo fmt --all -- --check
• cargo check --workspace --all-targets --locked
• cargo test --workspace --all-targets --locked
• cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
• cargo test --doc --workspace --locked
• RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --locked
• cargo check -p hydracache --benches --locked
• cargo check -p hydracache-db --benches --locked
• cargo deny check bans
• cargo tree -p hydracache-db -e no-dev | Select-String sqlparser
• cargo test -p hydracache-db --features sqlx-outbox --test outbox_sqlite --locked
• cargo test -p hydracache-db --features sqlx-outbox --test outbox_postgres --locked -- --ignored
• cargo test -p hydracache-db --test outbox_barrier --locked
• cargo test -p hydracache-db --test outbox_worker --locked
• cargo test -p hydracache-db --test outbox_property --locked
• cargo test -p hydracache-db --test weigher --locked
• cargo test -p hydracache-db --test required_dimensions --locked
• cargo test -p hydracache-db --test derive_ui --locked

Optional real Postgres coverage uses HYDRACACHE_TEST_POSTGRES_URL; without it
the ignored Postgres tests skip gracefully when run with -- --ignored.