feat(proxy): deterministic substitution/failover engine (v0.9.1)

[WayforthOfficial]

Extends the Reliability Proxy /proxy/{slug} from single-hop into a config-driven, multi-hop substitution/failover engine. Deterministic layer only — ML-ranked selection is a later phase. Built in apps/api (co-located with /proxy + billing; zero cross-service hop), per the approved plan.

⚠️ Idempotency (#5) — FLAGGED FOR YOUR REVIEW BEFORE MERGE

• pre-send (conn refused, connect-timeout, HTTP 5xx, 429) → always fail over.
• post-send-ambiguous (read-timeout-after-send, invalid-body-after-200) on the managed rail → fails over (the end user is always refunded, so never double-charged) under a cost cap (failover_post_send_max_cost, default 25 cr), preceded by a same-provider retry-first, with full instrumentation (duplicate_upstream_cost_possible + measured second_upstream_cost_credits per event).
• x402 / on-chain per-call settlement → STRICT: never fail over (and no retry) on post-send — surfaces the error. Irreversible double-settlement is the real risk.
• failover_post_send defaults true, flippable to strict via env if the measured leak turns material. The residual risk is Wayforth's duplicate upstream cost — now measured in substitution_events, not assumed.

What it does

• Config-driven groups (substitution_groups table, seeded web-search + llm-inference; weather/maps config-ready, no peers yet). A provider is never substituted outside its group. Ordered by wri_score when present, else curated manual_rank — never sorts on nulls, never random (verified live: tavily wri 85.5 ranks first, null-wri peers fall to manual_rank).
• Billing correctness: charges ONLY the served provider (+ its embedded 1.5% routing fee); every failed hop nets to zero (deduct+refund, per-hop idempotency keys); the surviving ledger row is the real served provider.
• Failure detection: _try_execute_managed_ex distinguishes httpx ConnectError/ConnectTimeout/5xx/429 (pre_send) vs ReadTimeout/PoolTimeout/200-invalid-body (post_send).
• Self-heal surface: X-Wayforth-Served-By + X-Wayforth-Fallback headers (+ wrap envelope). Group exhaustion → clean 502 listing providers tried + reasons.
• substitution_events log (migration 064, shared DB) — future learned-layer training signal; nothing consumes it yet.
• Guardrails: depth cap; per-provider creds via key_var (missing → skip); primary success path untouched (engine only invoked on the failure branch — zero overhead).

Verification

• 13 engine unit tests green (ordering, depth cap, pre/post classification + gates, served-only billing, retry-first, invalid-body, 502 shape, event emission). Full offline suite green; import chain clean.
• Migration 064 applied + verified on prod (additive/idempotent): both groups seeded, substitution_events (15 cols) created. Loader ordering validated live against real wri data.
• VERSION 0.9.0 → 0.9.1.

Not auto-merging — please review the idempotency (#5) policy above first.

🤖 Generated with Claude Code