Document sync vs async + fallback strategy trade-offs

[EtaCassiopeia]

Summary

Captures the resilience-strategy guidance that came out of the post-merge analysis of how the new initTimeout watchdog and the existing MultiProvider patterns interact for production workloads. Two doc files updated, no code changes.

What lands

docs/providers.md — new "Choosing a strategy — sync vs async, with vs without fallback" section. Sits after the existing "Async Variants" section, before "Provider Registry". Contains:

• Decision matrix mapping the four combinations of {sync, async} × {fallback, no fallback} to who they're right for.
• Watchdog semantics in each cell — sync uses initTimeout as a hard ceiling on cold-start latency; async uses it as a bounded uncertainty window.
• The cold-start "all defaults" gap explained, plus the two mitigations: (1) gate traffic on providerStatus from the readiness endpoint, (2) keep EnvVarProvider for only the flags whose default-value correctness matters.
• Recovery semantics under Fatal: it's a "stop waiting, take operator action" signal, not a tombstone — a later PROVIDER_READY event transitions Fatal → Ready.
• Tuning guidance for initTimeout (production cold-start vs CI vs sync-mode-is-the-boot-deadline).

docs/optimizely.md — expanded operational guidance.

• §7 (Detecting Fatal): rewritten with the readiness-check pattern explicit; clarifies that Fatal is recoverable so don't treat it as permanent.
• §8 (new) "Choosing a topology": three named patterns specific to Optimizely-backed apps — Pattern A (Optimizely-only async + readiness gate), Pattern B (Optimizely-only sync, fail-fast boot for correctness-critical workloads), Pattern C (Optimizely + EnvVarProvider for the small set of flags where defaults are unsafe). Each pattern has a runnable snippet using OptimizelyProvider.make, a fit-for-purpose rationale, and the trade-offs it accepts.
• Decision table to pick between A / B / C indexed by workload questions (can the app start while Optimizely is down? what happens during a runtime outage? right for correctness-critical workloads?).

CHANGELOG.md — [Unreleased] entries pointing at the new sections.

Why this is worth the change

Without this guidance, users picking a topology have to derive these trade-offs themselves. The full chain — fromProviderAsync defaults, the 30 s watchdog, MultiProvider + FirstSuccessfulStrategy's "Ready if any sub-provider is Ready" semantics, the recovery path under Fatal — is implicit in the codebase but not visible at any single doc location. The new sections make the implicit decisions explicit and give operators a fit-for-purpose pattern to pick from rather than a "here are the knobs, good luck" set of APIs.