feat(cache): canonical row cache keys + alias entries + table generation tokens

[alexstandiford]

Problem

The datastore trait cached the same row under different keys depending on how it was asked for:

1. getModels() read-back keyed by table identity (from findIds() SQL, table order); cacheItems() keyed by $model->getIdentity() — the model's identity, which is not necessarily the table's (Siren's Config model identity omits the tenant column); updateCompound($ids) invalidated only the caller's compound key. A writer cannot enumerate every shape a reader may have used → GET-after-PUT served pre-update rows until TTL; a revoked API key kept authenticating from cache (observed on Siren SaaS against real Redis).
2. No table-level invalidation primitive existed — every fix so far (fix(cache): invalidate identity-keyed entries on compound-key updates #26, Novatorius/siren#195) was per-key enumeration containment.
3. The cache-aside race (slow reader SETs a stale row back after the writer invalidated) had no close that doesn't need transactions — and WordPress cannot use transactions.

Design

Canonical row keys. A row has exactly ONE cache entry, keyed by its table identity derived from row data: getFieldsForIdentity() fields, table-declared order, scalars stringified. Every context carries the table name alongside the model class — nothing enforces a 1:1 model-to-table mapping, so two tables reusing one model can never cross-serve rows with coinciding identities. cacheItems() and getCacheContextForItem() are gone. The shape follows the documented Novatorius class patterns: RowCacheContextAdapter (lib/Adapters) is a pure Adapter converting rows, identities, lookup keys, and models into the cache-context vocabulary (row/alias/table/generation contexts, canonical + raw identity projections, identity equality keys, generation-token formats, tri-state lookup verification) — no I/O, publicly testable. The datastore handler trait orchestrates the cache, driving the existing CacheableService with contexts the adapter builds: generation snapshots and bumps, guarded read-throughs, swallow-and-log entry mutations, alias resolution, and ephemeral-token skipping. DatabaseServiceProvider's constructor is unchanged; the only edit is a guidance docblock on its $cacheableService property. Contexts are canonical by construction — the test suite runs a deliberately order-sensitive md5(serialize()) policy to prove no normalizing policy is rescuing them.

Alias entries. A business-key lookup (findFromCompound() with anything that isn't the table identity) resolves through an alias entry: {type, table, alias: ksorted-lookup-key} → canonical identity, then the row entry. Aliases store identities, never data, and self-heal two ways: a dead target misses and falls to the DB, and every alias-resolved hit is verified against the caller's lookup values via the model adapter — so an identity-keyed update that rotates a business key can't leave its alias serving fresh-looking rows for a key they no longer carry. updateCompound() invalidates the row entry + alias as free byproducts of its existing pre-read — no extra query, no enumeration (what #26 tried to do with a resolution query).

Table generation tokens (the WP last_changed pattern). Every context carries a per-table opaque token; every writer replaces it. All prior entries become unreachable at once: O(1) whole-table invalidation (estimatedCount now invalidates correctly), and the late stale SET lands under the old generation where no future reader can compute its key — the race closes without transactions. Each operation takes ONE generation snapshot before touching the database and threads it through every context it builds — that snapshot is both the race fence (a stale write-back keyed pre-write can never collide with post-bump reader keys) and the round-trip bound (one token fetch per operation, not per row). Per-table opt-out: shouldUseTableGenerations(). Opted-out tables keep correct point invalidation: precise per-key deletes, read-time alias verification, and precise set-level (estimatedCount) invalidation on every write — the documented residual cost is only the TTL-bounded cache-aside read-back race.

Also fixed in passing

deleteWhere() previously deleted by the model's identity — on tables where that is a subset of the table identity, the SQL delete could reach rows outside the matched set. It now resolves identity rows via findIds() and deletes by the full table identity. RecordDeleted broadcasts for every deleted row with the raw identity row — deletions listeners never hear about are silent failures, and cache-key normalization stays out of the event contract. On every write path, post-commit cache work is best-effort: post-write invalidation never throws (deleteWhere additionally guarantees it lands via finally even when a mid-loop SQL delete fails), cache failures are logged instead of failing committed writes, and RecordCreated/RecordUpdated/RecordDeleted broadcasts always fire for committed writes under cache outages (bulk delete emission also isolates throwing listeners per-event; single-record broadcasts intentionally keep the pre-PR propagate contract) — a transient cache outage can no longer suppress events, fail committed writes, or break reads. Every cache entry mutation on the datastore handler swallows-and-logs failures (the obligation is documented on each helper); reads treat cache failure as a miss; the read-throughs use a capture-guard that serves the loaded value when only the post-load store failed, propagates domain exceptions untouched, and loads directly when the probe itself broke. Proven by tests driving reads and all three write paths through a throwing cache. updateCompound's SQL WHERE pins the resolved table identity together with the caller's lookup fields — the identity prevents non-unique-key fan-out, the caller's fields turn a concurrent key rotation into a no-op write, and an unresolvable record throws RecordNotFoundException. (Known limitation: QueryStrategy::update() returns void, so a rotation-noped write still broadcasts RecordUpdated.) Duplicate self-matches filter by table identity, so a true duplicate on a different row sharing a subset model identity is still caught. deleteWhere buffers its RecordDeleted broadcasts until after the SQL work, with per-event isolation. create() deliberately does NOT pre-warm the cache: the attribute-hydrated model carries request-typed scalars (#29) and a pre-warm keyed under create's own bump can seed the newest generation with a row a concurrent writer already overwrote — the first read after create costs one round-trip and is always correct.

Breaking / downstream migration

• getCacheContextForItem(), cacheItems(), and hydrateItems() are removed from the trait (hard breaks, no shims). DatabaseServiceProvider's constructor is unchanged.
• Event contract changes: RecordDeleted and RecordUpdated broadcast the handler's configured model class (previously the runtime $item::class/$record::class), and RecordDeleted carries the full raw table-identity row with driver-typed values (previously the model's getIdentity()). Listeners keyed on the old shapes must adjust.
• getEstimatedCount()'s cache operation is now Operation::Read (previously the literal 'estimatedCount') — a CachePolicy::shouldCache() branching on that string changes behavior.
• maybeThrowForDuplicateUniqueFields() is renamed to maybeThrowForDuplicateUniqueFieldsExcluding() with new semantics (self-matches filter by canonical TABLE identity, model identity as fallback) — stale call sites fail loudly instead of silently misfiltering.
• composer.json now declares php >= 8.2 with the composer platform pinned to match (phpnomad/chrono, a hard dependency, requires >= 8.2 in every release — older lock files were hiding it; PHP 8's locale-independent float casting also matters for cache keys).
• The typed-hydration follow-up for create()'s returned model is tracked as create()'s cache pre-warm carries request-typed scalars instead of DB column types #29. Siren: delete the cache overrides in TenantScopedDatabaseDatastoreHandler (the #195 containment) when adopting — the tenant column is part of the table identity, so the decorated/bare split disappears by construction.
• Key shapes change → one-time cold cache on deploy.

Testing

• New CanonicalRowCacheTest drives the trait through a real CacheableService + live array strategy: table-identity (not model-identity) keying, business-key update invalidating the row entry (the production bug), alias hit avoiding re-query, stale-alias self-heal, generation bump orphaning a late stale write-back, deleteWhere by full identity. A poisoned or old-format entry — canonical or alias, string garbage, wrong-field arrays, identity subsets — is never served or dereferenced: the slot is repaired from the database and the next lookup is query-free (both generation modes). Direct-store paths (alias writes, list-read write-backs) are proven to write nothing under an ephemeral outage token.
• Audit-driven additions: partial-identity rows never become cache keys (and warn), estimatedCount invalidates after writes in BOTH generation modes, healed aliases serve lookups query-free, rotated business keys never serve from their old alias, the first read after create() is DB-true (there is deliberately no pre-warm), and deleteWhere coverage includes broadcast payloads and the no-match path. Canonical behavior tests run under both generation modes via data providers.
• Legacy trait tests updated to the new context shape; phpnomad/event is a declared runtime dependency (replacing hand-rolled interface shims); reusable doubles live in tests/Doubles. Direct unit coverage for the adapter's pure conversions lives in RowCacheContextAdapterTest; outage behavior is covered for reads and all write paths via a throwing-cache double at the datastore-handler level. Read-side outage behavior is proven with a read-failing cache double (canonical reads, alias lookups, estimatedCount, and generation read-blips that must not clobber healthy tokens). Failure paths are proven end to end: read outages, write outages, mid-loop SQL failures in bulk deletes, throwing listeners, generation read-blips (ephemeral tokens skip caching entirely — stores no-op and read-throughs go straight to the database — so a sustained blip can't fill the cache with unreachable garbage). Full package suite: 95 tests, 198 assertions, green on the repo's CI (PHPUnit gate and spellcheck green). PHPStan: the new files (adapter, tests, doubles) are level-9 clean and the repo total improves on main (155 vs 233); the residual is pre-existing legacy flow and legacy interface signatures, re-reported per consuming class.

🤖 Generated with Claude Code

[alexstandiford]

Audit loop summary

This PR went through ten full rounds of the six-reviewer audit fleet (coding standards, testing standards, repo consistency, stack elevator, documentation, code smells — 60 independent reviews total), with every actionable finding fixed and re-verified between rounds. Highlights of what the loop caught, in order of consequence:

1. Generation-snapshot race — cache contexts were rebuilt (with a fresh token) at write-back time, so a concurrent writer's bump couldn't fence a slow reader's stale SET. Fixed with one pre-query snapshot per operation, threaded through every context.
2. Rotated business keys served from live aliases — an identity-keyed update could rotate a business key out from under its alias with nothing noticing on generation-disabled tables. Fixed with read-time lookup verification via the model adapter.
3. Failure-path outage behavior, end to end — committed writes can no longer be failed (or their events suppressed) by cache outages; reads survive read-side outages; ephemeral tokens skip caching entirely during token-read blips; bulk deletes isolate throwing listeners and guarantee invalidation via finally through mid-loop SQL failures. All proven by failure-injection doubles.
4. Identity discipline everywhere — SQL updates target the resolved table identity merged with the caller's key (no non-unique-key fan-out, no rotation TOCTOU), duplicate self-matches compare table identities, list reads keep survivors when rows vanish mid-read, and cache stringification stays out of SQL and event payloads.
5. CI was quietly broken — the phpunit action's default PHPUnit 11 phar ignores @dataProvider annotations (provider tests silently never ran), the lock couldn't install on the workflow's PHP, and spellcheck had been red on main for months. All three addressed: build-test and spellcheck are green; phpstan improves from 233 errors on main to 194 (the residual is pre-existing debt in files this PR doesn't author — every PR-authored file is level-9 clean).

Consciously accepted, documented in code: the provider's cacheableService extension surface (structural narrowing noted as future work), stringified alias identities in SQL WHERE (raw business key co-conditions), the model-identity duplicate-filter fallback for narrow adapters, single-record broadcasts propagating listener exceptions (bulk isolates), QueryStrategy::update()'s void return meaning rotation-noped writes still broadcast (needs an upstream signature change).

Follow-ups filed: #29 (typed hydration of create()'s returned model), #30 (TableSchemaService's unguarded cache reads).

Final state: 76 tests / 163 assertions green on CI, four new lib/ files + all new tests level-9 clean, Siren-side canonicalization already merged as Novatorius/siren#196, and Siren's TenantScopedDatabaseDatastoreHandler containment (#195) is deletable once this ships.

🤖 Generated with Claude Code