# Features
Honest inventory of what `segment-buffer` does, by status. Code is the source of
truth; this file tracks reality, not aspirations.
| FULLY_FUNCTIONAL | Code present and working (tests pass, or exercised in prod). |
| PARTIALLY_FUNCTIONAL | Ships but has documented gaps or edge-case limitations. |
| PLANNED | Designed or discussed; no code yet. |
| WORTH_CONSIDERING | Raw idea, not yet designed. |
## Core queue
| Durable bounded queue (`SegmentBuffer<T>`) | FULLY_FUNCTIONAL | Generic over `T: Serialize + DeserializeOwned + Clone + Send + 'static`. Proven on 597M+ events in monitor365. |
| Append with sequence-number assignment (`append`) | FULLY_FUNCTIONAL | Sequence numbers computed atomically inside the mutex (concurrency bug fixed; see CHANGELOG). |
| Batch + interval auto-flush (`flush`) | FULLY_FUNCTIONAL | Configurable via `max_batch_events` and `flush_interval_secs`. |
| Range read across disk + memory (`read_from`) | FULLY_FUNCTIONAL | Merges on-disk segments with the in-memory tail, in ascending sequence order. |
| Ack-based segment deletion (`delete_acked`) | PARTIALLY_FUNCTIONAL | Removes flushed segment files only; unflushed in-memory items remain until flushed (documented, count stays honest via head_seq clamp). |
| Backlog size (`pending_count`, `len`, `is_empty`) | FULLY_FUNCTIONAL | `next_seq - head_seq`; honest even when acks race unflushed items. `len`/`is_empty` added as standard-collection aliases in 0.2.0. |
| Atomic snapshot (`stats` → `BufferStats`) | FULLY_FUNCTIONAL | Single-lock snapshot of pending/latest/head/next seq + disk bytes + pressure. Added in 0.2.0. |
| Backpressure metrics (`store_pressure`, `is_overloaded`) | FULLY_FUNCTIONAL | Ratio of `approx_disk_bytes` to `max_size_bytes`. Admission policy is caller-defined. |
| Compile-time `Send + Sync` of `SegmentBuffer<T>` | FULLY_FUNCTIONAL | Static assertion in `lib.rs` — adding a non-thread-safe field fails the build. Added in 0.2.0. |
## Storage format
| zstd + CBOR segment files | FULLY_FUNCTIONAL | `seg_{start:012}_{end:012}.zst`, configurable `compression_level` (1-22). |
| **Format envelope (`SBF1` magic + version)** | FULLY_FUNCTIONAL | 8-byte header; forward-evolvable without breaking legacy readers. |
| **Envelope hardening** | FULLY_FUNCTIONAL | Reserved-bytes-zero check drops legacy _encrypted_ false-positive rate from 2⁻³² to 2⁻⁵⁶. Added in 0.2.0. |
| **Legacy file compatibility (unencrypted)** | FULLY_FUNCTIONAL | Pre-envelope (monitor365) files auto-detected; zero migration. Covered by `legacy_envelopeless_file_still_reads`. |
| **Legacy file compatibility (encrypted)** | FULLY_FUNCTIONAL | Covered by `legacy_encrypted_file_without_envelope_still_reads` in 0.2.0 (previously untested). |
| Filename-based crash recovery | FULLY_FUNCTIONAL | No WAL, no metadata DB. `open()` scans filenames to rebuild `head_seq`/`next_seq`. |
| Atomic write (tmp → fsync → rename) | FULLY_FUNCTIONAL | A crash never leaves a partial segment; `.tmp` debris is cleaned on `open()`. |
| Mutex-never-held-across-I/O invariant | FULLY_FUNCTIONAL | `flush()` drops the lock before `write_segment`; `recover()` drops it across the `fs::metadata` loop (fixed in 0.2.0). |
| Crash-recovery limitation | PARTIALLY_FUNCTIONAL | Unflushed in-memory items are lost on crash (by design — durability requires flush). |
## Encryption
| `SegmentCipher` trait (pluggable AEAD) | FULLY_FUNCTIONAL | Always available; bring any `Send + Sync` encrypt/decrypt impl. |
| `AesGcmCipher` (AES-256-GCM, random 12-byte nonce) | FULLY_FUNCTIONAL | Behind the `encryption` feature. Byte-compatible with monitor365's segment format. |
| Opaque `CipherError` with `source()` chaining | FULLY_FUNCTIONAL | `with_source` preserves the underlying AEAD error. Added in 0.2.0 (breaking). |
## Concurrency & operations
| MPMC via `parking_lot::Mutex` | FULLY_FUNCTIONAL | Multiple writers and readers; mutex never held across file I/O. |
| `tracing` instrumentation (`debug` / `info`) | FULLY_FUNCTIONAL | Flush, delete, and recovery events are logged. |
| Typed errors with segment-path context | FULLY_FUNCTIONAL | `Cbor`/`Cipher`/`Integrity` carry the offending file path + phase. |
| Criterion benchmarks (append, read_from, delete_acked, recover) | FULLY_FUNCTIONAL | `cargo bench --bench <name>`; shared helpers in `benches/support.rs`. |
| CI matrix (ubuntu/macos × stable/1.85, `-D warnings`) | FULLY_FUNCTIONAL | Dedicated MSRV (1.85) verification job. |
## Testing & trust
| Unit tests (40+) + doc tests (15) | FULLY_FUNCTIONAL | CRUD, partial reads, limits, crash recovery, concurrency, error paths, envelope detection, encrypted-legacy read. |
| Property tests (`proptest`, 8 properties) | FULLY_FUNCTIONAL | Filename bijection, payload bijection, envelope identity, encrypted roundtrip with varied key, corrupted-segment/recovery analogues. |
| Fuzz targets (`cargo-fuzz`) | FULLY_FUNCTIONAL | Scaffold in `fuzz/`; verified locally via Nix `devShells.fuzz` (nightly + `libfuzzer-sys`). `fuzz_corrupted_read`: 187,811 runs / 60s, 392 coverage blocks, no crashes. `fuzz_recovery`: 942,719 runs / 60s, no crashes. Not yet integrated into CI (planned: nightly scheduled workflow). Proptest analogues run on every `cargo test` as additional coverage. |
| Loom concurrency verification | PLANNED | Exhaustive schedule check of `append`/`flush`/`delete_acked` not yet in place. |
## Planned / worth considering
See [ROADMAP.md](ROADMAP.md) for long-term direction (async I/O, ChaCha20-Poly1305, pluggable segment store, fuzzing harness) and [TODO_LIST.md](TODO_LIST.md) for short/mid-term work.