# Filesystem Preload Primitives
CoreShift-Core provides the low-level file operations used by higher layers to
warm file data. Core does not discover files or decide which files deserve
preload.
## `readahead`
`readahead(fd, offset, len)` asks the kernel to begin reading a byte range for an
open file descriptor.
Callers choose:
- The file descriptor.
- The byte offset.
- The byte length.
Unsupported platforms return `ENOSYS`. Offsets that cannot fit the platform
syscall type return `EINVAL`.
## `fadvise`
`fadvise(fd, offset, len, advice)` wraps `posix_fadvise`, passing the requested
advice through verbatim. Callers choose the fd, byte offset, length, and advice
constant. Unsupported platforms return `ENOSYS`.
## `mmap_madvise`
`mmap_madvise(fd, offset, len, touch)` maps a read-only byte range and applies
`MADV_WILLNEED`.
When `touch` is false, Core maps the range, calls `madvise`, and unmaps it. When
`touch` is true, Core also reads one byte from each page after `madvise` so the
caller can request page touching.
Unsupported platforms return `ENOSYS`.
## Offset Alignment
`mmap` requires page-aligned offsets. Core validates this before calling into the
kernel:
- Page-aligned offsets are allowed.
- Unaligned offsets return `EINVAL`.
- Offsets larger than the platform `off_t` range return `EINVAL`.
Core does not silently widen, shift, or round the request. Policy layers should
align ranges before calling Core when they want a wider mapping.
## Safety and Errors
The mapping is read-only and private to the process. Core unmaps the range before
returning. Errors are reported as `CoreError` values with the platform operation
name, such as `readahead`, `mmap`, or `madvise`.
Higher layers should treat preload as best-effort unless their product policy
requires a hard failure.