L10 - Cache
Cache read results without moving query execution or persistence into the cache layer
Location: src/cache/
Why This Layer Exists
Repeated reads should not always reach the database. L10 provides cache keys, TTL handling, stale-while-revalidate behavior, invalidation, and backend abstractions while keeping database queries in the query engine and drivers.
The official cache() extension exposes $withCache() and $invalidate() on
its derived client only. Cache backends implement storage; they do not know how
VibORM builds or executes SQL.
Boundary
| Cache owns | Cache does not own |
|---|---|
| Canonical validated-operation keys and private extension namespaces | Query construction |
| TTL and stale-while-revalidate policy | Database execution |
| Portable detached snapshots and fresh materialization | Provider-row ownership |
| Explicit and mutation-triggered invalidation | Result parsing |
See Caching for configuration and backend documentation.
Connection to Other Layers
- L9 (Client): Authenticates the official capability and creates cached views
- L11 (Instrumentation): Observes cache hits, misses, writes, and refreshes
- L6-L8 (Execution): Run only when the cache path requires a database read
Read caching deliberately bypasses callback and array transactions, raw calls,
and statement-transform chains. Mutation invalidation uses the existing ordered
write-outcome rail in src/extensions/query.ts, so savepoint rollback discards
it and outer commit publishes it once. The official factory and authenticated
capability stay in src/cache/extension.ts; the inner-core read trigger remains
in the query engine. A custom read key is a suffix of canonical identity, never
a replacement.