docs(observability): define per-turn cache diagnostics

[627150795]

Problem

The model-info footer exposes only a cumulative cache percentage, which cannot identify the turn where prefix reuse changed. A zero cacheRead value is also ambiguous across providers and cache modes.

Value

This documents a conservative, provider-aware diagnostic boundary so operators can distinguish observations, correlations, and verified causes without turning normal best-effort cache behavior into false alarms.

Approach

Add a focused design contract for trace inputs, warm-to-cold classification, explicit versus implicit provider semantics, unknown handling, replay fixtures, and the opt-in delivery gate. The change is intentionally docs-only; it does not add a runtime detector or default UI marker.

Validation

• git diff --check
• bun run lint
• bun run typecheck
• Replay benchmark not run because this PR defines the contract and does not add the detector.

Impact

• User-visible behavior: none.
• Model-visible context/tools: none.
• Runtime/lifecycle: none.
• Persisted config/data: none.
• Compatibility/risk: docs-only; the existing cumulative cache metric remains unchanged.

Addresses #156

[tt-a1i]

Thank you for preserving this research. We are closing this PR as a source record for the Context and model invocation consolidation tracked in #277. This is not a finding that the content is wrong. The current queue contains overlapping contracts from one stale base, so we will extract only settled facts, recommendations, and unknowns into at most one successor record, citing this PR explicitly. Please do not spend time rebasing this branch.