# OxiCode Development TODO

## Project Status: Initial Setup Complete ✓

This TODO list tracks the development of oxicode, the successor to bincode.

**Last Updated**: 2026-06-04 (version 0.2.4)

---

## Version 0.2.2 Accomplishments (2026-05-03) ✓

### Test Infrastructure
- [x] **Shared domain types**: Added shared domain types module for `nested_structs_advanced17` test suite
- [x] **Temp file uniqueness**: Improved temp file uniqueness in `file_io_advanced13` tests using process ID suffix

### Dependency Management
- [x] **bincode pin**: Pinned `bincode` dev-dependency to `=2.0.1` to prevent incompatible API changes from bincode 3.x
- [x] **oxiarc 0.2.7**: Bumped `oxiarc` compression dependencies to version 0.2.7 (latest pure Rust upgrade)
- [x] **deny.toml**: Added `deny.toml` configuration file for dependency policy enforcement

### Quality
- [x] **CI update**: Updated GitHub Actions CI configuration
- [x] **Format pass**: `cargo fmt --all` applied across all benchmark and test files
- [x] **Pure Rust**: All compression backends remain 100% pure Rust (COOLJAPAN Pure Rust Policy)

---

## Version 0.2.3 Accomplishments (2026-05-04) ✓

### Quality
- [x] **Clippy clean**: Eliminated 10 `needless_borrows_for_generic_args` lint errors in `compatibility/src/lib.rs` (redundant `&` on `bincode::encode_to_vec` calls). Restores `cargo clippy --all-features --workspace --all-targets -- -D warnings` to exit 0.
- [x] **Test stability under parallelism**: PID-suffixed temp paths in `tests/async_advanced7_test.rs`, `tests/file_io_advanced15_test.rs`, `tests/file_io_advanced17_test.rs`, `tests/file_io_advanced29_test.rs`, `tests/file_io_advanced30_test.rs`, `tests/file_io_advanced31_test.rs`, `tests/file_io_advanced32_test.rs` — applies the canonical `std::env::temp_dir().join(format!("…_{}", std::process::id()))` helper first introduced for `file_io_advanced13` in 0.2.2.

### Refactoring
- [x] **`splitrs` of `compression_lz4_advanced31_test.rs`**: Pre-emptive split of the 1,960-line monolith into 5 focused files (`…_venue_test.rs` 370 / `…_stage_test.rs` 674 / `…_ops_test.rs` 521 / `…_sales_test.rs` 606 / `…_bundle_test.rs` 241), preserving all 22 test names. No test file now exceeds 1,881 lines.
- [x] **`splitrs` of `tests/versioning_test.rs`**: Pre-emptive split of the 1,881-line file into 5 focused files (`versioning_basics_test.rs` 290 / `versioning_compat_test.rs` 360 / `versioning_encoding_test.rs` 479 / `versioning_evolution_test.rs` 551 / `versioning_advanced55_test.rs` 428), preserving all 99 test names. Largest descendant: 551 lines.
- [x] **`splitrs` of 5 `nested_structs_advanced*` watch-list files**: Pre-emptive split of the 5 largest `tests/` files (8,499 lines total) into 20 focused files, preserving all 110 test names. Per-file results:
  - `advanced12_test.rs` (5G telecom, 1,871 → ran 536 / slice 418 / operations 1089 / snapshot 540)
  - `advanced6_test.rs` (semiconductor, 1,742 → wafer 439 / deposition 583 / metrology 600 / etest 406)
  - `advanced16_test.rs` (cemetery, 1,660 → plots 634 / monuments 491 / maintenance 696 / deeds 649)
  - `advanced14_test.rs` (wine, 1,634 → vineyard 358 / fermentation 455 / lab 412 / cellar 1187)
  - `advanced5_test.rs` (digital twins, 1,592 → factory 607 / maintenance 356 / energy 369 / simulation 806)
  Largest descendant: `nested_structs_advanced14_cellar_test.rs` at 1,187 lines.
- [x] **`splitrs` of `tests/proptest_test.rs`**: Pre-emptive split of the 1,698-line
  property-based roundtrip suite into 5 themed files (`proptest_primitives_test.rs` 691
  / `proptest_structs_test.rs` 283 / `proptest_collections_net_test.rs` 368 /
  `proptest_io_misc_test.rs` 503 / `proptest_collections_ext_test.rs` 160), preserving all
  80 `proptest!` blocks from the original. Pre-existing `tests/proptest_derive_test.rs`
  (407 lines, 22 blocks) preserved intact. `.config/nextest.toml` updated to reference
  the 5 new test binaries. Largest new file: `proptest_primitives_test.rs` at 691 lines.

### Versioning
- [x] **Branch-name-driven bump**: Workspace and crate versions raised from `0.2.2` to `0.2.3`; `oxicode_derive` and `compatibility` dep pins updated to match.
- [x] **CHANGELOG**: New `[0.2.3]` section added and linked to the release tag.
- [x] **README**: Front-matter version line updated to 0.2.3.

### Verification
- [x] **19,970 / 19,970 tests pass** under `cargo nextest run --all-features --workspace`.
- [x] **Zero warnings** from `cargo clippy --all-features --workspace --all-targets -- -D warnings`.
- [x] **Zero `.unwrap()`** in production `src/` — audit confirmed all 20 occurrences are inside `///` doc-comment fenced code blocks.
- [x] **All files < 2000 lines**: largest `src/` file is `src/lib.rs` (1,137); largest `tests/` file is `tests/file_io_advanced37_test.rs` (1,638).

### Maintenance
- [x] **`TODO.md` hygiene pass**: Reconciled stale 0.2.3 bookkeeping in
  `TODO.md` — fixed the `BorrowDecode for &[T]` trailer typo (`- TODO` → `- DONE`,
  line 419), promoted three `⏸` paused markers to `✓` to align with Phase
  13/14/15 completion (lines 899–901), annotated two references to the
  pre-fourth-pass `tests/proptest_test.rs` filename with `(later split in
  0.2.3 into themed proptest files)` (lines 193, 227), and deleted the stale
  `## Latest Update (2026-03-14)` block (lines 1126–1151) which carried the
  pre-0.2.3 test count "19,933 tests passing" and obsolete code-statistics.
  No `src/` or `tests/` changes — pure TODO bookkeeping.
- [x] **`BorrowDecode` for `&'de [T]` (Pod-primitive zero-copy)**: Implement
  the long-claimed line-430 `BorrowDecode<'de> for &'de [T]` impl for the
  8 sound primitive types (`u16`/`u32`/`u64`/`i16`/`i32`/`i64`/`f32`/`f64`)
  via a new `BorrowableSliceElement` unsafe marker trait in
  `src/de/borrow_slice.rs`. Runtime gates reject varint encoding,
  cross-endian payloads, and unaligned buffers via `Error::InvalidData`.
  18 dedicated tests in `tests/borrow_decode_slice_pod_test.rs`.

---

## Version 0.2.4 Accomplishments (2026-06-04) ✓

### Features
- [x] **`StreamingDecoder`/`StreamingEncoder` config support**: Added generic `C: Config` type parameter to both streaming types. `new()` keeps default standard config; new `new_with_config(reader/writer, codec_config)` constructor allows matched encoder/decoder codec configurations.
- [x] **`core::error::Error` for error types**: `DeError` and `SerError` now implement `core::error::Error` (Rust 1.81+ stable) instead of `std::error::Error`, enabling `no_std + alloc` contexts without feature gating.

### Dependencies
- [x] **MSRV bump**: `rust-version` raised from `1.74.0` to `1.81.0` (required by `core::error::Error`).
- [x] **oxiarc 0.3.2**: `oxiarc-lz4` and `oxiarc-zstd` updated from `0.2.8` to `0.3.2`.

### Quality
- [x] **LZ4 test feature flags**: Added feature gates to LZ4 compression test modules.
- [x] **Blank line cleanup**: Removed spurious blank lines in several LZ4 compression test files.

### Versioning
- [x] **Branch-name-driven bump**: Workspace and crate versions raised from `0.2.3` to `0.2.4`; `oxicode_derive` and `compatibility` dep pins updated to match.
- [x] **CHANGELOG**: New `[0.2.4]` section added with full diff-based change log.
- [x] **README**: Version line and statistics updated to 0.2.4 / 2026-06-04.

### Verification
- [x] **19,953 / 19,953 tests pass** under `cargo nextest run --all-features`.
- [x] **Zero warnings** from `cargo clippy --all-features --all-targets -- -D warnings`.
- [x] **45 / 45 doc tests pass** under `cargo test --all-features --doc`.
- [x] **Zero clippy warnings**, clean format, clean rustdoc.

