# API Contracts
Julienne's public API is built around explicit chunking contracts.
## Structured Offset Contract
Every structured chunk preserves a byte range into the original input:
```text
&input[chunk.start_byte..chunk.end_byte] == chunk.text
```
This invariant is covered by tests and fuzzing targets.
## Fallibility
Plain methods are for infallible paths:
- `split_text`
- `split_chunks`
- `chunks`
Fallible paths use `try_*` methods and return `ChunkError`:
- invalid configuration
- regex compilation failure
- parser failure
- unsupported code language
- oversized semantic unit
- invalid token spans
- embedding failure
- sizing failure
## Thread Safety
Public splitter types, builders, and default sizing implementations are intended
to be `Send + Sync` where their configured handles are `Send + Sync`. Custom
length functions and embedders are stored behind `Arc<dyn ... + Send + Sync>` so
configured splitters can be cloned and shared.
## No Silent Degradation
Julienne does not hide provider failures or parser failures by falling back to a
different algorithm. Unsupported languages, parser failures, malformed token
spans, and embedding errors are explicit errors in fallible APIs.
The one intentional semantic fallback is the no-embedder configuration for
`SemanticChunker`: if no embedder is configured, it uses sentence-based packing.
Once an embedder is configured, embedder failures are errors.