The Invalidation Event Contract: Fields a Publisher Must Send

Every event carries exactly these fields. Extra fields are allowed but never load-bearing.

{
  "event_id": "0f3c6b1e-5a2d-4f0a-9b7e-2f1c8d4a6e90",
  "content_id": "product:4417",
  "version": 1842,
  "scope": { "kind": "key", "tags": ["catalog:shoes", "listing:page-3"] },
  "occurred_at": "2025-11-04T09:12:33.412Z",
  "reason": "price_update",
  "origin": "catalog-writer"
}

Here is what each field means and who reads it.

event_id: a UUID produced once at publish time. It is the deduplication key. Consumers keep a short-lived set of seen ids, and it doubles as the correlation id in logs so you can trace one change through gate, L1 and L2. A request that arrives twice with the same event_id must be a no-op the second time, which is the same idempotency discipline webhook receivers need to avoid replay attacks the webhook security guide.

content_id: a namespaced identifier for the thing that changed, for example product:4417 or article:slug/foo. L1 and L2 build their cache keys from this, so it must match the key function the read path uses. If it does not, the event purges nothing and the cache looks fine while serving stale data.

version: a monotonically increasing integer per content_id, bumped on every write. This is the ordering mechanism. L2 keeps the version it cached and ignores any event whose version is lower than what it already stored. That single rule fixes the out-of-order problem where a slow bypass write lands after a newer application write. Data consumers whose correctness depends on freshness need exactly this kind of ordering guarantee, and it is the same reasoning SRE teams apply when they tie reliability targets to measurable indicators the SRE workbook chapter on SLOs.

scope: an object with a kind and an optional tag list. Kind is key, tag, or all. A key event purges only the named content_id. A tag event purges every entry carrying a listed tag, which is how the edge gate turns one change into a purge of a listing page. An all event is a full flush and should be rare and audited.

occurred_at: an ISO 8601 timestamp with milliseconds and an offset, set when the change was committed, not when the event was published. Consumers use it for observability and to compute age, never for ordering. Ordering belongs to version.

reason: a short code such as price_update, delete, publish, schema_change. Consumers do not branch on it today, but it is the field that makes incident review possible, and it is the first place you look when a purge storm appears in metrics.

origin: the service that made the change. This lets you attribute events during a rollout, mute a noisy publisher, and detect duplicate publishers when two services both emit for the same content_id.

The same event drives three different actions, and being explicit about each is what stops drift.

The edge gate cares about scope. On a tag event it purges every cached response carrying any listed tag. On a key event it purges only responses tagged with that content_id. On all it flushes the whole node group. It never needs version, because it holds no per-entry ordering state. That is a deliberate simplification: keeping version state at the edge costs memory and buys nothing when the rebuild path always fetches fresh.

L1 cares about content_id only. Each process holds a map from content_id to value, and an event for that id deletes the entry. Because L1 is per-process and short-lived, the loss of an event costs seconds of staleness, not minutes. That bounded blast radius is also why L1 can be the least careful consumer.

L2 cares about content_id and version. On receiving an event it compares the incoming version to the version stored alongside the cached value. If incoming is greater, delete. If equal or lower, ignore and count it as a stale event. If no entry exists, record the version anyway if your design tracks a version index, so a later repopulation does not overwrite newer data.

Tag-based invalidation has a known cost: a tag drawn too broadly discards far more cached data than the change required and triggers an avoidable burst of misses the Redisson invalidation glossary. Version-based invalidation has the opposite trade-off, since the old entry is orphaned rather than deleted and needs TTL and eviction to reclaim memory the Redisson invalidation glossary. The contract above lets you use tags at the edge, where the trade-off is cheap, and versions in L2, where correctness matters more.

Take a product whose price changes from 20.00 to 18.00. The writer commits the row and bumps version from 1841 to 1842. It publishes one event with content_id: product:4417, version: 1842, scope.kind: tag, tags catalog:shoes and listing:page-3, reason: price_update.

The gate receives it and purges two response groups: the product page group tagged with the item and the listing page group. Suppose that listing page held 48 cached responses, one per country and device variant. All 48 are gone and will be rebuilt on next request. At a rebuild cost of 40 ms each, that is roughly 1.9 seconds of extra work spread across the next minute of traffic, not a spike if requests are spread.

L1 receives the same event and deletes the single object under product:4417 in each process that saw it. No version bookkeeping.

L2 receives it and finds a cached value at version 1841. Since 1842 is greater, it deletes the entry and stores 1842 in its version index.

Now the failure case. A nightly batch job writes the same row directly to the database, bypassing the writer, so no event is published. L2 keeps serving 18.00 while the database says 17.50. Nothing catches it until either the TTL expires or the reconciliation job runs. That is why the fallback section below is not optional.

