> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bioptimus.observability.fsboundary

Filesystem boundary helpers that translate raw I/O failures into typed errors.

This module centralizes the policy for converting low-level `OSError` and parser exceptions into `BioptimusError` with a stable `ErrorCode`, structured `context`; remediation text lives centrally with the error code.

The two context managers are applied at the exact boundary call (`open`, `yaml.safe_load`, `Path.mkdir`) so that domain logic stays outside the `try` and the translation policy lives in one place rather than being copy-pasted into every reader and writer. The approach mirrors how mature libraries centralize exception translation, for example httpx's `map_httpcore_exceptions` context manager and PyTorch's `_check_seekable` boundary validator.

To keep this module dependency-light (standard library only), parser exception types that are not built in (for example `yaml.YAMLError`) are not imported here; callers pass them via the `malformed` argument of [`fs_read`](/sdk-reference/observability/fsboundary#fs_read).

***

#### fs\_read

```python theme={null}
@contextmanager
def fs_read(
    path: str | Path,
    *,
    description: str,
    malformed: tuple[type[BaseException], ...] = ()
) -> Iterator[None]
```

Translates read and parse failures within the block into typed errors.

Wraps the boundary call that reads or parses *path*. Raw filesystem and parser exceptions are converted into a [`BioptimusValueError`](/sdk-reference/observability/errors#bioptimusvalueerror) with code [`ErrorCode.INVALID_CONFIG`](/sdk-reference/observability/errors#invalid_config), attaching the path and errno to the context and an errno-specific remediation hint when available. Already-typed [`BioptimusError`](/sdk-reference/observability/errors#bioptimuserror) instances raised inside the block propagate unchanged so that domain errors keep their original code.

<ParamField body="path">
  The filesystem path being read, used for structured context.
</ParamField>

<ParamField body="description">
  A short noun phrase naming the artifact, for example `"cohort CSV manifest"`. It is interpolated into the message.
</ParamField>

<ParamField body="malformed">
  Additional, non-built-in exception types (for example `yaml.YAMLError` or `csv.Error`) that signal malformed content and should be reported as [`ErrorCode.INVALID_CONFIG`](/sdk-reference/observability/errors#invalid_config). Built-in `UnicodeDecodeError` is always treated as malformed.
</ParamField>

**Returns**:

A context manager that translates read and parse failures raised inside
the `with` block into a typed [`BioptimusValueError`](/sdk-reference/observability/errors#bioptimusvalueerror) with code
[`ErrorCode.INVALID_CONFIG`](/sdk-reference/observability/errors#invalid_config).

***

#### fs\_write

```python theme={null}
@contextmanager
def fs_write(path: str | Path, *, description: str) -> Iterator[None]
```

Translates write failures within the block into typed errors.

Wraps the boundary call that writes *path*. Raw `OSError` failures are converted into a [`BioptimusRuntimeError`](/sdk-reference/observability/errors#bioptimusruntimeerror): code [`ErrorCode.DISK_FULL`](/sdk-reference/observability/errors#disk_full) when the volume is out of space or over quota, or [`ErrorCode.OUTPUT_WRITE_FAILED`](/sdk-reference/observability/errors#output_write_failed) otherwise, attaching the path to the context. Already-typed [`BioptimusError`](/sdk-reference/observability/errors#bioptimuserror) instances raised inside the block propagate unchanged.

<ParamField body="path">
  The destination path being written, used for structured context.
</ParamField>

<ParamField body="description">
  A short noun phrase naming the artifact, for example `"cohort manifest"`. It is interpolated into the message.
</ParamField>

**Returns**:

A context manager that translates write failures raised inside the
`with` block into a typed [`BioptimusRuntimeError`](/sdk-reference/observability/errors#bioptimusruntimeerror) with code
[`ErrorCode.DISK_FULL`](/sdk-reference/observability/errors#disk_full) or [`ErrorCode.OUTPUT_WRITE_FAILED`](/sdk-reference/observability/errors#output_write_failed).