From f4cd83dbb7792552186a1ff401d780ee2f91f9b3 Mon Sep 17 00:00:00 2001 From: Carlos Rolo Date: Mon, 23 Feb 2026 13:23:32 +0000 Subject: [PATCH 1/4] Agents.md --- AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e97b0e9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# Agents Guide (fft-compression / ATSC workspace) + +This repository is a Rust workspace containing ATSC (Advanced Time Series Compressor) and supporting crates. This file provides **project-specific guidance and guardrails** for AI-assisted changes, especially around on-disk formats and performance-sensitive code. + +## Codebase map (high-signal entry points) + +- **CLI**: `atsc/src/main.rs` + - Reads `.wbro` or `.csv`, produces `.bro` (values) and `.vsri` (timestamps when CSV). +- **Stream container (on-disk payload)**: `atsc/src/data.rs` (`CompressedStream`) +- **Frame container (per chunk)**: `atsc/src/frame/mod.rs` (`CompressorFrame`) +- **Header / magic**: `atsc/src/header.rs` (`"BRRO"`) +- **Compressors**: `atsc/src/compressor/` + - FFT: `atsc/src/compressor/fft.rs` + - Polynomial / IDW: `atsc/src/compressor/polynomial.rs` + - Constant: `atsc/src/compressor/constant.rs` + - VSRI (timestamps): `atsc/src/compressor/vsri.rs` +- **Chunking / planning**: `atsc/src/optimizer/mod.rs` (`OptimizerPlan`) + +## How to build, test, lint, benchmark + +- **Build**: `cargo build --release` +- **Format**: `cargo fmt` +- **Clippy**: `cargo clippy --workspace --all-targets` +- **Unit tests**: `cargo test --workspace` +- **Benchmarks (Criterion)**: + - `cargo bench -p atsc --bench fft_bench` + - `cargo bench -p atsc --bench polynomial_bench` + +If you change compressor logic, prefer adding/adjusting a Criterion benchmark alongside unit tests. + +## On-disk format compatibility (do not break silently) + +ATSC writes `.bro`/`.vsri` payloads using **bincode v2** (`bincode = 2.0.0-rc.3`) and a shared config (`atsc/src/compressor/mod.rs::bincode_config()`). + +Implications: +- **Changing the shape/order of `Encode`/`Decode` structs is format-breaking**, even if Rust still compiles. +- High-risk types include (non-exhaustive): `atsc::data::CompressedStream`, `atsc::frame::CompressorFrame`, `atsc::header::CompressorHeader`, and any compressor frame types in `atsc/src/compressor/*` (e.g. `FFT`, `FrequencyPoint`). + +Guardrails: +- If you need to evolve the format, prefer **explicit versioning** (header/version field) and **versioned decode paths** rather than “just changing the struct”. +- When adding fields, consider whether they must be encoded; if not, follow the existing pattern (e.g. `FFT` manually omits `error` from encoding). +- Add a **roundtrip test** that reads representative bytes and validates decode behavior. + +## Performance expectations + +ATSC is designed for **fast decompression** and “reasonable” compression throughput. When optimizing: +- Treat **allocations and per-sample conversions** in hot paths as first suspects. +- Use existing Criterion benches as baselines and add focused micro-benches when needed. +- Prefer changes that are **measurable** (bench evidence) and **local** (don’t destabilize format without intent). + From b4645bcf2d54bf3efae37f8acfc36af9fe2d3df9 Mon Sep 17 00:00:00 2001 From: Carlos Juzarte Rolo Date: Mon, 23 Feb 2026 16:49:25 +0000 Subject: [PATCH 2/4] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e97b0e9..61c53a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ If you change compressor logic, prefer adding/adjusting a Criterion benchmark al ## On-disk format compatibility (do not break silently) -ATSC writes `.bro`/`.vsri` payloads using **bincode v2** (`bincode = 2.0.0-rc.3`) and a shared config (`atsc/src/compressor/mod.rs::bincode_config()`). +ATSC writes `.bro` payloads using **bincode v2** (`bincode = 2.0.0-rc.3`) with a shared config (`atsc/src/compressor/mod.rs::BinConfig::get()`). `.vsri` files are written by the `vsri` crate as a line-based text format (not bincode). Implications: - **Changing the shape/order of `Encode`/`Decode` structs is format-breaking**, even if Rust still compiles. From 127505e70a9d5373a166c66a4016479fd3862eb6 Mon Sep 17 00:00:00 2001 From: Carlos Juzarte Rolo Date: Mon, 23 Feb 2026 16:49:34 +0000 Subject: [PATCH 3/4] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 61c53a3..1321d2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ This repository is a Rust workspace containing ATSC (Advanced Time Series Compre - FFT: `atsc/src/compressor/fft.rs` - Polynomial / IDW: `atsc/src/compressor/polynomial.rs` - Constant: `atsc/src/compressor/constant.rs` - - VSRI (timestamps): `atsc/src/compressor/vsri.rs` + - VSRI (timestamps): `vsri/src/lib.rs` (separate workspace crate) - **Chunking / planning**: `atsc/src/optimizer/mod.rs` (`OptimizerPlan`) ## How to build, test, lint, benchmark From 4092db54b9c3dcebc1197f31584a44f5cdc6fcbf Mon Sep 17 00:00:00 2001 From: Carlos Juzarte Rolo Date: Mon, 23 Feb 2026 16:49:48 +0000 Subject: [PATCH 4/4] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1321d2d..a930de2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ This repository is a Rust workspace containing ATSC (Advanced Time Series Compre ## Codebase map (high-signal entry points) - **CLI**: `atsc/src/main.rs` - - Reads `.wbro` or `.csv`, produces `.bro` (values) and `.vsri` (timestamps when CSV). + - Reads `.wbro` or `.csv`, produces `.bro` (values). `.vsri` (timestamps) output for CSV is handled by the `csv-compressor` crate. - **Stream container (on-disk payload)**: `atsc/src/data.rs` (`CompressedStream`) - **Frame container (per chunk)**: `atsc/src/frame/mod.rs` (`CompressorFrame`) - **Header / magic**: `atsc/src/header.rs` (`"BRRO"`)