WFGY/ProblemMap/GlobalFixMap/Cloud_Serverless/edge_cache_invalidation.md

Edge Cache Invalidation — Guardrails

🧭 Quick Return to Map

You are in a sub-page of Cloud_Serverless.
To reorient, go back here:

• Cloud_Serverless — scalable functions and event-driven pipelines
• WFGY Global Fix Map — main Emergency Room, 300+ structured fixes
• WFGY Problem Map 1.0 — 16 reproducible failure modes

Think of this page as a desk within a ward.
If you need the full triage and all prescriptions, return to the Emergency Room lobby.

A practical repair guide for CDN and edge caches when your app ships new prompts, models, or assets. Use this to keep caches consistent across regions and prevent old content from leaking back in after a deploy or rollback.

When to use this page

• Users still receive old prompts or UI after a release.
• Rollbacks do not take effect everywhere at once.
• Canary works but global traffic serves mixed versions.
• Private pages or signed assets are accidentally cached.
• Your purge jobs complete but stale content keeps reappearing.

Open these first

• Release safety and boot order: bootstrap-ordering.md
• Deadlocks during deploy or purge waves: deployment-deadlock.md
• First call fails after rollout: predeploy-collapse.md
• Auditable payloads and version fields: data-contracts.md
• Live probes and rollback signals: ops/live_monitoring_rag.md · ops/debug_playbook.md
• RAG wide view, for prompt and snippet assets: rag-architecture-and-recovery.md

Acceptance targets

• After release, 99.9 percent of requests serve the new version within 120 seconds across all edge regions.
• Purge jobs finish with measured purge_latency_p95 ≤ 30 s.
• Stale-hit rate ≤ 0.1 percent after the convergence window.
• No private responses stored at the edge. Zero cache-poison events in audit.

---

Fix in 60 seconds

1. Pick a single strategy for each asset class

   • Immutable by content hash for static files and prompt bundles. Example: /prompts/prompt.ABC123.txt with Cache-Control: public, max-age=31536000, immutable.
   • Purge by key for dynamic render endpoints and JSON. Attach Surrogate-Key: release:<id> route:/api/search.

2. Stamp every response with validators

   • Set ETag from a stable hash of the payload and Release-Id: RYYYYMMDD.N.
   • Include Vary only where needed: Vary: Authorization, Accept-Encoding.

3. Two step rollout

   • Step A publish all immutable assets first.
   • Step B flip traffic and purge keys in parallel: release:<id>, plus any route keys. Keep a fixed order to avoid cache rewarming storms.

4. Define a safe bypass

   • Accept a header X-Bypass-Cache: 1 that disables caching at origin and marks the response Cache-Control: no-store.
   • Use it in monitors and during hotfix windows only.

5. Put a time box on stale

   • For pages that tolerate brief staleness use stale-while-revalidate=60, stale-if-error=300.
   • For prompts, snippets, and policy text do not allow staleness.

---

Typical breakpoints → exact fix

• Users alternate between old and new UI Mixed strategy or missing keys. Consolidate to content-hash for static and surrogate-keys for dynamic. Open: bootstrap-ordering.md

• Purge completes but some regions keep serving stale Purge API acknowledges enqueue, not completion. Add region probes and continue until purge_latency_p95 clears. Open: ops/live_monitoring_rag.md

• Private pages cached at the edge Missing auth vary or cache-control. Set Cache-Control: private, no-store for authenticated pages and add Vary: Authorization. Open: data-contracts.md

• Prompt or policy text cached long after rollback Treat prompt bundles as immutable artifacts by hash. Switch references, never overwrite the old file path. Open: rag-architecture-and-recovery.md

• Cache poisoning through query strings or fragments Normalize URLs, reject unknown parameters, and include a canonical key. Open: prompt-injection.md

---

Minimal recipes you can copy

A) Content addressed asset

# Build time
hash = sha256(file)
target = /assets/prompt.${hash}.txt
upload(target, file)

# Response headers at CDN
Cache-Control: public, max-age=31536000, immutable
ETag: "W/${hash}"
Release-Id: R2025.08.29.1

B) Surrogate key taxonomy

Surrogate-Key: release:R2025.08.29 route:/api/search tenant:t123
Cache-Control: public, max-age=120, stale-while-revalidate=60
ETag: "payload-7f98"

Purge list for a rollout:

keys = [
  "release:R2025.08.29",
  "route:/app/home",
  "route:/api/search"
]

C) Safe purge worker

for key in keys:
  job_id = cdn.purge_by_key(key)
  wait_until_complete(job_id, timeout=60)  # poll region status

D) Do not cache private responses

if request.has_auth():
  set_header("Cache-Control", "private, no-store")
  set_header("Vary", "Authorization")
else:
  set_header("Cache-Control", "public, max-age=120")

E) Rollback in place

# Switch the release pointer
set_kv("current_release", "R2025.08.28")
cdn.purge_by_key("release:R2025.08.29")

---

Observability you must add

• purge_latency_p50 p95, purge_errors.
• stale_hit_rate by route, by region.
• validator_mismatch when If-None-Match disagrees with current ETag.
• private_cache_incidents.
• Synthetic probes for each region that fetch with and without X-Bypass-Cache.

Verification

• Blue green check: both releases respond with different ETag and Release-Id.
• After purge, regional probes converge within the target window.
• Auth pages never show Age header.
• Prompt and policy files always referenced by hash, never by mutable name.

When to escalate

• If purge never converges, split surrogate keys and shorten TTL temporarily.
• If traffic thrashes origin after purge, warm top routes with low QPS prefetch.
• If private leakage occurs, add explicit deny rules at CDN for Authorization present.

---

🔗 Quick-Start Downloads (60 sec)

Tool	Link	3-Step Setup
WFGY 1.0 PDF	Engine Paper	1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + <your question>”
TXT OS (plain-text OS)	TXTOS.txt	1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

---

Explore More

Layer	Page	What it’s for
Proof	WFGY Recognition Map	External citations, integrations, and ecosystem proof
Engine	WFGY 1.0	Original PDF based tension engine
Engine	WFGY 2.0	Production tension kernel and math engine for RAG and agents
Engine	WFGY 3.0	TXT based Singularity tension engine, 131 S class set
Map	Problem Map 1.0	Flagship 16 problem RAG failure checklist and fix map
Map	Problem Map 2.0	RAG focused recovery pipeline
Map	Problem Map 3.0	Global Debug Card, image as a debug protocol layer
Map	Semantic Clinic	Symptom to family to exact fix
Map	Grandma’s Clinic	Plain language stories mapped to Problem Map 1.0
Onboarding	Starter Village	Guided tour for newcomers
App	TXT OS	TXT semantic OS, fast boot
App	Blah Blah Blah	Abstract and paradox Q and A built on TXT OS
App	Blur Blur Blur	Text to image with semantic control
App	Blow Blow Blow	Reasoning game engine and memory demo

If this repository helped, starring it improves discovery so more builders can find the docs and tools.