/// @module std::core::io
/// File System, Network, and Process I/O
///
/// Comprehensive I/O operations including file handles, path manipulation,
/// TCP/UDP networking, process management, and async file operations.
///
/// # Example
///
/// ```shape
/// use std::core::io
///
/// let handle = io.open("data.txt", "r")
/// let content = io.read(handle)
/// io.close(handle)
///
/// let dir = io.dirname("/home/user/file.txt")
/// let exists = io.exists("/tmp/test")
/// ```
// === File handle operations ===
/// Open a file and return a handle.
///
/// # Arguments
///
/// * `path` - File path to open
/// * `mode` - Open mode: "r" (default), "w", "a", "rw"
///
/// # Returns
///
/// An `IoHandle` for the opened file.
pub builtin fn open(path: string, mode: string) -> _;
/// Read from a file handle (n bytes or all).
///
/// # Arguments
///
/// * `handle` - File handle from io.open()
/// * `n` - Number of bytes to read (omit for all)
///
/// # Returns
///
/// String contents read from the file.
pub builtin fn read(handle: _, n: int) -> string;
/// Read entire file as a string.
///
/// # Arguments
///
/// * `handle` - File handle from io.open()
///
/// # Returns
///
/// Full file contents as a string.
pub builtin fn read_to_string(handle: _) -> string;
/// Read bytes from a file as array of ints.
///
/// # Arguments
///
/// * `handle` - File handle from io.open()
/// * `n` - Number of bytes to read (omit for all)
///
/// # Returns
///
/// Array of byte values.
pub builtin fn read_bytes(handle: _, n: int) -> Array<int>;
/// Write string or bytes to a file.
///
/// # Arguments
///
/// * `handle` - File handle from io.open()
/// * `data` - Data to write
///
/// # Returns
///
/// Number of bytes written.
pub builtin fn write(handle: _, data: string) -> int;
/// Close a file handle.
///
/// # Arguments
///
/// * `handle` - File handle to close
///
/// # Returns
///
/// `true` if the handle was successfully closed.
pub builtin fn close(handle: _) -> bool;
/// Flush buffered writes to disk.
///
/// # Arguments
///
/// * `handle` - File handle to flush
pub builtin fn flush(handle: _) -> _;
// === Stat operations ===
/// Check if a path exists.
///
/// # Arguments
///
/// * `path` - Path to check
///
/// # Returns
///
/// `true` if the path exists.
pub builtin fn exists(path: string) -> bool;
/// Get file/directory metadata.
///
/// # Arguments
///
/// * `path` - Path to stat
///
/// # Returns
///
/// Object with file metadata.
pub builtin fn stat(path: string) -> _;
/// Check if path is a file.
///
/// # Arguments
///
/// * `path` - Path to check
///
/// # Returns
///
/// `true` if the path is a regular file.
pub builtin fn is_file(path: string) -> bool;
/// Check if path is a directory.
///
/// # Arguments
///
/// * `path` - Path to check
///
/// # Returns
///
/// `true` if the path is a directory.
pub builtin fn is_dir(path: string) -> bool;
// === Directory operations ===
/// Create a directory.
///
/// # Arguments
///
/// * `path` - Directory path to create
/// * `recursive` - Create parent directories if needed (default: false)
pub builtin fn mkdir(path: string, recursive: bool) -> _;
/// Remove a file or directory.
///
/// # Arguments
///
/// * `path` - Path to remove
pub builtin fn remove(path: string) -> _;
/// Rename/move a file or directory.
///
/// # Arguments
///
/// * `old` - Current path
/// * `new_path` - New path
pub builtin fn rename(old: string, new_path: string) -> _;
/// List directory contents.
///
/// # Arguments
///
/// * `path` - Directory path to list
///
/// # Returns
///
/// Array of entry names.
pub builtin fn read_dir(path: string) -> Array<string>;
// === Path operations ===
/// Join path components.
///
/// # Arguments
///
/// * `parts` - Path components to join (variadic)
///
/// # Returns
///
/// Joined path string.
pub builtin fn join(parts: string) -> string;
/// Get parent directory of a path.
///
/// # Arguments
///
/// * `path` - File path
///
/// # Returns
///
/// Parent directory path.
pub builtin fn dirname(path: string) -> string;
/// Get filename component of a path.
///
/// # Arguments
///
/// * `path` - File path
///
/// # Returns
///
/// Filename portion of the path.
pub builtin fn basename(path: string) -> string;
/// Get file extension.
///
/// # Arguments
///
/// * `path` - File path
///
/// # Returns
///
/// Extension string (without dot).
pub builtin fn extension(path: string) -> string;
/// Resolve/canonicalize a path.
///
/// # Arguments
///
/// * `path` - Path to resolve
///
/// # Returns
///
/// Absolute, canonical path.
pub builtin fn resolve(path: string) -> string;
// === TCP operations ===
/// Connect to a TCP server.
///
/// # Arguments
///
/// * `addr` - Address to connect to (e.g. "127.0.0.1:8080")
///
/// # Returns
///
/// An IoHandle for the TCP stream.
pub builtin fn tcp_connect(addr: string) -> _;
/// Bind a TCP listener.
///
/// # Arguments
///
/// * `addr` - Address to bind (e.g. "0.0.0.0:8080")
///
/// # Returns
///
/// An IoHandle for the TCP listener.
pub builtin fn tcp_listen(addr: string) -> _;
/// Accept an incoming TCP connection.
///
/// # Arguments
///
/// * `listener` - TcpListener handle from io.tcp_listen()
///
/// # Returns
///
/// An IoHandle for the accepted TCP stream.
pub builtin fn tcp_accept(listener: _) -> _;
/// Read from a TCP stream.
///
/// # Arguments
///
/// * `handle` - TcpStream handle
/// * `n` - Max bytes to read (default 65536)
///
/// # Returns
///
/// String data read from the stream.
pub builtin fn tcp_read(handle: _, n: int) -> string;
/// Write to a TCP stream.
///
/// # Arguments
///
/// * `handle` - TcpStream handle
/// * `data` - Data to send
///
/// # Returns
///
/// Number of bytes written.
pub builtin fn tcp_write(handle: _, data: string) -> int;
/// Close a TCP handle.
///
/// # Arguments
///
/// * `handle` - TCP handle to close
///
/// # Returns
///
/// `true` if successfully closed.
pub builtin fn tcp_close(handle: _) -> bool;
// === UDP operations ===
/// Bind a UDP socket.
///
/// # Arguments
///
/// * `addr` - Address to bind (e.g. "0.0.0.0:0" for ephemeral)
///
/// # Returns
///
/// An IoHandle for the UDP socket.
pub builtin fn udp_bind(addr: string) -> _;
/// Send a UDP datagram.
///
/// # Arguments
///
/// * `handle` - UdpSocket handle
/// * `data` - Data to send
/// * `target` - Target address (e.g. "127.0.0.1:9000")
///
/// # Returns
///
/// Number of bytes sent.
pub builtin fn udp_send(handle: _, data: string, target: string) -> int;
/// Receive a UDP datagram.
///
/// # Arguments
///
/// * `handle` - UdpSocket handle
/// * `n` - Max receive buffer size (default 65536)
///
/// # Returns
///
/// Object with received data and sender address.
pub builtin fn udp_recv(handle: _, n: int) -> _;
// === Process operations ===
/// Spawn a subprocess with piped I/O.
///
/// # Arguments
///
/// * `cmd` - Command to execute
/// * `args` - Command arguments
///
/// # Returns
///
/// An IoHandle for the spawned process.
pub builtin fn spawn(cmd: string, args: Array<string>) -> _;
/// Run a command and capture output.
///
/// # Arguments
///
/// * `cmd` - Command to execute
/// * `args` - Command arguments
///
/// # Returns
///
/// Object with `stdout`, `stderr`, and `status` fields.
pub builtin fn exec(cmd: string, args: Array<string>) -> _;
/// Wait for a process to exit.
///
/// # Arguments
///
/// * `handle` - Process handle from io.spawn()
///
/// # Returns
///
/// Exit code of the process.
pub builtin fn process_wait(handle: _) -> int;
/// Kill a running process.
///
/// # Arguments
///
/// * `handle` - Process handle from io.spawn()
pub builtin fn process_kill(handle: _) -> _;
/// Write to a process stdin.
///
/// # Arguments
///
/// * `handle` - Process handle
/// * `data` - Data to write to stdin
///
/// # Returns
///
/// Number of bytes written.
pub builtin fn process_write(handle: _, data: string) -> int;
/// Read from a process stdout.
///
/// # Arguments
///
/// * `handle` - Process handle
/// * `n` - Max bytes to read (default 65536)
///
/// # Returns
///
/// String data read from stdout.
pub builtin fn process_read(handle: _, n: int) -> string;
/// Read from a process stderr.
///
/// # Arguments
///
/// * `handle` - Process handle
/// * `n` - Max bytes to read (default 65536)
///
/// # Returns
///
/// String data read from stderr.
pub builtin fn process_read_err(handle: _, n: int) -> string;
/// Read one line from process stdout.
///
/// # Arguments
///
/// * `handle` - Process handle
///
/// # Returns
///
/// One line of text from stdout.
pub builtin fn process_read_line(handle: _) -> string;
// === Standard stream operations ===
/// Get handle for current process stdin.
///
/// # Returns
///
/// An IoHandle for stdin.
pub builtin fn stdin() -> _;
/// Get handle for current process stdout.
///
/// # Returns
///
/// An IoHandle for stdout.
pub builtin fn stdout() -> _;
/// Get handle for current process stderr.
///
/// # Returns
///
/// An IoHandle for stderr.
pub builtin fn stderr() -> _;
/// Read a line from a handle or stdin.
///
/// # Arguments
///
/// * `handle` - Handle to read from (default: stdin)
///
/// # Returns
///
/// One line of text.
pub builtin fn read_line(handle: _) -> string;
// === Async file I/O operations ===
/// Asynchronously read entire file as a string.
///
/// # Arguments
///
/// * `path` - File path to read
///
/// # Returns
///
/// File contents as a string.
pub builtin fn read_file_async(path: string) -> string;
/// Asynchronously write a string to a file.
///
/// # Arguments
///
/// * `path` - File path to write
/// * `data` - Data to write
///
/// # Returns
///
/// Number of bytes written.
pub builtin fn write_file_async(path: string, data: string) -> int;
/// Asynchronously append a string to a file.
///
/// # Arguments
///
/// * `path` - File path to append to
/// * `data` - Data to append
///
/// # Returns
///
/// Number of bytes written.
pub builtin fn append_file_async(path: string, data: string) -> int;
/// Asynchronously read file as raw bytes.
///
/// # Arguments
///
/// * `path` - File path to read
///
/// # Returns
///
/// Array of byte values.
pub builtin fn read_bytes_async(path: string) -> Array<int>;
/// Asynchronously check if a path exists.
///
/// # Arguments
///
/// * `path` - Path to check
///
/// # Returns
///
/// `true` if the path exists.
pub builtin fn exists_async(path: string) -> bool;
// === Gzip file I/O ===
/// Read a gzip-compressed file and return decompressed string.
///
/// # Arguments
///
/// * `path` - Path to gzip file
///
/// # Returns
///
/// Decompressed file contents as a string.
pub builtin fn read_gzip(path: string) -> string;
/// Compress a string with gzip and write to a file.
///
/// # Arguments
///
/// * `path` - Output file path
/// * `data` - String data to compress and write
/// * `level` - Compression level 0-9 (default: 6)
pub builtin fn write_gzip(path: string, data: string, level: int) -> _;