# Implementation Report
## Summary
This repository now contains an initial Rust library crate for blind watermarking over borrowed RGB8/RGBA8 buffers.
Implemented:
- core public API from the design brief
- `WatermarkConfig`, `WatermarkKey`, strength/profile/color/thread config types
- raw `ImageBufferRef` input and owned `WatermarkedImage` output
- RGB8 and RGBA8 support
- exact RGBA alpha preservation
- capacity reporting
- self-describing payload header with embedded length
- keyed BLAKE3 MAC over header and payload
- key-derived payload whitening
- deterministic key-derived tile permutation
- repeated-bit recovery controlled by `RobustnessProfile`
- luma-only local Haar + 4x4 DCT coefficient-pair embedding
- no unsafe code
- unit and integration tests for round trip, UTF-8, binary payloads, wrong key, capacity, alpha, determinism, invalid images, brightness, small noise, and fixture JPEG editing through the `bwm` binary
## Algorithm
The current v0.1 implementation processes 8x8 tiles. For each selected tile, it converts RGB/RGBA to luma, runs a one-level local Haar transform, applies a 4x4 DCT to the low-frequency subband, and embeds one bit by enforcing a margin between two mid-frequency coefficients. The inverse transforms produce a target luma tile, and RGB channels are shifted by the resulting luma delta.
The implementation intentionally starts with DCT coefficient-pair quantization rather than a full DWT-DCT-SVD port. The public API and module boundaries are prepared for a future SVD or stronger ECC implementation.
## Memory Behavior
The core API borrows the input image and returns an owned output buffer. Per tile, the encoder uses fixed-size stack arrays. It does not allocate full-image float buffers or per-block vectors. Extraction allocates only the decoded candidate payload byte buffer and the deterministic tile permutation.
## Robustness Matrix
Current tests:
| No attack | Covered |
| UTF-8 payload | Covered |
| Wrong key | Covered |
| Mild brightness increase | Covered |
| Small deterministic noise | Covered |
| JPEG recompression | Covered by fixture test at quality 85 |
| Resize down/up | Not yet covered |
| Same-canvas border crop damage | Covered by fixture test at 10% width/height loss |
| Visible occlusion | Covered by fixture test with diagonal scars and a dark rectangle |
| 180-degree rotation | Covered by CLI orientation fallback |
| Shifted crop / arbitrary crop | Not claimed |
| Arbitrary rotation | Not claimed |
## Known Limitations
- no general geometric synchronization, so shifted crop, resize, and arbitrary rotation recovery are not claimed
- no Reed-Solomon/BCH-style ECC yet; current redundancy is repeated-bit majority voting
- image decoding/encoding currently exists only in the `bwm` binary path
- `RobustnessProfile::Robust` uses 75 repeated placements per bit, improving localized damage tolerance at a large capacity cost
- no Rayon parallelism yet
- no criterion benchmarks yet
- `ColorMode::YuvChannels` is reserved and returns a config error
## Next Steps
1. Move image decoding/encoding helpers behind an optional library feature.
2. Add a real ECC layer and interleaving.
3. Benchmark 1024x1024, 1920x1080, and 4096x4096 images.
4. Add optional parallel tile processing while preserving single-thread determinism.
5. Evaluate an SVD-based embedder against the current DCT pair quantizer.