Application Cache Boundary

## The two calls and where they belong A service method that uses an application cache has exactly two extra touch points, and the whole design is deciding where they sit relative to the transactional boundary. ``` lookup(key) <-- before the unit of work opens hit -> return miss -> begin unit of work load + assemble commit store(key, model) <-- after commit returns return ``` Everything interesting follows from keeping both calls outside the transaction. ## Why the read goes first - **A hit should cost nothing on the database side.** If the lookup happens inside an open unit of work, every hit has still taken a connection from the pool and started a transaction, then thrown that away. Under load the pool, not the query, is often the scarce resource, so a cache that still borrows a connection has given back much of its value. - **A hit should not touch the mapper.** The point of caching above the mapper is to skip the mapper's work as well as the query. Reading the cache from inside the mapper's own load path defeats that. - **It keeps the transaction short.** Whatever remains inside the boundary is only the work a miss genuinely needs. The exception worth stating out loud is a read that happens *inside* a write use case — code that must see its own uncommitted changes. That read has to go to the mapper, not the cache, because the cache by construction holds the last committed answer. ## Why the populate goes after the commit Storing the assembled model while the transaction is still open makes the cache visible to other readers before the database is. Three concrete failures follow: 1. **Rollback publishes a phantom.** The transaction fails after the entry is stored — a constraint violation, a concurrency check, a timeout on a later statement — and the store now holds a value that never existed in the database. Nothing will correct it: no write happened, so no invalidation runs. It survives until its expiry. 2. **Readers see the future.** Between the store and the commit, other requests are served data the database has not accepted yet. If they act on it, the ordering error propagates outward. 3. **The value may not even be final.** Values the database supplies — column defaults, trigger effects, computed columns — reach the assembled model only after the statements have actually run, and an identifier handed back during an insert is still undone by a rollback. An entry snapshotted early can be missing, or wrong about, exactly the fields that make it useful. The same reasoning bans populating from a hook that fires during flush, or from a callback the mapper invokes while assembling objects. Flush is not commit: pending statements have reached the database, and can still be undone. Only the return of the commit call is the point at which the value is real. ## The write path mirrors it | Step | Inside the transaction | After the commit returns | |---|---|---| | Change the record through the mapper | yes | — | | Read the current state to build the new model | yes | — | | Store or refresh the cache entry | never | yes | | Drop the entry so the next read reassembles | never | yes | Two practical notes on the "after" column. First, the code that runs after the commit is *not* covered by the transaction, so a failure there — the store is unreachable, the process dies — leaves the database correct and the cache wrong. That is the right direction to fail, but it means the entry must be able to be wrong safely, which is what expiry is for. Second, "after commit" has to mean after the *outermost* commit. In a nested call where an inner service participates in a caller's transaction, the inner method's own boundary may not be a real commit at all; hanging the store off it publishes early. The cleanest arrangement is to let the outermost boundary trigger the population, rather than each layer doing its own. ## What this placement does not solve Getting the order right prevents publishing something the database rejected. It does not make the entry fresh: from the moment it is stored, another writer can change the underlying data and the entry will happily keep serving what it captured. Ordering is a correctness rule about *never publishing an uncommitted value*; keeping a committed value current afterwards is a separate discipline with its own trade-offs.