feat: graceful degradation strategy for service mode failures #11

Context

When service mode launches, verify() will make HTTP calls to the BurnerGuard API. Network calls fail — timeouts, 5xx errors, rate limiting, DNS issues. The library needs a clear, configurable strategy for what happens when the API is unreachable.

This is a must-have before service mode goes live.

Proposed behavior

Configuration

const guard = await BurnerGuard.create({
    apiKey: 'bg_live_...',
    fallback: 'static',       // 'static' | 'throw' | 'allow'
    serviceTimeout: 5000       // ms before falling back (default: 5000)
});

Fallback strategies

Result indication

When a fallback occurs, the result should indicate it:

{
    isMatch: true,
    matchedOn: ['blocklist'],
    isAllowlisted: false,
    degraded: true,             // indicates this was a fallback, not a full service check
    degradedReason: 'timeout'   // 'timeout' | 'serviceError' | 'rateLimited'
}

Retry behavior

• No automatic retries in the library — the consumer controls retry logic
• But expose enough info (degradedReason) for the consumer to make retry decisions

Open questions

• Should degraded and degradedReason be on VerifyResult (always present) or only on EnrichedVerifyResult?
• Should there be an onDegradation callback for logging/alerting?
• Should the fallback strategy be overridable per-call via VerifyOptions?

Acceptance criteria

• fallback option in BurnerGuardOptions with 'static', 'throw', and 'allow' strategies
• serviceTimeout option
• degraded and degradedReason fields in verify result
• Correct behavior for each fallback strategy on timeout, 5xx, rate limit
• Tests covering: each fallback strategy, timeout handling, degraded result fields
• README section explaining degradation strategies and when to use each

Priority: 🟡 Medium — must-have before service mode launches