/**
 * Minimal handle contract shared by native filesystem adapters.
 *
 * The caller supplies the handle factory so each runtime can choose its native
 * open semantics while this helper owns bounded chunking and cleanup.
 */
export interface BoundedFileReader {
    read(buffer: Uint8Array): Promise<number | null>;
}
export interface BoundedFileReadHandle extends BoundedFileReader {
    close(): void | Promise<void>;
}
/**
 * Run one operation against one opened file handle, then close it exactly once.
 *
 * When the operation and cleanup both fail, the aggregate retains the primary
 * operation failure first and the cleanup failure second.
 */
export declare function withFileHandle<THandle extends {
    close(): void | Promise<void>;
}, TResult>(openHandle: () => Promise<THandle>, operation: (handle: THandle) => Promise<TResult>, aggregateFailureMessage: string): Promise<TResult>;
export declare function requireBoundedFileReadLimit(byteLimit: unknown): number;
/**
 * Read at most `byteLimit` bytes without first materializing the whole file.
 *
 * A full-length result is intentionally ambiguous: callers that need to
 * distinguish an exact-size file from an oversized file request their accepted
 * maximum plus one byte.
 */
export declare function readBoundedFilePrefix(openHandle: () => Promise<BoundedFileReadHandle>, byteLimit: number): Promise<Uint8Array>;
/**
 * Read the complete file only when it fits within `byteLimit`.
 *
 * Unlike a prefix read, reaching the limit triggers one additional EOF probe.
 * The probe reuses the final byte of the accepted buffer, so the helper never
 * retains more than `byteLimit` bytes from the source.
 */
export declare function readFileWithinLimit(openHandle: () => Promise<BoundedFileReadHandle>, byteLimit: number): Promise<Uint8Array>;
/** Read a bounded prefix while leaving ownership of the open handle to the caller. */
export declare function readBoundedFileHandlePrefix(reader: BoundedFileReader, byteLimit: number): Promise<Uint8Array>;
/** Read a complete bounded file while leaving ownership of the handle to the caller. */
export declare function readFileHandleWithinLimit(reader: BoundedFileReader, byteLimit: number): Promise<Uint8Array>;
//# sourceMappingURL=bounded-file-read.d.ts.map