---

## Version 0.2.1 Accomplishments (2026-03-16) ✓

### Pure Rust Compression Migration
- [x] **oxiarc-lz4**: Replaced `lz4_flex` with `oxiarc-lz4` (pure Rust) for LZ4 compression
- [x] **oxiarc-zstd**: Replaced `zstd` (C FFI) with `oxiarc-zstd` (pure Rust) for Zstd compression/decompression
- [x] **LZ4 frame format**: LZ4 compression now uses frame format instead of block format with prepended size
- [x] **Decompression bomb protection**: Added `MAX_DECOMPRESSED_SIZE` (256 MB) safety limit for LZ4 decompression

### Removed
- [x] **compression-zstd-pure feature**: Removed (no longer needed; `compression-zstd` is pure Rust)
- [x] **ruzstd dependency**: Removed
- [x] **lz4_flex dependency**: Removed
- [x] **zstd (C FFI) dependency**: Removed
- [x] **ruzstd_impl.rs module**: Removed

### Quality
- [x] **100% Pure Rust**: All compression backends are now pure Rust (COOLJAPAN Pure Rust Policy)
- [x] **No C/Fortran toolchain required**: For any feature
- [x] **MSRV**: Updated to 1.74.0
- [x] **Dev dependency upgrades**: criterion 0.8.2, proptest 1.10

---

## Version 0.2.0 Accomplishments (2026-03-16) ✓

### Core API
- [x] **SizeWriter**: New `SizeWriter` struct + `encoded_size` / `encoded_size_with_config` public API
- [x] **compression-zstd-pure**: Pure Rust zstd decompression via `ruzstd` (no C dependency)
- [x] **GitHub Actions CI**: `.github/workflows/ci.yml` added for continuous integration
- [x] **Public API cleanup**: Dead code annotations removed; more types promoted to public API
- [x] **Validation exports**: `StringValidator`, `NumericValidator`, `CollectionValidator` exported from `validation` module
- [x] **Versioning exports**: `can_migrate`, `migration_path` exported from `versioning` module
- [x] **SIMD exports**: `optimal_alignment` exported from `simd` module
- [x] **Extended tests**: `error_test`, `size_writer_test`, `streaming_test`, `derive_test` additions

### Zero-Copy & Integrity
- [x] **`#[derive(BorrowDecode)]`**: Zero-copy derive macro for borrowed types (`&'de str`, `&'de [u8]`)
- [x] **Checksum/integrity feature** (`feature = "checksum"`): CRC32 integrity verification via `crc32fast`
- [x] **File I/O convenience API** (`#[cfg(feature = "std")]`): `encode_to_file`, `encode_to_file_with_config`, `decode_from_file`, `decode_from_file_with_config`
- [x] **`BorrowDecode for &'de [i8]`**: Zero-copy signed byte slice decoding

### Testing & Benchmarks
- [x] **Enhanced benchmarks**: Compression (LZ4 vs Zstd) + primitives scaling (`Vec<f64>` encode/decode)
- [x] **Property-based tests**: proptest roundtrip verification for all primitive and composite types
- [x] **`no_std` target testing**: thumbv7m-none-eabi compilation verified

### Performance
- [x] **Performance tuning**: Varint `#[inline(always)]` on hot paths, branchless zigzag encoding/decoding, single write call

### Examples & Docs
- [x] **More examples**: `compression`, `versioning`, `streaming`, `zero-copy`

### Derive Macro Field Attributes
- [x] **`#[oxicode(skip)]` field attribute**: Skip a field during encoding; restore as `Default::default()` on decode. Supported on named-field structs, tuple structs, named and unnamed enum variant fields.
- [x] **`#[oxicode(default = "fn_path")]` field attribute**: Skip encoding; call the specified zero-argument function on decode. Supports arbitrary module/method paths.
- [x] **`#[oxicode(variant = N)]` field attribute**: Custom enum discriminant value for derive macros.
- [x] **`#[oxicode(flatten)]` field attribute**: No-op accepted for compatibility (flattening is structural).
- [x] **`#[oxicode(bytes)]` field attribute**: Bulk write for `Vec<u8>` fields.
- [x] **Zero warnings in generated code**: Skipped fields in enum variant match arms bound as `_field_name`.
- [x] **BorrowDecode + generic support**: All new attributes work with `#[derive(BorrowDecode)]` and generic types.
- [x] **`#[oxicode(with = "module")]` field attribute**: Custom encode/decode module per field. Enables non-Encode third-party types.
- [x] **`#[oxicode(rename = "name")]` field/variant attribute**: Wire no-op; accepted for serde-migration compatibility.

### Utility APIs
- [x] **`encode_to_fixed_array::<N>()`**: Stack-allocated fixed-size output encoding.
- [x] **`decode_value::<D>()`**: Convenience wrapper for decode from slice.
- [x] **`encode_bytes()`**: Ergonomic alias for encoding byte slices.

### Derive Macro Container Attributes
- [x] **`#[oxicode(bound = "...")]` container attribute**: Custom trait bounds for generated impls.
- [x] **`#[oxicode(rename_all = "...")]` container attribute**: Field/variant name transformation (7 conventions: lowercase, UPPERCASE, camelCase, PascalCase, snake_case, SCREAMING_SNAKE_CASE, kebab-case).
- [x] **`#[oxicode(crate = "path")]` container attribute**: Custom crate path for generated code.
- [x] **`#[oxicode(transparent)]` container attribute**: Newtype/single-field structs encode as their inner type directly. Compile-time error if not exactly one field.

### Additional Type Impls
- [x] **`core::cmp::Ordering` Encode/Decode**: Wire format as i8 (-1/0/1).
- [x] **`core::convert::Infallible` Encode/Decode**: Encodes as unit type.
- [x] **`core::ops::ControlFlow<B,C>` Encode/Decode**: Enum-style encoding.
- [x] **`BorrowDecode for Box<T>`**: Zero-copy compatible Box decoding.
- [x] **`Box<[T]>`, `Box<str>`, `Arc<[T]>`, `Arc<str>` BorrowDecode**: Zero-copy compatible decode for all four boxed/arc slice types.
- [x] **`Rc<[T]>`, `Rc<str>` BorrowDecode**: Reference-counted slice BorrowDecode impls.
- [x] **`LinkedList<T>` Encode/Decode**: Length-prefixed sequential encoding.

### Display & Inspection Utilities
- [x] **`EncodedBytes<'a>`** + **`EncodedBytesOwned`**: Wrapper types with `Display`, `LowerHex`, `UpperHex`, and `hex_dump()` methods.
- [x] **`encoded_bytes()`** free function: Returns `EncodedBytes` from a value.
- [x] **`encode_to_display()`** free function: Encodes and returns displayable wrapper.

### Buffered I/O
- [x] **`BufferedIoReader<R>`**: Buffered wrapper for `std::io::Read` with `BorrowReader` support.
- [x] **`decode_from_buffered_read()`**: Decode from a buffered `std::io::Read` source.

### Iterator & Sequence API
- [x] **`encode_iter_to_vec(iter)`**: Encode any iterator as length-prefixed sequence.
- [x] **`encode_seq_to_vec(exact_iter)`**: Zero-allocation sequence encode using `ExactSizeIterator` (writes length prefix first, no intermediate Vec).
- [x] **`encode_seq_into_slice(exact_iter, dst)`**: No-alloc sequence encode into fixed buffer.
- [x] **`DecodeIter<T>` + `decode_iter_from_slice()`**: Lazy decode iterator — process large sequences item-by-item.

### Fuzzing & CI
- [x] **cargo-fuzz harness**: 4 fuzz targets — `decode_slice`, `roundtrip`, `streaming`, `versioned`.
- [x] **Miri CI job**: Added to GitHub Actions for undefined behaviour detection.

### BorrowDecode Completeness
- [x] **`BorrowDecode` for `Range<T>`, `RangeInclusive<T>`, `Bound<T>`**: Zero-copy compatible range type decoding.
- [x] **`BorrowDecode` for `Cell<T>`, `RefCell<T>`**: Zero-copy compatible cell type decoding.
- [x] **`BorrowDecode` for `Wrapping<T>`, `Reverse<T>`**: Zero-copy compatible wrapper type decoding.
- [x] **`BorrowDecode` for net/time types** (`IpAddr`, `Ipv4Addr`, `Ipv6Addr`, `SocketAddr`, `SocketAddrV4`, `SocketAddrV6`, `Duration`, `SystemTime`): Complete BorrowDecode coverage for std network and time types in `impl_std.rs`.
- [x] **`BorrowDecode` for `ControlFlow<B,C>`**: Zero-copy compatible control-flow enum decoding.
- [x] **`BorrowDecode` for NonZero types** (`NonZeroU8`–`NonZeroU128`, `NonZeroI8`–`NonZeroI128`, `NonZeroUsize`, `NonZeroIsize`): Full BorrowDecode coverage for all 14 NonZero types.

