import { Worker } from 'node:worker_threads';
/**
 * Build the sub-batch dispatch payload + transferList.
 *
 * For the parse-worker shape `{path, content: string}[]`, encodes each
 * file's content as a `Uint8Array` via `TextEncoder` so the underlying
 * `ArrayBuffer` can be transferred zero-copy. For any other input
 * shape, the items array is passed through verbatim (no transfer).
 *
 * @internal Exported for the unit test suite
 * (`test/unit/worker-pool-transferlist.test.ts`) so the
 * Uint8Array-per-content allocation contract can be pinned without
 * spinning up a real worker_threads.
 */
export declare function buildDispatchMessage<T>(items: readonly T[]): {
    message: {
        type: 'sub-batch';
        files: Array<{
            path: string;
            content: Uint8Array;
        }>;
    } | {
        type: 'sub-batch';
        files: readonly T[];
    };
    transferList?: ArrayBuffer[];
};
export interface WorkerPool {
    /**
     * Dispatch items across workers. Items are split into bounded jobs, each job
     * is committed independently, and stalled jobs are split/retried locally.
     *
     * Files in {@link WorkerPool.getQuarantinedPaths} are filtered out before
     * dispatch — they have already caused a worker death this pool lifetime and
     * are not safe to re-attempt in workers. The caller is responsible for
     * routing them (e.g. to sequential fallback); inspect the quarantine
     * snapshot before and after each dispatch.
     */
    dispatch<TInput, TResult>(items: TInput[], onProgress?: (filesProcessed: number) => void): Promise<TResult[]>;
    /** Terminate all workers. Must be called when done. */
    terminate(): Promise<void>;
    /** Number of worker slots originally requested for the pool. */
    readonly size: number;
    /**
     * Snapshot of paths quarantined by this pool instance. Populated when a
     * worker dies with an authoritative in-flight file (Layer 4 starting-file
     * message) or a singleton-timeout exclusion. Cleared only by pool teardown
     * — quarantine is session-scoped per `createWorkerPool` invocation.
     *
     * Optional so external `WorkerPool` shapes (test doubles, alternate
     * implementations) can omit the method without compile errors. Callers
     * (`processParsing`) use optional chaining at the call site to handle
     * absence gracefully.
     */
    getQuarantinedPaths?(): readonly string[];
    /**
     * Throughput / health snapshot for operator observability. Surfaced at
     * chunk boundaries by `parse-impl` when verbose ingestion is enabled
     * so the operator can see whether workers are saturated, idle, or
     * dropping. Optional for compatibility with external `WorkerPool`
     * shapes that predate this method.
     */
    getStats?(): WorkerPoolStats;
}
/** Snapshot returned by {@link WorkerPool.getStats}. */
export interface WorkerPoolStats {
    /** Worker slots configured at pool creation time. */
    readonly size: number;
    /** Slots that are still in the active rotation (have not been dropped
     *  for exceeding their respawn budget and have not been cleared by
     *  the circuit breaker). */
    readonly activeSlots: number;
    /** Slots permanently removed from rotation this pool lifetime
     *  (size - activeSlots). When the circuit breaker has tripped this
     *  equals `size` because activeSlots is cleared. */
    readonly droppedSlots: number;
    /** Cumulative paths quarantined by failure attribution. */
    readonly quarantined: number;
    /** Whether the circuit breaker has tripped (no further dispatches
     *  will be accepted by this pool instance). */
    readonly poolBroken: boolean;
    /** Whether `terminate()` has been called on this pool. Distinguishes
     *  graceful shutdown (terminated=true, activeSlots=0) from a circuit-
     *  breaker trip (terminated=false, poolBroken=true, activeSlots=0).
     *  Optional for backward compatibility with external `WorkerPoolStats`
     *  implementations that predate this field. */
    readonly terminated?: boolean;
    /** Per-slot generation counter (U12). Increments by 1 on every
     *  successful worker replacement for that slot. Operators / tests
     *  observe this to confirm a death-then-respawn actually happened
     *  vs. the same worker being recycled in place. Initial value is 0
     *  for every slot at pool creation; dropped slots keep their last
     *  generation (they don't decrement). Optional so external
     *  `WorkerPoolStats` implementations that predate U12 can omit the
     *  field without a TypeScript compile error — in-repo callers use
     *  optional chaining (`stats?.slotGenerations`) consistently. */
    readonly slotGenerations?: readonly number[];
}
export interface WorkerPoolOptions {
    subBatchSize?: number;
    subBatchMaxBytes?: number;
    subBatchIdleTimeoutMs?: number;
    maxTimeoutRetries?: number;
    timeoutBackoffFactor?: number;
    /**
     * Max replacement spawns per worker slot before the slot is dropped from
     * the active rotation. Bounds respawn loops on a slot that consistently
     * crashes the worker (likely a system-level fault rather than a single
     * bad input). Default 3.
     */
    maxRespawnsPerSlot?: number;
    /**
     * Hard ceiling on total wall time the pool will spend retrying / splitting
     * any single job. Combined with `timeoutBackoffFactor`, this prevents
     * exponentially-growing retry waits from accumulating into multi-hour
     * stalls before the pool finally surfaces the bad file to sequential
     * fallback. Default 5x `subBatchIdleTimeoutMs`.
     */
    maxCumulativeTimeoutMs?: number;
    /**
     * Number of consecutive worker deaths (no successful job in between) that
     * trip the pool circuit breaker. Once tripped, the pool rejects every
     * subsequent `dispatch` with `WorkerPoolDispatchError` until a new pool is
     * created. Default `Math.max(3, poolSize)`.
     */
    consecutiveFailureThreshold?: number;
    /**
     * Test-only injection point for the Worker constructor. When provided,
     * the pool uses this factory instead of `new Worker(workerUrl)`. Production
     * code should leave this unset.
     */
    workerFactory?: (workerUrl: URL) => Worker;
}
export declare class WorkerPoolDispatchError extends Error {
    /**
     * Snapshot of the pool's session-scoped quarantine at the moment the
     * dispatch error was raised. Surfaced for operator diagnostics: when
     * the circuit breaker trips, this lists the files the pool had
     * already decided were unsafe before the trip. Read-only at the
     * caller boundary; no in-pool consumer rewires it post-construction.
     *
     * Previously named `fallbackExcludePaths` because the (since-
     * removed) sequential-parser fallback in `processParsing` consumed
     * it to filter the fallback file list. After U20's design pivot
     * (worker pool's resilience layers are the sole failure contract;
     * no sequential rescue), the field is informational only. The
     * rename clarifies semantics without changing wire behavior.
     */
    readonly quarantinedPaths: readonly string[];
    constructor(message: string, quarantinedPaths?: readonly string[]);
}
export declare class WorkerPoolInitializationError extends WorkerPoolDispatchError {
    readonly readinessFailures: readonly string[];
    constructor(message: string, quarantinedPaths?: readonly string[], readinessFailures?: readonly string[]);
}
interface ResolvedWorkerPoolOptions {
    subBatchSize: number;
    subBatchMaxBytes: number;
    subBatchIdleTimeoutMs: number;
    maxTimeoutRetries: number;
    timeoutBackoffFactor: number;
    maxRespawnsPerSlot: number;
    maxCumulativeTimeoutMs: number;
    consecutiveFailureThreshold: number;
}
export declare function resolveWorkerPoolOptions(options?: WorkerPoolOptions, poolSize?: number): ResolvedWorkerPoolOptions;
/**
 * Resolve the auto-default worker pool size when no explicit `poolSize`
 * arg is passed to `createWorkerPool`. Precedence:
 *
 * 1. `GITNEXUS_WORKER_POOL_SIZE` env var (operator override; set by
 *    `--workers <N>` on the CLI).
 * 2. `os.cpus().length - 1`, clamped to `[1, DEFAULT_POOL_SIZE_CAP]`.
 *
 * The cap exists because past ~16 workers the main-thread merge /
 * extraction work and structured-clone overhead dominate; adding more
 * worker threads costs memory without much throughput gain. Operators
 * who want to push past the cap set the env var explicitly.
 *
 * Exported for unit tests; production code should not call this
 * directly — pass an explicit `poolSize` to `createWorkerPool` or rely
 * on the env / default.
 */
