feat(discovery): merge bounded Discovery stack

.env.example

@@ -97,6 +97,7 @@ ENABLE_API_KEY_REDIS_CACHE="true"        # 是否启用 API Key Redis 缓存（
 # 降低该值会按签发时间收紧已签发 ADMIN_TOKEN 签名 cookie 的剩余寿命，且不会延长其原始 exp。
 AUTH_SESSION_TTL_SECONDS=604800         # Web UI 登录态过期时间（秒，默认 604800 = 7 天，范围 60-31536000）
 SESSION_TTL=300                         # 代理请求上下文缓存时间（秒，默认 300 = 5 分钟；不控制 Web UI 登录态）
+DISCOVERY_ROLLOUT_PERCENT=100           # Discovery 运维灰度比例（0-100，按 API Key + Session 稳定分桶）
 STORE_SESSION_MESSAGES=false            # 会话消息存储模式（默认：false）
                                         # - false：存储请求/响应体但对 message 内容脱敏 [REDACTED]
                                         # - true：原样存储 message 内容（注意隐私和存储空间影响）

docs/streaming-discovery.md

@@ -0,0 +1,71 @@
+# Bounded Streaming Discovery
+
+Bounded Discovery is an optional cold-start routing mode for streaming
+requests. It exists to reduce duplicate upstream spend while preserving a
+working request when the first provider is slow.
+
+## Defaults
+
+| Setting | Default | Meaning |
+| --- | ---: | --- |
+| `discoveryEnabled` | `false` | Keep the existing Hedge path until explicitly enabled. |
+| `discoveryConcurrency` | `2` | Number of normal providers in the first batch. |
+| `maxDiscoveryRounds` | `2` | Maximum Discovery rounds. |
+| `discoverySlaMs` | `10000` | First-byte budget for a Discovery round. |
+| `stickySlaMs` | `20000` | First-byte budget for an existing Sticky provider. |
+| `racingTotalTimeoutMs` | `60000` | Total pre-winner deadline; it is cleared after a winner is committed. |
+| `stickyTimeoutCooldownMs` | `300000` | Session/provider cooldown after a Sticky timeout. |
+
+The total deadline must be at least `stickySlaMs + maxDiscoveryRounds *
+discoverySlaMs`. The UI and API reject configurations that do not satisfy
+this relationship.
+
+## Request lifecycle
+
+- A healthy Sticky provider is probed alone. If it times out, it becomes the
+  single fallback for this request and receives a cooldown; a later request
+  may select it again after the cooldown.
+- A cold start launches the configured initial normal candidates. The highest
+  priority ready candidate wins; a lower-priority candidate remains held while
+  a higher-priority candidate is still inside its SLA window.
+- At a round boundary, at most one pending normal attempt is promoted to the
+  fallback. The next round uses the remaining slots for new normal candidates,
+  so `discoveryConcurrency=2` means `one fallback + one new candidate`.
+- A fallback that has produced a valid prefix is held until the current normal
+  window closes, all normal candidates fail, or no candidates remain. A normal
+  winner always has precedence during the window.
+- When `bill_hedge_losers` is enabled, a Discovery loser that already produced
+  a protocol-valid prefix and reached ready state may reuse the legacy
+  background drain and billing path. It is billed only after natural stream
+  completion with a completion marker and explicit usage. All other losers are
+  cancelled and their readers/agents/provider-session references are released.
+- Sticky binding is written only after a natural, successful stream completion
+  with the protocol completion marker and a generation-aware CAS. Fake-200,
+  incomplete, and client-aborted streams do not create or renew Sticky.
+
+Discovery is eligible only for supported streaming protocol families and when
+the versioned Redis binding capability is available. If Redis capability is
+unknown/unavailable, the existing provider selection and Hedge behavior remain
+active.
+
+The versioned binding scripts require the canonical binding, legacy provider,
+legacy owner, lease, and cooldown keys to be evaluated atomically. On Redis
+Cluster layouts where those keys do not share a slot and Redis returns
+`CROSSSLOT` (or when Lua capability probing fails), the capability state is
+`unavailable`; the service records that state and uses the tenant-checked
+legacy wrapper. Discovery stays disabled until a later connection-lifecycle
+probe succeeds.
+
+## Rollout
+
+1. Apply the system-settings migration.
+2. Confirm the Redis versioned-binding capability probe is `available`.
+3. Leave `discoveryEnabled=false` while validating the existing Hedge and
+   versioned binding checks.
+4. Enable Discovery for a controlled group, observe provider-chain outcomes,
+   first-token latency, fallback promotions, cancellations, CAS conflicts, and
+   final 503s.
+5. Disable the setting to return immediately to the legacy Hedge path.
+
+This feature does not change the final client failure contract: an exhausted
+request continues to return the existing `503` mapping.

drizzle/0110_daffy_rawhide_kid.sql

@@ -0,0 +1,7 @@
+ALTER TABLE "system_settings" ADD COLUMN "discovery_enabled" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE "system_settings" ADD COLUMN "discovery_concurrency" integer DEFAULT 2 NOT NULL;--> statement-breakpoint
+ALTER TABLE "system_settings" ADD COLUMN "max_discovery_rounds" integer DEFAULT 2 NOT NULL;--> statement-breakpoint
+ALTER TABLE "system_settings" ADD COLUMN "discovery_sla_ms" integer DEFAULT 10000 NOT NULL;--> statement-breakpoint
+ALTER TABLE "system_settings" ADD COLUMN "sticky_sla_ms" integer DEFAULT 20000 NOT NULL;--> statement-breakpoint
+ALTER TABLE "system_settings" ADD COLUMN "racing_total_timeout_ms" integer DEFAULT 60000 NOT NULL;--> statement-breakpoint
+ALTER TABLE "system_settings" ADD COLUMN "sticky_timeout_cooldown_ms" integer DEFAULT 300000 NOT NULL;

drizzle/0111_happy_mauler.sql

@@ -0,0 +1,41 @@
+ALTER TABLE "message_request" ADD COLUMN "routing_trace" jsonb;
+
+-- Routing trace finalization is observability-only. Restrict the ledger trigger
+-- to columns that can actually change its projection so trace-only patches do
+-- not rewrite accounting rows.
+DROP TRIGGER IF EXISTS trg_upsert_usage_ledger ON message_request;
+
+CREATE TRIGGER trg_upsert_usage_ledger
+AFTER INSERT OR UPDATE OF
+  blocked_by,
+  status_code,
+  error_message,
+  provider_chain,
+  actual_response_model,
+  endpoint,
+  provider_id,
+  user_id,
+  "key",
+  model,
+  original_model,
+  api_type,
+  session_id,
+  cost_usd,
+  cost_multiplier,
+  group_cost_multiplier,
+  input_tokens,
+  output_tokens,
+  cache_creation_input_tokens,
+  cache_read_input_tokens,
+  cache_creation_5m_input_tokens,
+  cache_creation_1h_input_tokens,
+  cache_ttl_applied,
+  context_1m_applied,
+  swap_cache_ttl_applied,
+  duration_ms,
+  ttfb_ms,
+  client_ip,
+  created_at
+ON message_request
+FOR EACH ROW
+EXECUTE FUNCTION fn_upsert_usage_ledger();