# μCOBS (ucobs)

## Identity

- **Crate name**: `ucobs` (on crates.io)
- **Display name**: μCOBS
- **Mission**: Become THE COBS crate for Rust — embedded and non-embedded alike

## First Principles

1. **Correct** — 100% COBS spec-compliant (Cheshire & Baker 1999). No shortcuts, no deviations.
2. **Interoperable** — proven byte-for-byte compatibility with `corncobs`, `cobs` crates and Python `cobs` packages.
3. **Insanely tested** — canonical vectors, property-based tests (proptest), fuzz targets (cargo-fuzz), cross-crate interop, miri, mutation testing, randomized payloads. If you think testing is done, you're 10% done.
4. **Fast** — benchmark against every competing implementation. Must be at least as fast, ideally fastest. Benchmarks run via `just bench`.
5. **Tiny** — `no_std`, zero-alloc, zero runtime dependencies. ~140 lines of implementation. Runs on 8-bit MCUs and servers alike.
6. **Trustworthy** — small enough to audit by hand. No unsafe. No panics in release. Fuzz-hardened.

## Architecture

Single-file library: `src/lib.rs`

### Public API (3 functions)

```rust
pub const fn encode(src: &[u8], dest: &mut [u8]) -> Option<usize>
pub fn decode(src: &[u8], dest: &mut [u8]) -> Option<usize>
pub const fn max_encoded_len(src_len: usize) -> usize
```

**Convention**: Output does NOT include trailing `0x00` sentinel. Caller appends it for framing.

## Development

```sh
# Run all quality gates (tests, clippy, fmt, doc, fuzz, miri, mutants)
just test

# Unit + property + interop tests only
just test-unit

# Benchmarks (iai-callgrind, requires valgrind)
just bench

# Fuzz (requires nightly + cargo-fuzz)
just test-fuzz
```

## Dev Dependencies (test-only)

- `cobs` — cross-validation against the `cobs` 0.5 crate
- `corncobs` — cross-validation against another COBS implementation
- `iai-callgrind` — deterministic instruction-count benchmarks
- `mutants` — mutation testing annotations
- `proptest` — property-based testing
- `rand` — randomized test payloads

## Roadmap

- quickcheck in addition to proptest
- Even more fuzz targets and edge-case generators