cache: document Tiered Cache eligibility timing and upper-tier origin-path latency

[stechedo]

What

Documents two Tiered Cache behaviors that customer tickets repeatedly surface, from a real escalation (InvestCloud custom hostname, intermittent asset latency from EWR):

1. Request-time vs response-time bypass. Tiered Cache activates for cache-eligible requests when they arrive. Origin response headers (Cache-Control: no-store / bare private) act on the response, after the upper-tier fetch has already happened, so origin-header bypass produces BYPASS without stopping the upper-tier fetch. Only a request-time Cache Rule Bypass cache prevents tiering.
2. Upper-tier selection ignores upper-tier→origin latency. Generic Global maps lower tiers to fixed regional upper tiers, statically; only Smart Tiered Cache uses in-house origin-latency data. A congested provider on the upper-tier→origin path slows tiered misses without affecting cache hits, and the fix is a network-path change, not disabling Tiered Cache.

Changes

• cache/how-to/tiered-cache.mdx
  • Generic Global section: static regional lower→upper mapping, no origin-latency probing (Smart does), requests tier within region only.
  • New "Tiered Cache and cache eligibility" section: activation timing, BYPASS-after-upper-tier-fetch behavior, request-time Bypass cache rule.
• cache/troubleshooting/investigating-tiered-cache-latency.mdx (new page): intermittent slow-on-MISS-only diagnosis, MTR comparison from upper-tier colo to origin IP vs a working colo, when to route the provider-path finding to network engineering, why disabling Tiered Cache is not the fix, upper-tier placement options (Smart topology, cloud region hint, custom topology).
• cache/troubleshooting/investigating-uncached-responses.mdx: BYPASS section gains the upper-tier-fetch note; Related resources link the new pages.

Companion internal work already shipped: CSUP wiki runbook updates (Cache Troubleshooting Guide Tiered Cache section; Declaring an Incident anti-criteria) and Support Seal guidance MR (tiered-cache latency journey + escalation judgment guard).

[cloudflare-docs-bot]

Review

💡 3 suggestions found in commit 63344d7.

👉 Fix in your agent 👈

Fix the following review findings in PR #33422 (https://github.com/cloudflare/cloudflare-docs/pull/33422).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Style Guide Review

### Suggestions (3)

#### SG-f3206064c2d2 · Semicolon joining two independent clauses
- **File:** `src/content/docs/cache/troubleshooting/investigating-tiered-cache-latency.mdx` line 15
- **Issue:** `...that fetches through an upper tier; the fast requests are HIT.` uses a semicolon to join two independent clauses
- **Fix:** Break into two sentences, e.g. `...that fetches through an upper tier. The fast requests are HIT.`

#### SG-dd31c881c832 · Semicolon joining two independent clauses
- **File:** `src/content/docs/cache/troubleshooting/investigating-tiered-cache-latency.mdx` line 27
- **Issue:** `...over uncoordinated paths; routing around the congestion is what fixes it.` uses a semicolon to join two independent clauses
- **Fix:** Break into two sentences, e.g. `...over uncoordinated paths. Routing around the congestion is what fixes it.`

#### SG-b368b7951965 · Semicolon joining independent clauses
- **File:** `src/content/docs/cache/troubleshooting/investigating-uncached-responses.mdx` line 46
- **Issue:** Line joins two independent clauses with a semicolon: "Origin-header bypass does not prevent this; a request-time Cache Rule with **Bypass cache** does."
- **Fix:** Break into two sentences, e.g. "Origin-header bypass does not prevent this. A request-time Cache Rule with **Bypass cache** does."

Code Review

This code review is in beta and may not always be helpful — use your judgment.

_{No code review issues found.}

Conventions

_{No convention issues found.}

Style Guide Review

Suggestions (3)

File	Issue
cache/troubleshooting/investigating-tiered-cache-latency.mdx line 15	Semicolon joining two independent clauses — ...that fetches through an upper tier; the fast requests are HIT. uses a semicolon to join two independent clauses Fix: Break into two sentences, e.g. ...that fetches through an upper tier. The fast requests are HIT.
cache/troubleshooting/investigating-tiered-cache-latency.mdx line 27	Semicolon joining two independent clauses — ...over uncoordinated paths; routing around the congestion is what fixes it. uses a semicolon to join two independent clauses Fix: Break into two sentences, e.g. ...over uncoordinated paths. Routing around the congestion is what fixes it.
cache/troubleshooting/investigating-uncached-responses.mdx line 46	Semicolon joining independent clauses — Line joins two independent clauses with a semicolon: "Origin-header bypass does not prevent this; a request-time Cache Rule with **Bypass cache** does." Fix: Break into two sentences, e.g. "Origin-header bypass does not prevent this. A request-time Cache Rule with **Bypass cache** does."

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.