Cache Invalidation Race Verdict

Verifies a cache event log for the write/populate/invalidate race that leaves a cache silently stale, permanently. Pure function of the log you pass in: no clock, no I/O, no default threshold. The caller supplies the facts and gets a verdict.

THE SILENT FAILURE. A cache-aside pattern has three moving parts, not two: the source of truth is written, the cache is invalidated, and -- separately, often on a different request, sometimes much later -- the cache is repopulated. A read that began BEFORE the write can complete AFTER the invalidate and populate the cache with the value it fetched, which is the old one. There is no error, no warning, and no expiry that will fix it if the entry is written with a fresh TTL. The cache is now wrong until something unrelated evicts it, and every request in between is served a confident stale answer.

IT IS A VERIFIER, NOT A CACHE. You already have the events -- from tracing, from structured logs, from a test harness. This decides whether the interleaving in them admits the race, and names the specific pair of operations that did it. That makes it usable as a CI check over recorded traces, not just a post-incident tool.

NO DEFAULT THRESHOLD, ON PURPOSE. What counts as a dangerous window depends on your system, and a library that invents a number produces confident verdicts about a system it knows nothing about. Supply the fact or get NOT_DETERMINABLE naming what is missing.

A FALSE OK FOUND BY VERIFICATION, AND FIXED. A cache key named `__proto__` returned status OK with an empty key report -- the verdict object was a plain `{}`, so that key landed on the prototype and vanished from its own results. The one key most likely to be adversarial was the one key that could not be reported on. Reproduced by hand against both the fixed and unfixed builds before the change; reverting it now fails 2 tests.

VERIFIED: 111 tests, measured by running the suite, every mutation observed FAILING before restore.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateCacheInvalidationRace(events: readonly CacheEvent[]): CacheRaceReport;

  export type CacheEventType = "db_write" | "cache_populate" | "cache_invalidate";
  export type KeyStatus = "FRESH" | "STALE" | "NOT_DETERMINABLE";
  export type KeyVerdict = FreshKeyVerdict | StaleKeyVerdict | NotDeterminableKeyVerdict;