/**
 * Heap-size preflight — auto-elevates Node's `--max-old-space-size`
 * to match the repo's size before any heavy work runs.
 *
 * V8 fixes the heap cap at process startup; we can't change it
 * mid-flight. So the only safe way to "auto-set" the heap is to
 * re-exec the process with the right `NODE_OPTIONS` and let the
 * child do the actual work. We guard re-exec with the
 * `OPENSIP_HEAP_ELEVATED` sentinel so the child doesn't loop back into
 * the preflight check.
 *
 * Policy:
 *   - >2500 source files → target 12288 MB cap
 *   - >1000 source files → target 8192 MB cap
 *   - otherwise → keep default (V8's ~4 GB)
 *
 * If total system RAM can't comfortably hold the elevated heap
 * (heap + 2 GB OS headroom), we warn the user and continue at the
 * current heap. The pressure monitor catches the impending OOM
 * gracefully — better than tanking the whole machine into swap.
 */
import { type RunCorrelation } from '@opensip-cli/core';
export interface HeapTarget {
    readonly fileThreshold: number;
    readonly heapMb: number;
}
/** Heap targets in descending order of file threshold. */
export declare const HEAP_TARGETS: readonly HeapTarget[];
export interface PreflightInput {
    readonly cwd: string;
    /** Optional override for the adapter's config-file path. */
    readonly configPathOverride?: string;
    /**
     * When true, print the human-facing "elevating heap" line to stderr. Off
     * by default: the elevation is silent unless `graph --verbose` asked for
     * detail. The structured `graph.heap.preflight.elevate` log is emitted
     * either way, so telemetry / log consumers lose nothing when it's off.
     */
    readonly verbose?: boolean;
}
export interface HeapPreflightDelegation {
    /** Wall-clock boundary used by the host to reject older correlated evidence. */
    readonly startedAt: string;
}
/**
 * Decide the target heap (in MB) for a given file count, or `null` if
 * the default V8 heap is sufficient.
 */
export declare function decideHeapTargetMb(fileCount: number): number | null;
/** Total system RAM in MB. */
export declare function totalSystemMemoryMb(): number;
/**
 * Whether the system has room for a heap of `targetMb` plus
 * `OS_HEADROOM_MB` for everything else.
 */
export declare function systemHasMemoryFor(targetMb: number): boolean;
/**
 * Run preflight. Returns `false` to indicate the caller should
 * continue normally; `true` means the elevated child completed the
 * actual command and the caller must return a delegated completion.
 * That handoff prevents the host from recording a second, evidence-free
 * standalone run for this lightweight parent process.
 */
export declare function runHeapPreflight(input: PreflightInput): Promise<HeapPreflightDelegation | false>;
/**
 * Build the elevated child's environment. The active run correlation is spread
 * after the inherited process environment so stale `OPENSIP_*` values cannot
 * replace the parent scope assembled for this invocation. In particular,
 * `OPENSIP_RUN_ID` lets the child's pre-action hook inherit the same ledger run.
 *
 * Exported from this private module only so the subprocess handoff can be tested
 * without spawning a second Vitest process; it is not part of the package API.
 */
export declare function buildHeapChildEnv(targetMb: number, parentEnv: NodeJS.ProcessEnv, correlation: RunCorrelation | undefined): NodeJS.ProcessEnv;
//# sourceMappingURL=heap-preflight.d.ts.map