sequenceDiagram
    participant Client
    participant TextIO as TextIOWrapper
    participant Buf as BufferedReader/Writer
    participant Raw as FileIO
    participant Kernel as OS/Kernel

    rect rgb(235,245,255)
    Note over Client,Kernel: Non-blocking read path (high-level)
    end

    Client->>TextIO: read(size, non_blocking=True)
    TextIO->>Buf: read(size, non_blocking=True)
    alt data in buffer
        Buf-->>TextIO: Option<Some(bytes)>
        TextIO-->>Client: Some(bytes)
    else need raw I/O
        Buf->>Raw: read(size, non_blocking=True)
        Raw->>Kernel: sys_read(non-blocking)
        alt kernel returns bytes
            Kernel->>Raw: bytes
            Raw-->>Buf: Option<Some(bytes)>
            Buf-->>TextIO: Some(bytes)
            TextIO-->>Client: Some(bytes)
        else EAGAIN
            Kernel->>Raw: EAGAIN
            Raw-->>Buf: Option<None>
            Buf-->>TextIO: None
            TextIO-->>Client: None
        end
    end

sequenceDiagram
    participant Writer
    participant BufW as BufferedWriter
    participant Buffer as LocalBuffer
    participant Raw as FileIO
    participant Closer as AtomicCloser

    rect rgb(255,245,235)
    Note over Writer,Closer: Write path with closing coordination
    end

    Writer->>BufW: write(data)
    BufW->>Closer: check closing()
    alt closing true
        BufW->>Closer: spin-wait / short yield
        Closer-->>BufW: still closing -> error
        BufW-->>Writer: raise value/error (write to closed)
    else closing false
        BufW->>Buffer: append data
        BufW->>Raw: flush()
        alt raw write succeeds
            Raw-->>BufW: Ok(n)
            BufW-->>Writer: Some(n)
        else EAGAIN / BlockingIOError
            Raw-->>BufW: BlockingIOError (EAGAIN)
            BufW->>Buffer: shift buffer, update positions
            BufW-->>Writer: raise BlockingIOError (EAGAIN)
        end
    end