What Is Caching

What It Is

Caching stores the result of expensive work so you never pay the same cost twice. It is a deterministic shortcut: compute once, serve many. Every cache entry is a contract — a promise that the stored value is faster to retrieve than the source of truth, and a promise that it will be invalidated when that truth changes.

Why It Matters

Without caching, every request hits the source of truth. Every database query, every API call, every disk read. This is correct. It is also ruinously slow.

Caching exists because the world has two truths: the truth that exists, and the truth that is fast enough to use. They are not always the same. The gap between them is the cost of certainty.

In OIP systems, this gap is not a bug. It is an explicit contract. The build does not pretend every cache hit is a live query. It states: this value is cached at time T, valid until invalidated by event E. That is honesty. That is auditability. A system that hides its cache is lying. A system that declares its cache is a protocol.

Practically, caching turns hardware constraints into predictable performance. A millisecond disk read becomes a nanosecond memory read. A cross-continent API call becomes a local hash lookup. The difference is not marginal. It is the difference between a system that scales and one that collapses under its own load.

How It Works

Step 1: The miss. A request arrives. The cache is checked. No entry exists. The system does the expensive work: queries the database, computes the result, fetches from origin.

Step 2: The store. The result is written to the cache with a key — typically a deterministic hash of the request parameters. This key is the contract identifier.

Step 3: The hit. A subsequent identical request arrives. The cache key is recomputed. The stored result is returned instantly. No database query. No network round-trip. No computation.

Step 4: The invalidation. The source of truth changes. A database row updates. A file is edited. The cache must be purged or updated. This is the hard part. Every caching system lives or dies on its invalidation logic.

Step 5: The eviction. The cache reaches its capacity limit. An old or unused entry is removed to make room. This is a mechanical, not logical, event. The entry is not wrong; it is merely less important.

Concrete example: a blog serves a popular article. The first reader triggers a database query, a template render, and a response. The rendered HTML is stored in a cache with key article:123. The next 10,000 readers receive the cached HTML in microseconds. When the author edits the article, the key article:123 is invalidated. The next reader triggers a fresh render.

The Contract

A cache is defined by four parameters:

In OIP, these four parameters are not implementation details. They are the public contract. Every cache entry must be traceable to its origin, its TTL must be explicit, and its invalidation must be observable in the ledger.

Real Examples

Redis in a web application. A user profile is fetched from PostgreSQL, serialized, and stored in Redis with a 60-second TTL. Every profile view in that minute reads from Redis. The user updates their bio; the application invalidates the Redis key user:profile:8472 immediately. The next read is a cache miss, fetches from PostgreSQL, and repopulates Redis.

CDN edge caching. A static JavaScript bundle is served from a Cloudflare CDN. The origin server in Virginia is the source of truth. A user in Tokyo requests the file. The first Tokyo request travels to Virginia. The file is cached at the Tokyo edge. The next 100,000 Tokyo requests are served from the local edge node. The cache key is the file path plus a content hash. When the build deploys a new version, the hash changes, and the edge cache is naturally bypassed.

CPU L1 cache. A processor executes x = array[i]. The data is not in the L1 cache. The CPU stalls for 100 cycles to fetch from RAM. The value is stored in L1. The next 10 instructions reference the same value. Each is served in 3 cycles. The hardware cache is invisible to the programmer, but the contract is identical: expensive fetch once, cheap access thereafter.

DNS caching. A browser resolves example.com to 93.184.216.34. The operating system caches this mapping for the TTL specified in the DNS record (e.g., 300 seconds). Every subsequent request to example.com in that window uses the cached IP. The registrar changes the A record; the old TTL governs how long stale resolutions persist across the internet.

HTTP ETag caching. A client requests an API resource. The server responds with an ETag: "abc123" header. The client caches the response and the ETag. On the next request, the client sends If-None-Match: "abc123". The server responds 304 Not Modified with no body. The client uses its cached copy. No data transferred. One header comparison. The contract is: the server promises the ETag changes when the resource changes.

Common Mistakes

Cache without invalidation. A system caches aggressively and never invalidates. The data grows stale. Users see wrong states. The system becomes a lie machine.

Cache without a contract. The cache TTL is implicit, buried in configuration, or undocumented. No one knows how stale the data is. Debugging becomes archaeology.

Cache the wrong layer. A developer caches the output of a function that already contains cached database calls. The double cache creates nested TTL problems and stale data cascades. Cache the expensive layer, not the cheap one.

Thundering herd. The cache expires. A thousand requests arrive simultaneously. Every one misses the cache and hits the database. The database collapses. Solution: per-request revalidation, stale-while-revalidate, or probabilistic early expiration.

Treating cache as source of truth. The cache is a performance layer. It is not the ledger. If the cache and the database disagree, the database wins. Any system that treats cache as truth has a consistency bug.

Connection to OIP

OIP is the Open, Deterministic, Auditable Protocol. Caching is not a peripheral optimization in OIP. It is a first-class concern precisely because it is a source of hidden state.

Open: Every cache policy is declared. TTLs are visible. Invalidation logic is explicit. There is no hidden cache that silently changes behavior.

Deterministic: The same input yields the same cache key. The same cache key yields the same result within its TTL. The contract is reproducible. A cache hit is not random luck; it is a predictable outcome of a deterministic hash.

Auditable: Every cache miss, hit, and invalidation is a candidate for the ledger. The build logs when a value was cached, when it was hit, and when it was purged. A cache is not a black box. It is a traceable component of the system's observable state.

In OIP, caching is not a trick to make things faster. It is a disciplined trade between speed and certainty, governed by explicit contracts that the system can read, verify, and audit. A cache is a promise. OIP keeps promises.

Connection to the Grain Philosophy

This protocol is part of the Open Inventory Protocol — a living system of self-describing voxels that serves the Grain philosophy. The OIP is the interface. The philosophy is the core.