# `text_stream` Module Notes
`text_stream` owns Alma's authoritative UTF-8 text storage. It is deliberately
small: byte coordinates, stream identity, monotonic revisions, and range
validation. Higher layers may plan edits, but this module proves whether bytes
are valid for a concrete stream snapshot.
## Public Shape
- `TextByteStream`: owned UTF-8 text plus `TextStreamId` and `TextRevision`.
- `TextRange`: unchecked half-open byte coordinates.
- `ValidatedTextRange`: ordered, in-bounds, UTF-8-aligned range scoped to one
stream id and revision.
- `TextByteStreamShape`: redacted diagnostic shape.
- `TextStreamError`: closed validation and mutation failures.
Key methods:
- `TextByteStream::new(text)`
- `TextByteStream::from_bytes(bytes)`
- `TextByteStream::as_str()`
- `TextByteStream::revision()`
- `TextByteStream::id()`
- `TextByteStream::validate_range(range)`
- `TextByteStream::validate_validated_range(range)`
- `TextByteStream::insert_str(index, text)`
- `TextByteStream::replace_validated_range(range, text)`
- `TextByteStream::delete_validated_range(range)`
## Invariants
- Text is always valid UTF-8.
- Byte indices are accepted only when they are in bounds and on character
boundaries.
- `TextRevision` is monotonic and never wraps.
- A cloned stream receives a fresh `TextStreamId`; validated ranges do not
silently transfer between allocations.
- `ValidatedTextRange` is a snapshot proof. It becomes stale after any stream
mutation.
- Mutation APIs validate before changing text, so failed edits leave the stream
and revision unchanged.
- `Debug` output exposes shape, not buffer text.
## Boundary Use
Operator resolution and buffer transactions should prefer `ValidatedTextRange`
when they already observed the authoritative stream. The buffer owner must still
call `validate_validated_range` before mutation. That recheck is what prevents a
validated range from becoming ambient authority after another edit, another
buffer, or a stale ECS request.