Caching semantics

Data under a (campaign, stamp) is immutable — a new extraction gets a new stamp. The stamp is pinned per deployment (SERVING_STAMP) rather than appearing in the URL, so correctness comes from strong ETags derived from content addresses, not from cache expiry guesswork.

The chain of custody

The extraction manifest records each pack's sha256.
Pack fetches are verified against that sha on read (PACK_INTEGRITY on mismatch) and the sha keys the in-process LRU (PACK_CACHE_MB, default 256).
Response ETags embed the relevant content address, so a byte-identical response always has the same ETag and any data change must change it.

Cache-Control per route class

Class	Routes	Cache-Control
Health / errors	`/v1/health`, every error	`no-store`
Catalog	families list/detail, preflop catalog/depth/boundaries	`public, max-age=300, s-maxage=3600, stale-while-revalidate=86400`
Documents	board NodeDocuments, preflop node documents	`public, max-age=3600, s-maxage=31536000, stale-while-revalidate=86400`

Documents get a year of CDN lifetime because they are content-addressed and effectively immutable; catalogs stay short so newly uploaded families appear within minutes.

ETag forms

Prefix	Route	Derived from
`mf-`	`/v1/families`	manifest sha
`fam-`	`/v1/families/:fam`	manifest sha + pack sha
`pk-`	board documents	pack sha + board id — e.g. `"pk-38b207591014bfb9-Ks7s6s"`
`pf-`	`/v1/preflop`	catalog sha
`pfd-`	`/v1/preflop/:depth`	pack sha
`pfn-`	preflop node	pack sha + node id
`pfb-`	preflop boundaries	pack sha

Conditional requests

If-None-Match returns 304 Not Modified (headers repeated per RFC 9111). Weak validators (W/"…") are accepted, as is *.

Verified round-trip

GET /v1/families/100bb_3bet_call_p7v5_n13380/boards/ks7s6s
→ 200
  etag: "pk-38b207591014bfb9-Ks7s6s"
  cache-control: public, max-age=3600, s-maxage=31536000, stale-while-revalidate=86400

GET …/boards/ks7s6s
If-None-Match: "pk-38b207591014bfb9-Ks7s6s"
→ 304

What a stamp bump does

Publishing a new extraction under a new SERVING_STAMP changes every pack sha, therefore every ETag, at once. CDNs revalidate cheaply (one 304 per stale entry, or a fresh 200 where content moved), and mixed-dataset views are impossible by construction — the same property the product's methodology page promises.

The app side

The app leans on this model with generous next: { revalidate } windows (300s catalogs, 3600s documents) — see Data flow.