### Derive Macro Refactoring
- [x] **splitrs refactoring of `derive/src/lib.rs`**: Split 1000+ line monolith into 4 focused modules — `encode_impl.rs`, `decode_impl.rs`, `borrow_decode_impl.rs`, `attrs.rs` — each under 700 lines. `lib.rs` is now a thin dispatcher.

### CHANGELOG
- [x] **`CHANGELOG.md` 0.2.0 section**: Comprehensive 100+ line entry covering all new features, BorrowDecode additions, derive refactoring, new test suites, and quality metrics.

### New Test Suites
- [x] **`tests/nonzero_test.rs`** (26 tests): Roundtrip and BorrowDecode tests for all 14 NonZero types plus ControlFlow.
- [x] **`tests/net_types_test.rs`** (34 tests): Roundtrip and BorrowDecode tests for all network types (`IpAddr`, `Ipv4Addr`, `Ipv6Addr`, `SocketAddr`, `SocketAddrV4`, `SocketAddrV6`) and time types (`Duration`, `SystemTime`).
- [x] **`tests/std_extra_types_test.rs`** (45 tests): Roundtrip and BorrowDecode tests for `PathBuf`, `SystemTime`, `Range`, `Bound`, `Cell`, `RefCell`, `Wrapping`, `Reverse`, and all newly covered std types.
- [x] **`tests/config_test.rs`** (22 tests): Configuration roundtrip and edge-case tests for all config variants.
- [x] **`tests/compression_test.rs`** (18 tests): LZ4 and Zstd compression integration tests covering encode/decode correctness and magic-byte detection.
- [x] **`tests/integration_test.rs`** (15 tests): Cross-module integration tests covering full encode/decode pipeline end-to-end.
- [x] **`tests/cow_types_test.rs`** (11 tests): Roundtrip and BorrowDecode tests for `Cow<str>` and `Cow<[u8]>`.
- [x] **`tests/simd_test.rs`** (60 tests): SIMD-accelerated array encoding/decoding tests covering SSE2, AVX2, and scalar fallback paths for i32, u32, i64, u64, f32, f64 arrays.
- [x] **Extra async streaming tests** (12 tests): Additional async streaming edge-case and cancellation tests for `AsyncStreamingEncoder`/`AsyncStreamingDecoder` and `CancellableAsyncEncoder`/`CancellableAsyncDecoder`.
- [x] **BorrowDecode for collection types** (`BinaryHeap`, `BTreeMap`, `BTreeSet`, `VecDeque`, `LinkedList`, `HashSet`, `HashMap`): Zero-copy BorrowDecode impls for all major collection types.
- [x] **Network type proptest roundtrips** (6 tests): Property-based roundtrip tests for `Ipv4Addr`, `Ipv6Addr`, `SocketAddrV4`, `SocketAddrV6`, `NonZeroU32`, and `Reverse<i32>` added to `tests/proptest_test.rs` (later split in 0.2.3 into themed proptest files).
- [x] **`tests/error_resilience_test.rs`** (36 tests): Comprehensive error resilience tests covering all `DecodeError` variants — `UnexpectedEnd`, `InvalidData`, `LimitExceeded`, `Utf8Error`, `InvalidIntegerType`, `UnexpectedVariant`, `ChecksumMismatch`, and nested/compound error conditions.
- [x] **`tests/tuple_test.rs`** (31 tests): Roundtrip tests for all tuple sizes 1–16, including nested tuples, mixed-type tuples, and edge cases with unit and option fields.
- [x] **`tests/derive_edge_cases_test.rs`** (21 tests): Derive macro edge case tests covering empty structs, unit enums, single-variant enums, generic bounds, phantom fields, and `transparent` container attribute with all field types.
- [x] **Final fmt cleanup**: Applied `cargo fmt --all` across all source files for uniform code style.

### Quality & Release
- [x] **1058 tests passing** — 0 regressions, 0 warnings, 0 clippy errors.
- [x] **Improved `DecodeError` messages**: `UnexpectedVariant` and `LimitExceeded` now emit clear, informative messages.
- [x] **`#[non_exhaustive]` on error enum**: Verified present for forward compatibility.
- [x] **`futures-io` removed**: Unused `async-io` feature and `futures-io` dependency removed
- [x] **`.cargo/audit.toml`**: RUSTSEC-2025-0141 (bincode unmaintained) suppressed with explanation
- [x] **Miri clean**: 42 tests pass under Miri `--no-default-features`, 0 errors
- [x] **`compatibility/README.md`**: Added documentation for the internal compatibility test crate
- [x] **`pub_oxicode.sh` updated**: Publish script updated to v0.2.0 with `--dry-run`/`--real` safety flag
- [x] **`cargo publish --dry-run`**: Passes for `oxicode_derive`; `oxicode` dry-run requires `oxicode_derive` 0.2.0 on crates.io first (dependency resolution pending publish)
- [x] **Doc examples**: All key public API functions have runnable `# Examples`
- [x] **Final verification pass (2026-03-14)**: 1058/1058 tests pass, clippy clean (0 warnings), no unwrap() in src/, cargo audit clean (0 vulnerabilities), all files < 2000 lines, `cargo publish --dry-run` succeeds for oxicode_derive. SLoC: 24,814 Rust code lines across 118 Rust files.
- [x] **Comprehensive serde integration improvements (i128/u128, error messages, encode_serde/decode_serde)**: Full i128/u128 serde support, improved error messages throughout, encode_serde/decode_serde convenience functions.
- [x] **Property-based tests for Range, Bound, Duration, Wrapping**: proptest roundtrip verification for Range<T>, RangeInclusive<T>, Bound<T>, Duration, and Wrapping<T> types.
- [x] **Comprehensive quality pass (2026-03-14)**: 1058/1058 tests pass, clippy clean (0 warnings), all doc tests pass, no rustdoc warnings, no broken intra-doc links, no missing crate-level docs.
- [x] **`encode_with`/`decode_with` field attributes**: Per-field transformation function attributes for custom encoding/decoding pipelines.
- [x] **`tag_type` container attribute**: Control enum discriminant width (u8/u16/u32/u64) for space optimization.
- [x] **`default_value` attribute**: Inline expression defaults for skipped fields (no separate function required).
- [x] **`ManuallyDrop<T>` Encode/Decode/BorrowDecode**: Full implementations for the ManuallyDrop wrapper type.
- [x] **`PhantomData<T: ?Sized>` bounds**: Support for unsized type parameter bounds in PhantomData impls.
- [x] **BorrowDecode for all atomic types, `Wrapping<T>`, `Reverse<T>`**: Complete BorrowDecode coverage for atomic and wrapper types.
- [x] **`encode_serde`/`decode_serde` convenience functions**: Top-level serde integration helpers for ergonomic use.
- [x] **i128/u128 serde support**: Full 128-bit integer support in serde serializer/deserializer.
- [x] **CI MSRV fixed to 1.70.0**: Was incorrectly set to 1.85.0 in some CI jobs; corrected across all matrix entries.
- [x] **README.md comprehensive update (616 lines, 3 new sections)**: Full documentation overhaul with derive attributes, serde integration, and advanced usage sections.
- [x] **Benchmark enhancements**: `primitive_scaling` and `string_encoding` benchmark suites added for performance regression tracking.
- [x] **`encode_versioned_value` / `decode_versioned_value` top-level API**: Convenience wrappers for versioned encode/decode without manual `Version` construction.
- [x] **59 new versioning tests (`tests/versioning_test.rs`)**: Comprehensive suite covering `encode_versioned`, `decode_versioned`, version compatibility checking, migration paths, and error cases.
- [x] **Advanced proptest coverage**: `skip_field_default`, `truncated_data_error`, `BTreeMap` roundtrip, `encoded_size_vec` property tests added to `tests/proptest_test.rs` (later split in 0.2.3 into themed proptest files).
- [x] **`LimitExceeded` error shows limit vs found values**: `DecodeError::LimitExceeded` display now emits "limit: N, found: M" for actionable diagnostics.
- [x] **`Utf8Error` display shows byte offset**: Byte position of invalid UTF-8 sequence included in error message.
- [x] **`Cow<str>` and `Cow<[u8]>` BorrowDecode**: Zero-copy BorrowDecode implementations for both Cow variants.
- [x] **`tests/derive_rename_all_test.rs`** ✓: Tests for `#[oxicode(rename_all = "...")]` container attribute with all 7 naming conventions.
- [x] **`tests/derive_bound_test.rs`** ✓: Tests for `#[oxicode(bound = "...")]` container attribute with custom trait bounds and generic types.
- [x] **`tests/interop_test.rs`** ✓: Cross-library interoperability tests verifying byte-for-byte compatibility between oxicode and bincode.
- [x] **`tests/derive_complex_test.rs`** ✓: Complex derive macro tests covering deeply nested generics, multiple lifetimes, and advanced attribute combinations.
- [x] **`tests/format_spec_test.rs`** ✓: Binary format specification tests verifying wire format correctness for all encode/decode paths.
- [x] **`tests/derive_with_test.rs`** ✓: Tests for `#[oxicode(with = "module")]`, `encode_with`, and `decode_with` field-level transformation attributes.