A worked comparison of what each consumer would do if you omitted a field:

The scope and version omissions are the two that cause real incidents. The event_id omission causes load. The occurred_at omission only hurts observability, which is why some teams make it optional, though I would keep it required to force publishers to think about clock source.

A contract is only real if it is executable. Publish a shared test package that both sides run, with a fixtures file of events and expected outcomes. The suite validates three things.

Field presence and type. Every required field exists, version is an integer, occurred_at parses as ISO 8601 with an offset, scope.kind is one of the three allowed values, and tags are non-empty strings when present. Run this against the publisher's serializer as part of its build, not after deploy.

Version monotonicity. Feed the suite a sequence of events for one content_id and assert that versions strictly increase. Some teams allow equal versions for idempotent republishes, so decide which rule you want and test it.

Consumer behavior. For each layer, assert the mapping. A tag event purges all matching groups. A key event purges only the named key. A stale version is ignored at L2. A duplicate event_id is a no-op everywhere.

The same discipline applies to security: verify the signature or shared secret on every incoming event and reject anything that fails, because a forged invalidation event is a cheap denial-of-service against your cache the webhook security guide. Treat the event endpoint as untrusted input even when it sits inside your network.

A checklist for the test suite itself:

• Fixtures are checked into the shared package and versioned alongside the schema.
• Both the publisher and all three consumers run the suite in CI.
• Adding a required field means bumping the schema version and updating fixtures first.
• The suite includes at least one deliberately malformed event per field, so a lenient parser fails loudly.
• The suite runs against a real L2 instance, not a mock, because the version index is where bugs hide.

Data quality teams use the same framing when they measure how often records arrive wrong: define the indicator, set the objective, and let the error budget tell you when to stop shipping features and start fixing pipelines Muness Castle on data quality SLOs. Your event stream deserves the same treatment. Track publish rate, consumer apply rate, stale-event rejections and gate purge count as four separate indicators, and alert when the gap between publish and apply grows.

Every event-driven design needs a fallback for silence, because publishers crash, topics drop messages and batch jobs bypass writers. The standard answer is a hybrid of TTL and events, which costs more complexity but bounds staleness the OneUptime invalidation guide.

Fallback TTL. Give every cache entry a TTL even when events work perfectly. Set it per data type: short for prices and inventory, long for descriptions. With a 60-second TTL you accept up to 60 seconds of staleness, which is fine for a product listing and not fine for an account balance the Redisson invalidation glossary. The TTL is the ceiling on your worst case, and writing it down as a number is the decision that matters.

Reconciliation. Run a periodic job that walks stored versions in L2 and compares them to the source of truth. Where the source version is higher than the cached version, purge the key and emit a synthetic event with reason reconcile so the gate and L1 also clear. Where an entry has no source record, purge it as a delete. Measure what fraction of entries the job had to fix. A steady nonzero rate means a publisher is silently failing, and that number is your most useful alert.

Choosing the reconciliation interval is a judgment call. A useful rule: set it to a small multiple of the fallback TTL, so the TTL handles most silence and the job catches the entries that never expire because they are read constantly. Run the job off-peak and cap its purge rate so it cannot itself cause a miss storm.

Data freshness is worth measuring explicitly rather than assuming: define what fresh means for each dataset and track the fraction of reads that fell inside the window Decube on data freshness. The same idea applies here. If your SLO says 99 percent of reads see a version no more than five minutes old, then TTL plus reconciliation is how you defend it, and the event stream is how you usually meet it without paying the cost.

Three rules keep the pipeline honest.

First, publish after commit, never before. If the event goes out and the transaction then rolls back, every consumer purges a value that never changed, and the read path refills the old value at the same version, which L2 will then reject as stale. If you need atomicity between the write and the publish, use a transactional outbox so the event is written in the same transaction and relayed afterward.

Second, make publishing a single function that every write path calls. When a service writes to its database, it should behave as the owner of that data and emit the event from one place, because a write path that forgets creates a stale entry nothing clears until TTL the Redisson invalidation glossary. Code review for this is cheaper than any monitoring.

Third, roll out schema changes additively. Add fields as optional, let every consumer ship support, then make them required and bump the schema version. Removing a field follows the reverse order. A contract test suite makes each step verifiable.

Teams building this pipeline also tend to be running models behind it, embeddings for search or a ranking model for listings. If the change events already move through one system, it is worth routing model calls through the same discipline. Quanta Inference gives you text, image, video, audio and embedding models through one OpenAI-compatible API key, priced in US dollars, so the rebuild path after a purge calls one endpoint instead of five vendor SDKs (https://quantaintelligence.ai/inference).

The test of a good invalidation contract is boring: when a writer breaks, the reconciliation job reports it before a customer does, and when you add a new cache layer, it takes a day rather than a quarter because the event already carries what it needs.