Caching

A cache costs invalidation, capacity, and recovery work for as long as it lives. The proposal records the observed query, load, latency, cost, and target so a reviewer weighs that cost against measured gain. A cache added without measurements stays until someone pays to remove it.

Reviewed forWhich cache proposals lack observed query, load, latency, cost, or target? Look at the proposal behind each cache.

Marked guidance: a reviewer answers this question.

Accepted staleness is the contract each reader relies on: it states how stale a read may be before it counts as a defect. The served query states it as {"mode": "bounded", "within": "PT5M"} on its output, so the cache and the query share one bound that is reviewed with the use case.

Reviewed forWhich cached queries lack a bounded freshness object with its duration on their output? Look at the served query beside each cache.

Marked guidance: a reviewer answers this question.

Traffic shifts and sources get faster, so a cache that paid for itself last year can cost more than it saves today. The owner re-checks the measurements and removes the cache when they no longer justify its operating cost. A cache nobody owns stays forever, and its invalidation bugs stay with it.

Reviewed forWhich caches stay past measurements that no longer justify their cost? Look at the owner reviews beside the operating cost.

Marked guidance: a reviewer answers this question.

A key missing the data-shape version serves old shapes to new readers after a deploy. A key missing a result-affecting input serves one caller's answer to a different request. Tenant or actor partition keeps one party's results away from another's.

post-summary:v2:tenant-42:post-17 identifies a versioned, tenant-scoped result.

Reviewed forWhich keys miss the data-shape version, a result-affecting input, or the tenant or actor partition? Look at the key construction.

Marked guidance: a reviewer answers this question.

Keys appear in diagnostics, metrics, and provider administration tools. That copies the value into a store no one classified. An email address in a key is a personal-data record in the cache provider's key space. It sits outside every retention and erasure path the project defined. Data minimization applies to an identifier as much as to a field.

A per-account cache key carries the account's opaque identifier. A key that carried the address instead is replaced by a hash of it, and the entry is bound to the account that owns it.

Reviewed forWhich keys contain a secret, unbounded input, or unhashed personal data? Look at the key construction.

Marked guidance: a reviewer answers this question.

Every cached value goes stale, and the only choice is whether the project decides the behavior up front or discovers it during an incident. Expiry, invalidating write events, an owner, and failure behavior state how long staleness lasts and who fixes it when invalidation fails. A cache without that contract serves stale data on a schedule nobody chose.

Reviewed forWhich cached values lack expiry, invalidating events, an owner, or failure behavior? Look at the invalidation contract of each cache.

Marked guidance: a reviewer answers this question.

A manual clear changes what every later reader sees and leaves no trace in the data itself. Investigating a stale-read report afterward means knowing whether someone already cleared the entry. Article 30 of the GDPR treats an administrative action over personal data as processing that has a record.

A command that clears one tenant's cached price list records the tenant, the operator, and the incident it was run for.

Reviewed forWhich manual clears lack a record naming actor, invalidation scope, and reason? Look at the invalidation runs.

Marked guidance: a reviewer answers this question.

Precise invalidation costs design and code, while a short expiry costs one recomputation per window. When recomputation is cheaper, a short expiry bounds staleness without the machinery. A longer expiry then needs a measured decision that says the extra staleness is worth its saving.

Reviewed forWhich long expiries lack a measured staleness and operating-cost decision? Look at the expiry beside the invalidation cost.

Marked guidance: a reviewer answers this question.

The cache holds a derived copy that the system can drop at any time. Required business data stays authoritative in its source of record, so losing the cache loses speed and nothing else. A cache that owns the only copy turns every cache outage into data loss.

Reviewed forWhich required business data lives authoritatively in the cache? Look at the source of record beside the cached copy.

Marked guidance: a reviewer answers this question.

Cache infrastructure fails like any other dependency. The outage behavior states whether callers fall back to the source or receive a documented degraded response, so an outage degrades the product on purpose instead of by accident.

Reviewed forWhich caches lack a documented source fallback or degraded response? Look at the outage behavior of each cache.

Marked guidance: a reviewer answers this question.

A fallback that works is invisible. An outage runs until someone notices the source load instead. The three cases need different responses: a miss is normal, an error is an infrastructure fault, and a degraded response is a product behavior change. One counter for all three answers none of them.

The metric carries the cache name and the outcome, following the OpenTelemetry semantic conventions for the client it wraps.

Reviewed forWhich cache paths share one counter across miss, error, and degraded response? Look at the emitted metrics.

Marked guidance: a reviewer answers this question.

When a popular entry expires, every concurrent miss can trigger its own refresh and flood the source the cache was protecting. Bounding simultaneous refresh work holds that flood to what the source tolerates. Request coalescing and jittered expiry are two ways to meet the bound.

One request refreshes a key while concurrent callers await the same bounded work.

Reviewed forWhich caches refresh without bound on concurrent misses? Look at the refresh path under concurrent load.

Marked guidance: a reviewer answers this question.

Per-key locks trade duplicate refresh for memory, and the trade needs a ceiling. Untrusted or high-cardinality keys create one lock entry each, which exhausts memory under attacker-chosen or runaway keys. A bounded lock scheme sheds that state instead of growing it.

Reviewed forWhich lock schemes grow one entry per key without bound? Look at the lock state under high-cardinality keys.

Marked guidance: a reviewer answers this question.