# Public API Surface
This audit records the release-facing API shape. The crate is a real
block-device filesystem implementation with C-oracle coverage; the remaining
gaps are about exact littlefs policy fidelity, not whether the public API is
usable.
## Core API
| Geometry and options | `Config`, `FilesystemOptions`, `InlineMax` | Keep. `Config` stays physical geometry; `FilesystemOptions` carries littlefs-style policy. |
| Block devices | `BlockDevice`, `MemoryBlockDevice`, `FileBlockDevice` | Keep. `MemoryBlockDevice` is useful for deterministic tests/integration; `FileBlockDevice` remains `std`-only. |
| Read-only filesystem | `Filesystem::{mount, mount_device, mount_device_with_options, stat, read_dir, read_dir_with, open_dir, read_file, read_file_into, read_file_at, read_attr, read_attr_into, walk, walk_with, used_blocks}` | Keep. Collecting APIs are ergonomic; caller-buffered/visitor APIs are the embedded-facing forms. |
| Formatting and mutable mount | `Filesystem::{format_device, format_device_with_options, mount_device_mut, mount_device_mut_with_options}` | Keep. These are the main user entry points for real block devices. |
| Mutable filesystem | `FilesystemMut::{create_file, write_file, append_file, remove_file, create_dir, remove_dir, rename_file, rename_dir, set_attr, remove_attr, open_file, create_file_writer, sync, into_device}` | Keep. Hidden whole-image fallbacks are removed; unsupported native transaction shapes return `Error::Unsupported`. |
| Handles | `FileOptions`, `FileHandle`, `FileWriter`, `DirHandle` | Keep. These are the stream/cursor APIs users need for nontrivial workloads. |
| Offline image tools | `ImageBuilder`, `ImageEditor` | Keep public for fixtures, host-side conversion, and interop testing. Document them as explicit full-image tools, not mounted block-device APIs. |
| Introspection | `FsInfo`, `FilesystemLimits`, `DirectoryUsage`, `DirEntry`, `WalkEntry`, `FileType` | Keep. These are useful for capacity planning, diagnostics, and tests. |
| Errors | `Error`, `Result` | Keep. The enum is intentionally small and littlefs-errno-like; adding variants later is possible but should be rare. |
## API Cleanup Notes
- No release-facing API currently needs to be hidden immediately.
- `FilesystemMut::as_filesystem` is useful for metadata inspection, but its
`Filesystem<'static>` return shape is an implementation compromise caused by
the owned-device mount. Keep it documented as a metadata view; callers should
read payloads through `FilesystemMut::read_file` or file handles.
- `FilesystemMut::set_block_cycles` is useful for deterministic relocation
tests and controlled deployments, but it should remain a low-level knob.
- `ImageBuilder` and `ImageEditor` are intentionally explicit full-image
utilities. They should not be used inside mounted APIs.
- The ergonomic one-shot methods (`read_file`, `write_file`, `append_file`) are
valuable even though large-file users should prefer handles and caller-owned
buffers for peak memory control.
## Compatibility Promise For This Release Line
- Preserve littlefs v2.1 on-disk compatibility for the documented operations.
- Preserve `no_std + alloc` for library code; `FileBlockDevice` stays behind
the default `std` feature.
- Treat hidden capacity-sized allocation in mounted block-device operations as
a regression.
- Keep C-oracle tests as the compatibility boundary for filesystem-visible
behavior.