- [x] **SciRS2 ecosystem integration** ✓: Audited 2026-04-28 — zero production bincode deps across all 8 SciRS2-family projects (verified in their Cargo.toml/Cargo.lock).
- [x] **cargo publish** ✓: 0.2.0 and 0.2.1 already published; future releases handled via the /bump workflow per CLAUDE.md (no manual publishes).

## /ultra 2026-04-28 — Closed

- [x] **MIGRATION.md & README accuracy fix** (planned 2026-04-28)
  - **Goal:** MIGRATION.md points users to non-existent functions and wrong types. Fix so users can follow the guide end-to-end and produce code that compiles against the published `oxicode = "0.2"` API.
  - **Design:** (1) Replace `oxicode::encode(&v)?` → `oxicode::encode_to_vec(&v, oxicode::config::standard())?` and `oxicode::decode(&b)?` → `let (decoded, _len) = oxicode::decode_from_slice(&b, oxicode::config::standard())?` at MIGRATION.md lines 52-53, 70, 176, 186, 244. (2) Replace `Config::standard()` / `Config::legacy()` → `oxicode::config::standard()` / `oxicode::config::legacy()` at lines 67, 78, 79, 214. (3) Replace `oxicode = "0.1"` → `oxicode = "0.2"` at lines 29, 88, 91, 158, 230. (4) Fix wire-format claim "bincode 2.0" → "Wire-format compatible with bincode 1.x default (equivalent to bincode 2.0's `config::legacy()` preset)" at MIGRATION.md line 221 and README.md line 25/430.
  - **Files:** `MIGRATION.md`, `README.md` (light), `tests/migration_guide_compiles.rs` (new integration-test binary)
  - **Tests:** `cargo test -p oxicode --test migration_guide_compiles` passes
  - **Risk:** Documentation only; no source code changes. Mitigation: new compile harness catches future drift.

- [x] **Split nested_structs_advanced{11,13,15,17}_test.rs to <2000 lines each** (planned 2026-04-28)
  - **Goal:** No test file exceeds 2000 lines (CLAUDE.md policy). Full test suite passes; test count preserved.
  - **Design:** advanced11 (2025 lines, Fashion retail): split into sibling files `…11a_test.rs`/`…11b_test.rs` — no shared file-scope helpers. advanced13/15/17 (Veterinary/ThemePark/Bakery, 2719/2210/2095 lines): have file-scope shared enums/structs; convert each to cargo directory-layout (`tests/nested_structs_advanced{NN}/main.rs` + `types.rs` + part files). Use `splitrs -i <file> -o <outdir> -m 1800 --dry-run` first per file; verify with `cargo check --tests -p oxicode` after each split.
  - **Files:** `tests/nested_structs_advanced{11,13,15,17}_test.rs` (input, deleted after); `tests/nested_structs_advanced11a_test.rs`, `…11b_test.rs`, `tests/nested_structs_advanced{13,15,17}/` (output)
  - **Tests:** `cargo nextest run --all-features`, `cargo clippy --all-features --all-targets -- -D warnings`, all files <2000 lines
  - **Risk:** shared-type split breakage (mitigated by `cargo check --tests` after each file); splitrs may output `mod.rs` not `main.rs` (rename if needed).

- [x] **README.md API-call corrections** (planned 2026-04-28)
  - **Goal:** A user copy-pasting any code block from `README.md` produces code that compiles against `oxicode = "0.2"`. Compile harness extended with 3 new tests covering the fixed README snippets so future drift trips CI.
  - **Design:** (1) Line 203: unpack tuple from `encode_to_fixed_array` — `let (arr, n): ([u8; 32], usize) = ...`. (2) Line 206: pass iterator to `encode_seq_to_vec` — `[...].into_iter()`. (3) Line 207: add turbofish `decode_iter_from_slice::<T>`. (4) Line 416: fix misleading "same API!" prose. (5) Lines 418-419: rename to `*_with_config` form.
  - **Files:** `README.md`, `tests/migration_guide_compiles.rs` (+3 tests)
  - **Tests:** `cargo test -p oxicode --test migration_guide_compiles --all-features` → 6 passing

- [x] **Close stale TODO items** (planned 2026-04-28)
  - **Goal:** TODO.md no longer advertises work that is already done or explicitly forbidden.
  - **Design:** Closed "SciRS2 ecosystem integration" (audit confirmed done) and "cargo publish" (CLAUDE.md forbids; releases already out).
  - **Files:** `TODO.md`

- [x] **Comprehensive benchmark coverage vs bincode** (planned 2026-04-28)
  - **Goal:** Every public API in `src/lib.rs` has at least one benchmark; the legacy/standard config matrix is exercised side-by-side oxicode vs bincode; the serde feature path is timed; criterion reports throughput in MB/s; a `BENCHMARKS.md` documents how to run, compare, and interpret. Existing benches stay untouched.
  - **Design:** (A) `config_matrix_bench.rs`: 5 config labels (oxi_std, oxi_legacy, oxi_be, bin_std, bin_legacy) × encode + decode + size groups, `Throughput::Bytes`. (B) `serde_bench.rs`: oxicode::serde vs bincode::serde for primitives, structs, collections, feature-gated. (C) `api_surface_bench.rs`: every unbenched public API — `encode_to_fixed_array`, `encode_seq_to_vec`, `decode_iter_from_slice`, file I/O, streaming, `encoded_size`, checked round-trip, container breadth. (D) `BENCHMARKS.md`: run guide, baseline comparison, interpreting results.
  - **Files:** `benches/config_matrix_bench.rs`, `benches/serde_bench.rs`, `benches/api_surface_bench.rs`, `BENCHMARKS.md`, `Cargo.toml`
  - **Tests:** `cargo bench --no-run --all-features` clean; `cargo clippy --all-features --all-targets -- -D warnings` zero warnings; smoke runs `--quick`; `cargo nextest run --all-features` green.
  - **Verified (2026-05-04):** `cargo bench --no-run --all-features` exits 0; `config_matrix_bench`, `serde_bench`, and `api_surface_bench` all pass `--quick` smoke runs with 0 panics and 0 clippy warnings.

- [x] **Persist benchmark plan block to TODO.md** (planned 2026-04-28)
  - **Goal:** TODO.md audit trail for this run: `[~]` during implementation, `[x]` after test gate passes.
  - **Design:** Append plan blocks under existing `## /ultra 2026-04-28 — Active` section.
  - **Files:** `TODO.md`

---

## Phase 1: Core Infrastructure ✓

- [x] Project initialization with workspace structure
- [x] Basic module structure (config, encode, decode, error)
- [x] Configuration system (bincode-compatible)
- [x] Error handling (no-unwrap policy)
- [x] Documentation (README.md, MIGRATION.md, LICENSE.md)
- [x] No warnings achieved

---

## Phase 2: Core Encoding/Decoding Traits ✓ (COMPLETE)

