/**
 * HydrationSandbox — Structured Deadline for Prompt Server-Side Hydration
 *
 * When a user invokes `/morning_briefing`, the prompt handler performs
 * server-side hydration: fetching Jira tickets, Stripe invoices, database
 * queries. If any external source hangs (15s Jira timeout, API 500),
 * the user stares at a frozen UI.
 *
 * This sandbox wraps the handler in a strict `Promise.race` deadline:
 *
 *   ┌─────────────────────────────────────────────────┐
 *   │  Promise.race([                                 │
 *   │    handler(ctx, args),     ← the real work      │
 *   │    deadlinePromise(3s),   ← the safety net      │
 *   │  ])                                             │
 *   │                                                 │
 *   │  Winner:                                        │
 *   │    handler  → return result (happy path)        │
 *   │    deadline → return SYSTEM ALERT (graceful)    │
 *   │    handler throws → return ERROR ALERT (catch)  │
 *   └─────────────────────────────────────────────────┘
 *
 * Three guarantees:
 *   1. The UI unblocks within `deadlineMs` — always.
 *   2. Handler errors become graceful alerts, not -32603 crashes.
 *   3. Timers are cleaned via `finally` — no resource leaks.
 *
 * Design influenced by:
 *   - Go's `context.WithDeadline` (structured cancellation)
 *   - gRPC deadline propagation (strict, per-call)
 *   - Resilience4j's TimeLimiter (JVM circuit breaker pattern)
 *
 * @module
 * @internal
 */
import { type PromptResult } from './types.js';
/**
 * Execute a prompt hydration function within a strict deadline.
 *
 * Uses `Promise.race` between the handler and a timeout promise.
 * Three scenarios:
 *
 * 1. **Handler wins** (completes before deadline) → returns result
 * 2. **Deadline wins** (handler too slow) → returns TIMEOUT alert
 * 3. **Handler throws** (API error, crash) → returns ERROR alert
 *
 * In ALL cases, the caller receives a valid `PromptResult`.
 * The UI never freezes. The user never sees `-32603`.
 *
 * @param fn - The prompt hydration function to execute
 * @param deadlineMs - Maximum time in milliseconds (must be > 0)
 * @returns Always returns a valid PromptResult
 */
export declare function runWithHydrationDeadline(fn: () => Promise<PromptResult>, deadlineMs: number): Promise<PromptResult>;
//# sourceMappingURL=HydrationSandbox.d.ts.map