export declare function resolveAutoPoolSize(): number;
/**
 * Create a pool of worker threads.
 *
 * Resilience model (PR #1693 / 1694):
 * - Layer 1 (auto-respawn): a worker `error`/`exit` triggers a replacement on
 *   the same slot, bounded by {@link WorkerPoolOptions.maxRespawnsPerSlot}.
 *   The slot is dropped from the rotation when its budget is exhausted.
 * - Layer 2 (circuit breaker): `consecutiveFailureThreshold` consecutive
 *   worker deaths (no successful job between) — OR all slots exhausting their
 *   respawn budget — trip the breaker. Every subsequent dispatch rejects
 *   with `WorkerPoolDispatchError` and the caller must build a new pool.
 * - Layer 3 (quarantine): a path identified as the in-flight file at the
 *   time of a worker death is added to `quarantined` and filtered out of
 *   future dispatches. Snapshot via {@link WorkerPool.getQuarantinedPaths}.
 * - Layer 4 (authoritative in-flight): the worker emits a `starting-file`
 *   message before each parse attempt; the pool prefers this for crash
 *   attribution and falls back to {@link inFlightExcludePath} only when no
 *   signal has been observed yet.
 * - Layer 5 (cumulative timeout budget): each job tracks the total wall
 *   time spent across all attempts/splits/retries. When the budget is
 *   exhausted, the pool surfaces the in-flight path via `WorkerPoolDispatchError`
 *   instead of letting timeouts compound indefinitely.
 */
export declare const createWorkerPool: (workerUrl: URL, poolSize?: number, options?: WorkerPoolOptions) => WorkerPool;
export {};