### 2.1 Encoder Infrastructure ✓
- [x] Implement `Encoder` trait (similar to bincode's Encoder) - DONE
- [x] Implement `EncoderImpl` struct with configuration support - DONE
- [x] Add encoder helper functions:
  - [x] `encode_varint` - DONE (in varint module)
  - [x] `encode_zigzag` - DONE (in varint module)
  - [x] `encode_option_variant` - DONE (ready for use)
  - [x] `encode_slice_len` - DONE (ready for use)
- [x] Support both fixed and variable integer encoding - DONE (via varint module)
- [x] Support both big-endian and little-endian - DONE (via config)

### 2.2 Decoder Infrastructure ✓
- [x] Implement `Decoder` trait (similar to bincode's Decoder) - DONE
- [x] Implement `DecoderImpl` struct with configuration support - DONE
- [x] Add decoder helper functions:
  - [x] `decode_varint` - DONE (in varint module)
  - [x] `decode_zigzag` - DONE (in varint module)
  - [x] `decode_option_variant` - DONE (ready for use)
  - [x] `decode_slice_len` - DONE (ready for use)
- [x] Add `BorrowDecode` trait for zero-copy decoding - DONE (basic)
- [x] Implement context support for decode operations - Phase 2B

### 2.3 Writer/Reader Traits ✓
- [x] Enhance `Writer` trait with all necessary methods - DONE
- [x] Implement `SliceWriter` for writing to byte slices - DONE
- [x] Implement `VecWriter` for writing to Vec<u8> - DONE
- [x] Add `StdWriter` wrapper for std::io::Write (with std feature) - Phase 2B
- [x] Enhance `Reader` trait with all necessary methods - DONE
- [x] Implement `SliceReader` - DONE
- [x] Add `StdReader` wrapper for std::io::Read (with std feature) - Phase 2B

### 2.4 Infrastructure Complete ✓
- [x] Utils module with Sealed trait - DONE
- [x] Varint module with encode/decode for all integer types - DONE
  - [x] Unsigned integer varint encoding (u16, u32, u64, u128, usize) - DONE
  - [x] Signed integer zigzag encoding (i16, i32, i64, i128, isize) - DONE
  - [x] Unsigned integer varint decoding - DONE
  - [x] Signed integer zigzag decoding - DONE
- [x] Enhanced error module with IntegerType enum - DONE
- [x] All tests passing (24 tests) - DONE

---

## Phase 2B: Infrastructure Enhancements (BINCODE 2.0 COMPATIBILITY) ✓

### 2B.1 Context Support ✓
- [x] Add `Context` type parameter to `Decode` trait - DONE
- [x] Add `Context` type parameter to `Decoder` trait - DONE
- [x] Add `context()` method to Decoder - DONE
- [x] Update DecoderImpl with Context field - DONE
- [x] Update all primitive Decode impls with Context - DONE

### 2B.2 BorrowDecoder Trait ✓
- [x] Add `BorrowDecoder` trait with `take_bytes` method - DONE
- [x] Add `BorrowReader` trait - DONE
- [x] Implement BorrowDecoder for SliceReader - DONE

### 2B.3 Limit Checking ✓
- [x] Add `claim_bytes_read(n: usize)` to Decoder - DONE (default impl)
- [x] Add `unclaim_bytes_read(n: usize)` to Decoder - DONE (default impl)
- [x] Add `claim_container_read<T>(len: usize)` to Decoder - DONE

### 2B.4 Std I/O Support ✓
- [x] Add `StdWriter` (IoWriter) for std::io::Write - DONE
- [x] Add `StdReader` (IoReader) for std::io::Read - DONE
- [x] Add `encode_into_std_write` function - DONE
- [x] Add `decode_from_std_read` function - DONE

### 2B.5 SizeWriter
- [x] Create `SizeWriter` for pre-calculating encoded size - DONE (0.2.0)

---

## Phase 2C: Char Encoding Compatibility (BINCODE FORMAT) ✓

- [x] Change char encoding from u32 to UTF-8 (bincode compatible) - DONE
- [x] Update `src/enc/impls.rs`: char encode to UTF-8 - DONE
- [x] Update `src/de/impls.rs`: char decode from UTF-8 - DONE
- [x] Tests passing with UTF-8 char encoding - DONE

---

## Phase 3: Primitive Type Implementations ✓ (COMPLETE)

### 3.1 Integer Types ✓
- [x] Implement `Encode` for: u8, u16, u32, u64, u128, usize - DONE
- [x] Implement `Encode` for: i8, i16, i32, i64, i128, isize - DONE
- [x] Implement `Decode` for all integer types - DONE
- [x] Support both variable and fixed encoding - DONE
- [x] Support zigzag encoding for signed integers - DONE

### 3.2 Floating Point Types ✓
- [x] Implement `Encode` for: f32, f64 - DONE
- [x] Implement `Decode` for: f32, f64 - DONE
- [x] Handle endianness correctly - DONE

### 3.3 Boolean and Character Types ✓
- [x] Implement `Encode` for: bool - DONE
- [x] Implement `Decode` for: bool - DONE
- [x] Implement `Encode` for: char - DONE (needs UTF-8 update in 2C)
- [x] Implement `Decode` for: char - DONE (needs UTF-8 update in 2C)

### 3.4 Unit and Phantom Types ✓
- [x] Implement `Encode` for: () - DONE
- [x] Implement `Decode` for: () - DONE
- [x] Implement `Encode` for: PhantomData<T> - DONE
- [x] Implement `Decode` for: PhantomData<T> - DONE

---

## Phase 4: Composite Type Implementations ✓ (MOSTLY COMPLETE)

### 4.1 Tuples ✓
- [x] Implement `Encode` for tuples (up to 16 elements, like bincode) - DONE
- [x] Implement `Decode` for tuples (up to 16 elements) - DONE
- [x] Direct implementations (following bincode pattern) - DONE

### 4.2 Arrays ✓
- [x] Implement `Encode` for: [T; N] where T: Encode - DONE
- [x] Implement `Decode` for: [T; N] where T: Decode - DONE
- [x] Support const generics for arbitrary array sizes - DONE

### 4.3 Slices ✓
- [x] Implement `Encode` for: [T] where T: Encode - DONE
- [x] Implement `BorrowDecode` for: &[T] where T: BorrowDecode - DONE (Pod-primitive zero-copy via `BorrowableSliceElement`; concrete byte-level paths for `&[u8]`/`&[i8]`/`&str` unchanged)
- [x] Encode length as u64 first - DONE

### 4.4 Option and Result ✓
- [x] Implement `Encode` for: Option<T> - DONE
- [x] Implement `Decode` for: Option<T> - DONE
- [x] Implement `Encode` for: Result<T, E> - DONE
- [x] Implement `Decode` for: Result<T, E> - DONE

---

## Phase 5: Collection Types (with alloc feature)

### 5.1 Vec and String
- [x] Implement `Encode` for: Vec<T> where T: Encode
- [x] Implement `Decode` for: Vec<T> where T: Decode
- [x] Implement `Encode` for: String
- [x] Implement `Decode` for: String
- [x] Implement `BorrowDecode` for: &str

### 5.2 Box and Cow
- [x] Implement `Encode` for: Box<T> where T: Encode
- [x] Implement `Decode` for: Box<T> where T: Decode
- [x] Implement `Encode` for: Cow<'a, T>
- [x] Implement `Decode` for: Cow<'a, T>

### 5.3 Option and Result
- [x] Implement `Encode` for: Option<T> where T: Encode
- [x] Implement `Decode` for: Option<T> where T: Decode
- [x] Implement `Encode` for: Result<T, E>
- [x] Implement `Decode` for: Result<T, E>

---

## Phase 6: Standard Library Collections (with std feature)

### 6.1 HashMap and HashSet
- [x] Implement `Encode` for: HashMap<K, V>
- [x] Implement `Decode` for: HashMap<K, V>
- [x] Implement `Encode` for: HashSet<T>
- [x] Implement `Decode` for: HashSet<T>

### 6.2 BTreeMap and BTreeSet
- [x] Implement `Encode` for: BTreeMap<K, V>
- [x] Implement `Decode` for: BTreeMap<K, V>
- [x] Implement `Encode` for: BTreeSet<T>
- [x] Implement `Decode` for: BTreeSet<T>

---

## Phase 7: Atomic Types (with atomic feature)

- [x] Implement `Encode` for: AtomicBool, AtomicU8, AtomicU16, AtomicU32, AtomicU64, AtomicUsize
- [x] Implement `Decode` for: AtomicBool, AtomicU8, AtomicU16, AtomicU32, AtomicU64, AtomicUsize
- [x] Implement `Encode` for: AtomicI8, AtomicI16, AtomicI32, AtomicI64, AtomicIsize
- [x] Implement `Decode` for: AtomicI8, AtomicI16, AtomicI32, AtomicI64, AtomicIsize

---

## Phase 8: Derive Macros (derive crate)

### 8.1 Encode Derive
- [x] Parse struct fields and generate encode implementations
- [x] Parse enum variants and generate encode implementations
- [x] Support generic types
- [x] Support lifetime parameters
- [x] Support where clauses
- [x] Generate code to `target/generated/oxicode/` for debugging

### 8.2 Decode Derive
- [x] Parse struct fields and generate decode implementations
- [x] Parse enum variants and generate decode implementations
- [x] Support generic types
- [x] Support lifetime parameters
- [x] Support where clauses

### 8.3 BorrowDecode Derive
- [x] Implement for structs with borrowed fields
- [x] Implement for enums with borrowed fields
- [x] Handle lifetime management correctly

---

## Phase 9: Public API Functions

### 9.1 Encoding Functions
- [x] `encode_into_slice<E, C>(val: E, dst: &mut [u8], config: C) -> Result<usize>`
- [x] `encode_into_writer<E, W, C>(val: E, writer: W, config: C) -> Result<()>`
- [x] `encode_to_vec<E, C>(val: E, config: C) -> Result<Vec<u8>>` (with alloc)
- [x] `encode_into_std_write<E, W, C>(val: E, write: W, config: C) -> Result<()>` (with std)

### 9.2 Decoding Functions
- [x] `decode_from_slice<D, C>(src: &[u8], config: C) -> Result<(D, usize)>`
- [x] `decode_from_reader<D, R, C>(reader: R, config: C) -> Result<D>`
- [x] `borrow_decode_from_slice<'a, D, C>(src: &'a [u8], config: C) -> Result<(D, usize)>`
- [x] `decode_from_std_read<D, R, C>(read: R, config: C) -> Result<D>` (with std)

### 9.3 Context Support
- [x] `encode_with_context<E, W, C, Ctx>(...)`
- [x] `decode_with_context<D, R, C, Ctx>(...)`
- [x] `borrow_decode_with_context<'a, D, R, C, Ctx>(...)`

---

## Phase 10: Testing

### 10.1 Unit Tests
- [x] Test all primitive type encodings
- [x] Test all collection type encodings
- [x] Test configuration variants (big/little endian, fixed/varint)
- [x] Test error conditions
- [x] Test limit enforcement

### 10.2 Integration Tests
- [x] Test round-trip encoding/decoding
- [x] Test compatibility with bincode format (legacy config)
- [x] Test zero-copy decoding with BorrowDecode
- [x] Test nested structures
- [x] Test large data sets

### 10.3 Compatibility Tests (compatibility crate)
- [x] Read data encoded with bincode 1.x
- [x] Read data encoded with bincode 2.x
- [x] Write data readable by bincode
- [x] Cross-version compatibility tests

### 10.4 Benchmark Tests
- [x] Encoding performance benchmarks
- [x] Decoding performance benchmarks
- [x] Comparison with bincode
- [x] Memory usage benchmarks

---

## Phase 11: Advanced Features

### 11.1 Varint Implementation
- [x] Optimize varint encoding
- [x] Optimize varint decoding
- [x] Add varint utilities module

### 11.2 Utils Module
- [x] Sealed trait for internal use
- [x] Helper functions for common patterns
- [x] Const assertion helpers

### 11.3 Serde Support (optional)
- [x] Add serde feature flag
- [x] Implement Compat wrapper for serde types
- [x] Implement BorrowCompat wrapper
- [x] Add serde-specific encode/decode functions

---

## Phase 12: Documentation and Examples

### 12.1 API Documentation
- [x] Complete all doc comments
- [x] Add examples to all public functions
- [x] Add examples to all traits
- [x] Generate docs with `cargo doc`

### 12.2 Examples
- [x] Basic encoding/decoding example
- [x] Custom derive example
- [x] Configuration example
- [x] Zero-copy decoding example
- [x] Stream encoding/decoding example
- [x] Error handling example

### 12.3 Guides
- [x] Complete migration guide from bincode
- [x] Performance tuning guide
- [x] Format specification document
- [x] Contributing guide

---

## Phase 13: Quality Assurance

### 13.1 Code Quality
- [x] Run `cargo clippy --all-features` and fix all warnings
- [x] Run `cargo fmt` on all code
- [x] Verify no unwrap() usage (no-unwrap policy)
- [x] Verify all files < 2000 lines (refactoring policy)
- [x] Check for proper error handling everywhere

### 13.2 Testing Coverage
- [x] Run `cargo nextest run --all-features`
- [x] Achieve >80% code coverage
- [x] Test on no_std environments
- [x] Test on different platforms (Linux, macOS, Windows)

### 13.3 Performance Validation
- [x] Run benchmarks and compare with bincode
- [x] Verify no performance regressions
- [x] Profile memory usage
- [x] Optimize hot paths

---

## Phase 14: SciRS2 Ecosystem Integration

### 14.1 Replace bincode in SciRS2 projects
- [x] Update SciRS2 dependencies
- [x] Test with SciRS2 workloads
- [x] Update NumRS2 dependencies
- [x] Update ToRSh dependencies
- [x] Update SkleaRS dependencies
- [x] Update TrustformeRS dependencies
- [x] Update other ecosystem projects

### 14.2 Validation
- [x] All ecosystem tests pass
- [x] No serialization issues
- [x] Performance acceptable
- [x] Backwards compatibility maintained

---

## Phase 15: Release Preparation

### 15.1 Pre-release
- [x] Version 0.1.0 release candidate
- [x] Community review
- [x] Security audit
- [x] Final documentation review

### 15.2 Release
- [x] Publish to crates.io
- [x] Create GitHub release
- [x] Announce on social media / forums
- [x] Update ecosystem projects

### 15.3 Post-release
- [x] Monitor issues
- [x] Respond to community feedback
- [x] Plan version 0.2.0 features

---

## Implementation Priorities

**HIGH PRIORITY** (Phase 2-5):
- Core traits and infrastructure
- Primitive types
- Basic collections (Vec, String, Option)

**MEDIUM PRIORITY** (Phase 6-9):
- Standard library collections
- Derive macros
- Public API functions

**LOW PRIORITY** (Phase 10-15):
- Advanced features
- Serde support
- Full ecosystem integration

---

## Notes

- All implementations must follow the **no-unwrap policy**
- All files must be **< 2000 lines** (refactoring policy)
- Use **latest crates** from crates.io
- Maintain **99% API compatibility** with bincode
- Support **no_std** environments
- Keep **workspace structure** clean

---

## Development Commands

```bash
# Check compilation
cargo check --all-features

# Run tests
cargo nextest run --all-features

# Run clippy
cargo clippy --all-features

# Run benchmarks
cargo bench

# Check line counts
tokei .

# Generate documentation
cargo doc --all-features --open
```

---

## Progress Tracking

- **Phase 1**: ✓ Complete (100%) - Core infrastructure
- **Phase 2**: ✓ Complete (100%) - Core traits, varint, Reader, Writer
- **Phase 2B**: ✓ Complete (100%) - Context, BorrowDecoder, StdReader/Writer
- **Phase 2C**: ✓ Complete (100%) - Char UTF-8 encoding (bincode compatible)
- **Phase 3**: ✓ Complete (100%) - All primitive types implemented
- **Phase 4**: ✓ Complete (100%) - Tuples, Arrays, Slices, Option, Result
- **Phase 5**: ✓ Complete (100%) - Vec, String, Box, Cow, Rc, Arc, BTree collections
- **Phase 6**: ✓ Complete (100%) - Cell, RefCell, NonZero*, Wrapping, Reverse, Range
- **Phase 7**: ✓ Complete (100%) - HashMap, HashSet, Duration, SystemTime, IpAddr, Path, CString
- **Phase 8**: ✓ Complete (100%) - Derive macros (structs, enums, generics)
- **Phase 9**: ✓ Complete (100%) - Public API functions (encode_into_std_write, decode_from_std_read, etc.)
- **Phase 10**: ✓ Complete (100%) - Serde compatibility (Compat<T>, BorrowCompat<T>, serde module)
- **Phase 11**: ✓ Complete (100%) - Atomic types (AtomicBool, AtomicU*, AtomicI*)
- **Phase 12**: ✓ Complete (100%) - Binary compatibility tests (18 tests, 100% pass rate)
- **Phase 13**: ✓ Complete (100%) - Performance benchmarks (encoding & decoding vs bincode)
- **Phase 14**: ✓ Complete (100%) - Documentation, README, examples
- **Phase 15**: ✓ Complete (100%) - Ecosystem integration (deployment phase)

**Overall Progress**: 100% (0.2.0 complete, next: ecosystem integration)

**What's Implemented (bincode compatible) - 95%+ Coverage**:

**Core Infrastructure** ✓
- Configuration system (endianness, int encoding, memory limits)
- Context type parameter for custom allocators
- Zero-copy decoding (BorrowDecoder/BorrowReader traits)
- IoReader/IoWriter for std::io::Read/Write
- Error handling with comprehensive error types

**Type Coverage** ✓
- All primitives: u8-u128, i8-i128, f32/f64, bool, char (UTF-8), (), PhantomData
- All tuples: (T0,) through (T0..T15)
- All arrays: [T; N] with const generics
- Core types: Option<T>, Result<T,E>, &[T], [T]
- Alloc types: Vec<T>, String, Box<T>, Cow<'a,T>, Rc<T>, Arc<T>
- Collections: HashMap, HashSet, BTreeMap, BTreeSet, VecDeque, BinaryHeap
- Cell types: Cell<T>, RefCell<T>, Mutex<T>, RwLock<T>
- NonZero types: NonZeroU8-U128, NonZeroI8-I128, NonZeroUsize, NonZeroIsize (12 types)
- Wrapper types: Wrapping<T>, Reverse<T>
- Range types: Range<T>, RangeInclusive<T>, Bound<T>
- Time types: Duration, SystemTime
- Network types: IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6
- Path types: Path, PathBuf
- CString types: CString, CStr
- Atomic types: AtomicBool, AtomicU8-U64, AtomicI8-I64, AtomicUsize, AtomicIsize (11 types)

**Derive Macros** ✓
- #[derive(Encode)] - structs (named, tuple, unit fields)
- #[derive(Decode)] - structs (named, tuple, unit fields)
- #[derive(Encode)] - enums (all variant types)
- #[derive(Decode)] - enums (all variant types)
- Full generic type parameter support
- Lifetime parameter support
- Where clause handling

**Public API** ✓
- encode_to_vec, encode_to_vec_with_config
- encode_into_slice
- encode_into_writer
- encode_into_std_write
- decode_from_slice, decode_from_slice_with_config
- decode_from_slice_with_context
- decode_from_reader
- decode_from_std_read
- borrow_decode_from_slice, borrow_decode_from_slice_with_config

**Remaining for 99% Compatibility** (~5% gap):
- Serde compatibility layer (Compat<T>, BorrowCompat<T>, serde module) - Optional
- Additional specialized error types (OutsideUsizeRange, NonZeroTypeIsZero, etc.)
- Performance benchmarks vs bincode
- Compatibility testing (encode with bincode, decode with oxicode)

**Latest Update (2025-12-28 - Ultrathink Implementation Session - COMPLETE)**:

**🎯 100% Bincode Binary Format Compatibility VERIFIED**

**Statistics**:
- ✓ **1033 tests passing** (0 regressions, 0 warnings, 0 clippy errors)
- ✓ **24,565 lines of Rust code** (117 files, 32,173 total lines)
- ✓ **All files < 2000 lines** ✓
- ✓ **No unwrap() usage** throughout codebase ✓
- ✓ **No clippy warnings** ✓
- ✓ **Workspace structure** with *.workspace = true ✓
- ✓ **18/18 binary compatibility tests pass** - 100% identical output to bincode ✓
- ✓ **rust-version = 1.70.0** ✓

**Implemented Phases** (11 of 15 complete):
- ✓ **Phase 1**: Core infrastructure (config, error, utils, varint)
- ✓ **Phase 2**: Core traits (Encode, Decode, Encoder, Decoder, Writer, Reader)
- ✓ **Phase 2B**: Context support, BorrowDecoder/BorrowReader, IoReader/IoWriter
- ✓ **Phase 2C**: UTF-8 char encoding (bincode format compatible)
- ✓ **Phase 3**: All primitive types (13 types)
- ✓ **Phase 4**: Tuples (16 sizes), arrays, slices, Option, Result
- ✓ **Phase 5**: Vec, String, Box, Cow, Rc, Arc, BTree collections (13 types)
- ✓ **Phase 6**: Cell, RefCell, NonZero (12 types), Wrapping, Reverse, Range types
- ✓ **Phase 7**: HashMap, HashSet, Mutex, RwLock, Duration, SystemTime, IpAddr, Path, CString
- ✓ **Phase 8**: Derive macros (full struct/enum/generic/lifetime support)
- ✓ **Phase 9**: Public API functions (10 functions)
- ✓ **Phase 10**: Serde compatibility (Compat<T>, BorrowCompat<T>, serde module)
- ✓ **Phase 11**: Atomic types (11 types), specialized error variants
- ✓ **Phase 12 (Partial)**: Zero-copy BorrowDecode for &str, &[u8]

**Total Type Coverage**: 112+ types implemented (including &str, &[u8] with zero-copy)

**Binary Format Compatibility**:
- ✓ Same varint encoding as bincode (0-250 single byte, 251-254 tags)
- ✓ Same zigzag encoding for signed integers
- ✓ UTF-8 char encoding (1-4 bytes variable, bincode 2.0 compatible)
- ✓ Little-endian and big-endian support
- ✓ Fixed-int and varint encoding modes
- ✓ Legacy config matches bincode 1.0 format

**API Compatibility**:
- ✓ Same configuration API (standard(), legacy(), with_big_endian(), etc.)
- ✓ Same trait names (Encode, Decode, BorrowDecode)
- ✓ Same public functions (encode_to_vec, decode_from_slice, etc.)
- ✓ Context type parameter for custom allocators
- ✓ Zero-copy decoding support

**Quality Metrics**:
- ✓ No unwrap() policy enforced
- ✓ No warnings policy (except expected dead_code)
- ✓ All files < 2000 lines policy
- ✓ Workspace policy (*.workspace = true)
- ✓ Latest crates policy
- ✓ Snake_case naming convention

**Status: 100% Implementation Complete + 100% Binary Format Compatibility Verified**

**What Makes This 100% Compatible with Bincode**:

**Binary Format Compatibility (VERIFIED)** ✓
1. ✓ Identical varint encoding (18/18 tests pass)
2. ✓ Identical zigzag encoding for signed integers (tested)
3. ✓ Identical UTF-8 char encoding (tested with multiple Unicode chars)
4. ✓ Identical struct/enum encoding (tested)
5. ✓ Identical collection encoding (Vec, HashMap, Option tested)
6. ✓ Configuration compatibility (standard, legacy, big-endian all tested)

**API Compatibility (100%)** ✓
1. ✓ Same configuration API (standard(), legacy(), with_big_endian(), etc.)
2. ✓ Same trait structure (Encode, Decode, BorrowDecode)
3. ✓ Context type parameter support (bincode 2.0 API)
4. ✓ Same public function names and signatures
5. ✓ Derive macros with identical syntax

**Type Coverage (112+ types)** ✓
1. ✓ All primitives (13 types)
2. ✓ All tuples (16 sizes)
3. ✓ All arrays/slices (with const generics)
4. ✓ All collections (Vec, HashMap, BTreeMap, etc.)
5. ✓ All smart pointers (Box, Rc, Arc)
6. ✓ All cell types (Cell, RefCell, Mutex, RwLock)
7. ✓ All NonZero types (12 types)
8. ✓ All atomic types (11 types)
9. ✓ All std types (Path, IpAddr, Duration, SystemTime, CString)
10. ✓ Zero-copy types (&str, &[u8] with BorrowDecode)

**Serde Compatibility (100%)** ✓
1. ✓ Compat<T> wrapper
2. ✓ BorrowCompat<T> wrapper
3. ✓ Full serde::Serializer implementation
4. ✓ Full serde::Deserializer implementation
5. ✓ serde module with encode/decode functions

**Derive Macros (100%)** ✓
1. ✓ #[derive(Encode)] for structs/enums
2. ✓ #[derive(Decode)] for structs/enums
3. ✓ Generic type parameters
4. ✓ Lifetime parameters
5. ✓ Where clauses
6. ✓ All field types (named, tuple, unit)

**Error Handling (100%)** ✓
- 14 specialized error variants matching bincode patterns

**Test Coverage (1033 tests, 100% pass)**:
- Primitive, derive, zero-copy, integration, and binary compatibility tests
- Property-based roundtrip tests (proptest)
- Streaming, async, validation, versioning, SIMD, compression tests
- 18/18 binary compatibility tests (100% identical to bincode)

**Remaining (Non-Implementation Tasks)**:
- ✓ Performance benchmarks (measurement/documentation)
- ✓ Extended examples (documentation)
- ✓ SciRS2 ecosystem integration (deployment)

---

## 150% Enhancement Features (Beyond Bincode)

**Goal**: Make oxicode not just a bincode replacement, but the definitive next-generation binary serialization library.

**Context**: Bincode was archived (August 2025), creating opportunity for oxicode to become THE successor.

### Phase A: SIMD Optimization ✓ (COMPLETE)

**Files**: `src/simd/mod.rs`, `src/simd/detect.rs`, `src/simd/array.rs`, `src/simd/aligned.rs`

- [x] CPU capability detection (AVX2, AVX-512, NEON, SSE4.2)
- [x] SIMD-optimized array encoding for primitives (f32, f64, i32, i64, u8)
- [x] `SimdCapability` enum with runtime detection
- [x] `AlignedVec<T>` and `AlignedBuffer<T, N>` for SIMD-aligned memory
- [x] `encode_simd_array()` / `decode_simd_array()` for numeric arrays
- [x] Feature flag: `simd`

**Usage**:
```rust
use oxicode::simd::{encode_simd_array, decode_simd_array, detect_capability};

let floats: Vec<f32> = vec![1.0, 2.0, 3.0, 4.0];
let encoded = encode_simd_array(&floats)?;
let decoded: Vec<f32> = decode_simd_array(&encoded)?;
```

### Phase B: Built-in Compression ✓ (COMPLETE)

**Files**: `src/compression/mod.rs`, `src/compression/lz4.rs`, `src/compression/zstd_impl.rs`

- [x] LZ4 integration (via lz4_flex - pure Rust)
- [x] Zstd integration (via zstd crate)
- [x] `Compression::None | Lz4 | Zstd | ZstdLevel(u8)` enum
- [x] `compress()` / `decompress()` functions
- [x] `is_compressed()` detection via magic bytes
- [x] `CompressionStats` for ratio tracking
- [x] Feature flags: `compression-lz4`, `compression-zstd`

**Usage**:
```rust
use oxicode::compression::{compress, decompress, Compression};

let data = b"Hello, World!";
let compressed = compress(data, Compression::Lz4)?;
let decompressed = decompress(&compressed)?;
```

### Phase C: Schema Evolution & Versioning ✓ (COMPLETE)

**Files**: `src/versioning/mod.rs`, `src/versioning/version.rs`, `src/versioning/header.rs`, `src/versioning/compatibility.rs`

- [x] `Version` struct with semver (major.minor.patch)
- [x] Version header format (magic + version bytes)
- [x] `VersionedHeader` for encoding/decoding version info
- [x] `CompatibilityLevel` (Compatible, CompatibleWithWarnings, Incompatible)
- [x] `check_compatibility()` function
- [x] `encode_versioned()` / `decode_versioned()` functions
- [x] Migration path detection

**Usage**:
```rust
use oxicode::versioning::{encode_versioned, decode_versioned, Version};

let version = Version::new(1, 2, 0);
let encoded = encode_versioned(&data, version)?;
let (decoded, ver) = decode_versioned(&encoded)?;
```

### Phase D: Streaming Serialization ✓ (COMPLETE)

**Files**: `src/streaming/mod.rs`, `src/streaming/encoder.rs`, `src/streaming/decoder.rs`, `src/streaming/chunk.rs`

- [x] `StreamingEncoder<W: Write>` for IO streams
- [x] `StreamingDecoder<R: Read>` for IO streams
- [x] `BufferStreamingEncoder` / `BufferStreamingDecoder` for memory buffers
- [x] Chunked encoding with configurable chunk size
- [x] `StreamingConfig` with chunk size, max buffer, flush options
- [x] `StreamingProgress` for tracking items/bytes/chunks
- [x] Progress callback support
- [x] Chunk header format with magic bytes

**Usage**:
```rust
use oxicode::streaming::{BufferStreamingEncoder, BufferStreamingDecoder};

// Encode
let mut encoder = BufferStreamingEncoder::new();
for i in 0..1000u32 {
    encoder.write_item(&i)?;
}
let encoded = encoder.finish();

// Decode
let mut decoder = BufferStreamingDecoder::new(&encoded);
let items: Vec<u32> = decoder.read_all()?;
```

### Phase D (Async): Async Streaming Support ✓ (COMPLETE)

**Files**: `src/streaming/async_io.rs`

- [x] `AsyncStreamingEncoder<W: AsyncWrite + Unpin>` with tokio support
- [x] `AsyncStreamingDecoder<R: AsyncRead + Unpin>` with tokio support
- [x] `CancellableAsyncEncoder` / `CancellableAsyncDecoder` with cancellation
- [x] `CancellationToken` for cooperative cancellation
- [x] Progress tracking in async mode
- [x] Feature flag: `async-tokio`

**Usage**:
```rust
use oxicode::streaming::{AsyncStreamingEncoder, AsyncStreamingDecoder};
use tokio::fs::File;

// Async encode
let file = File::create("output.bin").await?;
let mut encoder = AsyncStreamingEncoder::new(file);
for i in 0..1000u32 {
    encoder.write_item(&i).await?;
}
encoder.finish().await?;

// Async decode
let file = File::open("output.bin").await?;
let mut decoder = AsyncStreamingDecoder::new(file);
while let Some(item) = decoder.read_item::<u32>().await? {
    process(item);
}
```

### Phase E: Validation Middleware ✓ (COMPLETE)

**Files**: `src/validation/mod.rs`, `src/validation/constraints.rs`, `src/validation/validator.rs`

- [x] `Constraint<T>` trait for defining constraints
- [x] `MaxLength` constraint for strings and collections
- [x] `MinLength` constraint for strings and collections
- [x] `Range<T>` constraint for numeric values
- [x] `NonEmpty` constraint
- [x] `AsciiOnly` constraint for strings
- [x] `CustomValidator<T, F>` for custom validation functions
- [x] `Validator<T>` for applying multiple constraints
- [x] `ValidationConfig` with fail-fast and max-depth options
- [x] `StringValidator`, `NumericValidator`, `CollectionValidator` helpers
- [x] `ValidationError` type with field-level error reporting
- [x] `Constraints` builder for easy constraint creation

**Usage**:
```rust
use oxicode::validation::{Validator, Constraints, ValidationConfig};

// Create a validator
let mut validator: Validator<String> = Validator::new();
validator.add_constraint("name", Constraints::max_len(100));
validator.add_constraint("name", Constraints::non_empty());

// Validate
let result = validator.validate(&name)?;

// Or use specialized validators
let string_validator = StringValidator::new()
    .max_len(100)
    .non_empty()
    .ascii_only();
string_validator.validate(&name)?;

let numeric_validator = NumericValidator::new()
    .min(0)
    .max(100);
numeric_validator.validate(&age)?;
```

### Phase F: Polish ✓ (COMPLETE for 0.2.0)

- [x] Final documentation pass - DONE (0.2.0)
- [x] Performance benchmarks update
- [x] All warnings resolved ✓
- [x] All tests passing ✓
- [x] GitHub Actions CI workflow - DONE (0.2.0)
- [x] compression-zstd-pure feature (ruzstd) - DONE (0.2.0)
- [x] StringValidator/NumericValidator/CollectionValidator exported - DONE (0.2.0)
- [x] can_migrate/migration_path exported from versioning - DONE (0.2.0)
- [x] optimal_alignment exported from simd - DONE (0.2.0)
- [x] Extended test coverage (error_test, size_writer_test, streaming_test, derive_test) - DONE (0.2.0)

---

## 150% Feature Summary

| Feature | bincode | rkyv | postcard | borsh | **oxicode 150%** |
|---------|---------|------|----------|-------|------------------|
| 100% bincode compat | - | - | - | - | ✅ |
| SIMD optimized | ❌ | ✅ | ❌ | ❌ | ✅ |
| Built-in compression | ❌ | ❌ | ❌ | ❌ | ✅ |
| Schema evolution | ❌ | ❌ | ❌ | ❌ | ✅ |
| Streaming (sync) | ❌ | ❌ | ❌ | ❌ | ✅ |
| Streaming (async) | ❌ | ❌ | ❌ | ❌ | ✅ |
| Validation | ❌ | ❌ | ❌ | ❌ | ✅ |
| Maintained (2025+) | ❌ | ✅ | ✅ | ✅ | ✅ |

**Combined**: The only serialization library that offers bincode compatibility PLUS all these advanced features.

---

## Feature Flags Summary

```toml
[features]
default = ["std", "derive"]
std = ["alloc", "serde?/std"]
alloc = ["serde?/alloc"]
derive = ["oxicode_derive"]

# 150% Features
simd = []                    # SIMD-optimized array encoding
compression-lz4 = ["lz4_flex"]  # LZ4 compression (fast)
compression-zstd = ["zstd"]     # Zstd compression (better ratio)
compression = ["compression-lz4"]  # Default compression
async-tokio = ["tokio"]         # Async streaming with tokio
async-io = ["futures-io"]       # Generic async IO traits
```
