rdb_ocean_last_error Function

   function rdb_ocean_last_error(idx, buf, cap) result(len_out) &
      bind(c, name="rdb_ocean_last_error")
      !! Read the error ring at ring-relative index `idx` (0 = most
      !! recent push). Copies up to `cap` bytes of the trimmed message into
      !! `buf`, NUL-terminating if room remains, and returns the FULL
      !! trimmed message length — a `snprintf`-style contract: a returned
      !! length >= `cap` means the copy was truncated. Returns 0 (buf
      !! untouched) if `idx` is out of `[0, count)` or `cap <= 0`.
      !!
      !! The ring is the ONLY channel a caller should trust for the
      !! SPECIFIC reason behind a coarse status code (D4.3,
      !! `06_python_surface_design.md`) — never scrape stdout.
      integer(c_int), intent(in), value :: idx
      integer(c_int), intent(in), value :: cap
      character(kind=c_char), intent(out) :: buf(cap)
      integer(c_int) :: len_out

      character(len=ERROR_RING_MSG_LEN) :: msg
      integer :: n, ncopy, i

      len_out = 0_c_int
      if (idx < 0_c_int .or. idx >= int(error_ring_count(), c_int) .or. cap <= 0_c_int) return

      msg = error_ring_get(int(idx))
      n = len_trim(msg)
      len_out = int(n, c_int)
      ncopy = min(n, int(cap))
      do i = 1, ncopy
         buf(i) = msg(i:i)
      end do
      if (ncopy < cap) buf(ncopy + 1) = achar(0)
   end function rdb_ocean_last_error