Caching

Requirement A cache proposal MUST record its observed query, representative load, latency, source cost, target, accepted staleness as a Limit record, owner, status, decider, and decide-by.

Rationale The record makes the cache's freshness and operating-cost trade-off reviewable.

Requirement A cache owner MUST remove a cache when measurements do not justify its operating cost.

Rationale A cache creates invalidation, capacity, and recovery work that needs continuing value.

Requirement A cache key MUST include its data-shape version, every result-affecting input, and applicable tenant or actor partition.

Rationale The key separates results that have different shapes, callers, or input values.

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

Requirement A cache key MUST NOT contain a secret, unbounded raw input, or personal data that is not already a hash.

Rationale 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.

Example 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.

Requirement A cached value MUST define expiry as a Limit record, invalidating write events, an invalidation owner, and behavior after invalidation failure.

Rationale An explicit contract makes stale data behavior visible before implementation.

Requirement A manual invalidation MUST produce a record naming actor, scope, and reason, as an audit record in its category when the audit extension is selected.

Rationale 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.

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

Requirement A cache owner SHOULD use a short expiry when precise invalidation costs more than recomputation.

Deviation: A measured staleness and operating-cost decision permits a longer expiry.

Rationale Short expiry limits stale data when invalidation precision is not economical.

Requirement A cache implementation MUST keep required business data authoritative in its source of record.

Rationale A cache stores a derived copy rather than the sole required business record.

Requirement A cache outage MUST use the source when capacity permits or return a documented degraded response.

Rationale Callers need predictable behavior when cache infrastructure is unavailable.

Requirement A cache path MUST emit a metric distinguishing a cache miss, a cache error, and a degraded response.

Rationale 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.

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

Requirement A cache implementation MUST bound simultaneous refresh work when concurrent misses could overload its source.

Rationale Bounded concurrency, request coalescing, and jittered expiry are valid techniques.

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

Requirement A cache implementation MUST NOT create an unbounded per-key lock inventory.

Rationale Unbounded lock state can exhaust memory under untrusted or high-cardinality keys.