# `oska-sys` is the only crate allowed to use `unsafe`

## Decision

Every crate in the workspace forbids `unsafe` code, except one: `oska-sys`, an internal crate that confines filesystem access beneath a directory handle on Unix.

- **It adds no dependencies.** It declares the few C-library functions it needs itself, such as `openat`, and calls them through the C library that `std` already links.
- **It exposes only a safe API.** The runtime opens a root, and opens directories and files beneath it, through a directory handle type. Nothing `unsafe` is public.
- **Every `unsafe` block states its invariant.** Each block holds one unsafe operation and begins with a `// SAFETY:` comment. Clippy's `undocumented_unsafe_blocks` and `multiple_unsafe_ops_per_block` lints enforce both.
- **The exception cannot spread.** The workspace keeps `unsafe_code = "forbid"`, and `oska-sys` is the only crate that does not take the workspace's lints. `scripts/check.sh` runs `scripts/unsafe-guard/guard.sh`, which proves it by compiling: every other crate, every target, is built with `-F unsafe_code` last on rustc's command line, so no manifest, source attribute or flag can allow `unsafe` there, and `--cap-lints` is refused. The guard also refuses a checked-in cargo config and a workflow that sets rustc flags or a wrapper, and scans source the build skips, such as `#[cfg(windows)]` code, for the word `unsafe`. `scripts/unsafe-guard/test.sh` tries each known way around it.

## Why

A directory or file capability must not be steerable outside its root, even by another process that swaps a directory for a symlink while the program runs (#69). The only race-free way to do that is to open each path component relative to a handle for the one before, never following a symlink. On Unix that is `openat` with `O_NOFOLLOW`, one component at a time.

`std` has no `openat`, and it has no way to open a path beneath a directory handle. The usual answer, the `libc` or `rustix` crate, is ruled out because the workspace takes no crates from outside the repo. Calling the C library directly needs `unsafe`. Putting all of it in one small crate keeps the code that needs review in one place, with every invariant written down.

## Considered options

- **Keep path-based checks.** Rejected: checking a path and then opening it are separate steps, and a symlink swapped in between them escapes the root. The checks narrow the window, but they cannot close it.
- **Use the `libc` or `rustix` crate.** Rejected: the workspace takes no external crates.
- **Allow `unsafe` in the runtime crate itself.** Rejected: the exception would cover a large crate, and nothing would keep `unsafe` from spreading through it.
- **Linux `openat2` with `RESOLVE_BENEATH`.** Not needed now. Walking with `openat` works on every Unix target in the release matrix, and `openat2` is Linux-only. It remains an optional speed-up for later.

## Consequences

- **Windows keeps path-based checks.** `oska-sys` is empty there, and a confined capability on Windows checks each component on the path instead. That narrows the race but does not close it, and the docs say so.
- **The platform values are hand-copied.** Flag and error numbers, such as `O_NOFOLLOW` and `ELOOP`, come from each platform's headers. They are declared only for the targets Oska releases for, and any other Unix target fails to compile. CI runs the escape tests on Linux and macOS.
- **Every symlink beneath a root is refused,** including one that points inside the root, because the walk never follows one.