/**
 * V8 heap pressure monitor.
 *
 * Polls `v8.getHeapStatistics()` to catch impending OOMs before V8
 * itself SIGABRTs the process. The orchestrator calls `check()` at
 * every stage boundary; for long-running stages the monitor also
 * self-polls on a 1s interval. When old-gen usage crosses the
 * configured fraction of the heap limit, `check()` throws
 * `MemoryPressureError` and the orchestrator surfaces it through the
 * normal error path.
 *
 * The 0.90 default leaves ~10% of headroom for V8 to complete one
 * last major GC and for the exception to propagate. Below 0.85 we'd
 * get false positives during normal GC churn; above 0.95 the bail-out
 * itself runs out of headroom.
 */
import { ToolError, type EnvVarSpec, type ToolErrorOptions } from '@opensip-cli/core';
/**
 * Graph-engine environment variables (launch, §5.12). Read through the
 * {@link EnvRegistry} primitive (immutable spec table) so the env surface is
 * governed and documentable; the `env-via-registry` guardrail forbids raw
 * `process.env` reads. (`NODE_OPTIONS`, mutated by the heap-preflight before any
 * opensip module loads, is a documented pre-scope exception, not registered here.)
 */
export declare const GRAPH_ENV_SPECS: readonly EnvVarSpec<unknown>[];
/** Read a graph-engine env var through the governed registry (canonical → coerced). */
export declare function readGraphEnv<T = string>(canonical: string): T | undefined;
/** Thrown when heap usage crosses the configured pressure threshold during graph work. */
export declare class MemoryPressureError extends ToolError {
    readonly usedBytes: number;
    readonly limitBytes: number;
    readonly stage: string;
    constructor(message: string, details: {
        usedBytes: number;
        limitBytes: number;
        stage: string;
    }, options?: ToolErrorOptions);
}
/** Constructor options for {@link createPressureMonitor}: threshold and poll cadence. */
export interface PressureMonitorOptions {
    /** Fraction of `heap_size_limit` above which we abort. Default 0.90. */
    readonly threshold?: number;
    /** Background poll interval. 0 disables polling (check-only mode). */
    readonly pollIntervalMs?: number;
}
/** Stage-aware heap-pressure monitor that aborts work before the V8 OOM line. */
export interface PressureMonitor {
    /**
     * Bind the monitor to a logical stage. Subsequent `check()` calls and
     * background polls report this stage in any thrown error.
     */
    readonly setStage: (stage: string) => void;
    /** Synchronous check — throws MemoryPressureError if over threshold. */
    readonly check: () => void;
    /** Stop the background poller. Safe to call multiple times. */
    readonly dispose: () => void;
}
/**
 * Create a pressure monitor. Disabled when `OPENSIP_HEAP_NO_MONITOR=1`
 * — gives users an escape hatch for false positives in unusual GC
 * scenarios (REPL embedding, custom allocators).
 */
export declare function createPressureMonitor(opts?: PressureMonitorOptions): PressureMonitor;
//# sourceMappingURL=pressure-monitor.d.ts.map