/**
 * PoolPollCache — WS4.4(f) global pool-cache unification
 * (MULTI-MACHINE-SEAMLESSNESS-SPEC §WS4.4, normative clause (f)).
 *
 * THE PROBLEM this closes
 * -----------------------
 * Every pool-scope dashboard surface — `GET /sessions?scope=pool`,
 * `/jobs?scope=pool`, `/attention?scope=pool`, `/guards?scope=pool`,
 * `/parallel-work/activities?scope=pool`, `/subscription-pool?scope=pool` —
 * independently fans out to EVERY peer machine and fetches that peer's plain
 * route. With a dashboard polling several of these tabs at once, the SAME peer
 * is hit N times per poll interval (once per surface, per client). On the
 * fronting machine that is wasted egress + wasted peer CPU, and it scales with
 * the number of open dashboard tabs — exactly the "fronting-edge load posture"
 * the spec calls out.
 *
 * THE FIX (spec §WS4.4(f), verbatim intent)
 * -----------------------------------------
 *   "merged pool views (attention/jobs/sessions/guards) are served from ONE
 *    shared per-peer poll cache (one fan-out per interval feeds all pool-scope
 *    surfaces — never per-route, per-client re-fan-out), and when the fronting
 *    machine is over a CPU threshold, dashboard poll responses serve
 *    last-cached data with an explicit staleness tag instead of re-fanning
 *    (load-shed, honestly labeled)."
 *
 * This class is that shared cache. Every pool-scope surface routes its per-peer
 * fetch through `fetchPeer(peerMachineId, routePath, fetcher)`:
 *   - within the poll interval (`ttlMs`), the cached body is returned WITHOUT a
 *     network call — so two surfaces asking the same peer in the same window
 *     share ONE fan-out;
 *   - concurrent callers for the same (peer, route) in flight share ONE
 *     in-flight promise (single-flight) — a burst of tab-loads collapses to one
 *     request;
 *   - when the fronting machine is over the CPU load-shed threshold, a STALE
 *     cached body is returned (tagged `stale: true`) instead of re-fanning —
 *     honest load-shedding; if nothing is cached yet the fetch still runs (a
 *     first read can never be served from an empty cache).
 *
 * SAFETY / SCOPE
 * --------------
 * - Ships DARK behind `multiMachine.seamlessness.ws44PoolCache` (dev-agent
 *   gated, like ws44PoolLinks). When OFF, surfaces never construct/consult this
 *   and keep their existing direct per-peer fetch — byte-identical behavior.
 * - Caches ONLY peer route bodies the surfaces already fetch over the mesh.
 *   It introduces NO new authority, NEVER mutates anything, and NEVER caches
 *   private end-user content (the pool-scope surfaces are operator-Bearer reads
 *   of mesh metadata, not `/view/:id` bodies — those are handled by WS4.4
 *   pool-links, which explicitly never caches private bodies).
 * - A failed fetch is NEVER cached — a transient peer error must not stick for
 *   the whole TTL. The error propagates to the caller, which already classifies
 *   it into its per-peer `failed` list.
 */
export interface PoolPollCacheOptions {
    /** Shared poll interval — within this window a (peer, route) is served from
     *  cache without a network call. Default 3s, matching the per-route caches
     *  the surfaces use today (JOBS_POOL_CACHE_TTL_MS / ATTENTION_POOL_CACHE_TTL_MS). */
    ttlMs?: number;
    /** 1-min load-average-per-core at/above which the fronting machine serves
     *  last-cached (stale) instead of re-fanning. Default 1.5 (the SessionReaper
     *  cpuCriticalLoadPerCore default). */
    loadShedPerCore?: number;
    /** Injectable load reader (testability) — returns 1-min load avg per core. */
    loadReader?: () => number;
    /** Injectable clock (testability). */
    now?: () => number;
}
/** The outcome of a `fetchPeer` call — the body plus how it was served. */
export interface PeerFetchResult<T = unknown> {
    body: T;
    /** `true` when the body is a last-cached value served under load-shed (the
     *  caller surfaces this as an honest staleness tag); `false` when fresh or
     *  served from a within-TTL cache hit. */
    stale: boolean;
    /** how this body was produced: a live network fetch, a within-TTL cache hit,
     *  or a load-shed stale serve. Drives the observability counters. */
    source: 'fetch' | 'cache-hit' | 'load-shed';
}
interface CacheStats {
    /** live network fetches performed. */
    fetches: number;
    /** within-TTL cache hits (a fan-out avoided because the body was fresh). */
    cacheHits: number;
    /** load-shed stale serves (a fan-out avoided under CPU pressure). */
    loadSheds: number;
    /** concurrent callers that joined an in-flight fetch (single-flight). */
    coalesced: number;
    /** fetches that threw (never cached). */
    errors: number;
}
/**
 * One shared cache instance per server. Construct it ONLY when the WS4.4(f)
 * flag resolves on; pass it to RouteContext and let every pool-scope surface
 * route its per-peer fetch through it.
 */
export declare class PoolPollCache {
    private readonly ttlMs;
    private readonly loadShedPerCore;
    private readonly loadReader;
    private readonly now;
    private readonly cpuCount;
    /** keyed by `${peerMachineId}::${routePath}` */
    private readonly entries;
    /** in-flight single-flight promises, same key. */
    private readonly inflight;
    private readonly stats;
    constructor(opts?: PoolPollCacheOptions);
    /** `true` when the fronting machine is over the load-shed threshold. */
    isLoadShedding(): boolean;
    /**
     * Fetch a peer's route body through the shared cache.
     *
     * @param peerMachineId  the peer being polled
     * @param routePath      the plain peer route (e.g. '/jobs') — part of the key
     *                       so two surfaces hitting the SAME peer for DIFFERENT
     *                       routes never collide
     * @param fetcher        performs the actual network fetch + parse; called at
     *                       most once per (peer, route) per TTL window (and shared
     *                       across concurrent callers)
     */
    fetchPeer<T = unknown>(peerMachineId: string, routePath: string, fetcher: () => Promise<T>): Promise<PeerFetchResult<T>>;
    /** Drop the cached entry for a (peer, route) — e.g. when a peer goes offline. */
    invalidate(peerMachineId: string, routePath: string): void;
    /** Read-only observability snapshot for the `/pool/poll-cache` route. */
    snapshot(): {
        enabled: true;
        ttlMs: number;
        loadShedPerCore: number;
        loadPerCore: number;
        loadShedding: boolean;
        cachedKeys: number;
        inflight: number;
        stats: CacheStats;
    };
}
export {};
//# sourceMappingURL=PoolPollCache.d.ts.map