SOFA reader fuzz harness + docs site (Doxygen + concepts + Pages)#7
Merged
Conversation
Two evidence/quality items — and a real bug the fuzzer caught on its first run. Fuzzing: - tests/fuzz/fuzz_sofa_reader.cpp: libFuzzer harness over the SOFA reader (load_sofa + decompose_sh), the library's only untrusted-file surface. Clang + ASan/UBSan; AMBITAP_BUILD_FUZZERS CMake option (requires Clang + AMBITAP_ENABLE_SOFA); small deterministic seed corpus in tests/fuzz/corpus/ (one valid SOFA + hand-authored malformed cases). - Bug found: load_sofa dereferenced Data.IR, SourcePosition, and Data.SamplingRate through the declared M/N/R dimensions without checking the arrays were present and sized — a truncated or hostile file that parsed structurally read off a null/short buffer (UBSan: load of null float* at sofa_reader.h:161). Fixed by validating every dereferenced array against its expected element count up front; malformed inputs now throw cleanly. - tests/test_sofa.cpp: reject-malformed contract (built on the SOFA leg). - CI: new bounded "fuzz (sofa reader smoke)" job — clang-18, replays the seed corpus and fuzzes a few minutes on every push. tests/fuzz/README.md documents deep-campaign usage. Docs site: - docs/CONCEPTS.md: the orientation guide — conventions, the real-time contract, the processor lifecycle, the embedded profile. - docs/Doxyfile: API reference generated from the header doc-comments (README as mainpage; AUDIT/EMBEDDED/COMPARISON/CONCEPTS as related pages; generated tables excluded; Graphviz include graphs). Cleaned up the doc-comment warnings it surfaced (undocumented params on matrix_applier/sh_block_applier/probe_response, a couple of literal angle-bracket tokens). - .github/workflows/docs.yml: build on PRs, deploy to GitHub Pages from main. docs/html/ is gitignored (generated). - README documentation section + AUDIT.md ledger updated. 118 tests green with SOFA enabled (116 + 2 new); fuzzer smoke-runs clean over the committed corpus; Doxygen builds warning-clean (bar two cosmetic cross-refs); format clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ng2WDk5ho2yhzvfC2boRPQ
Integrates the measured C++ head-to-head against libspatialaudio and SAF: - bench/compare/: run.sh clones + builds libspatialaudio 0.4.1 and SAF v1.3.5 from source, compiles the two harnesses (bench_libspatialaudio.cpp, bench_saf.c), and runs all three benchmarks (AmbiTap's own bench/ + the two others) with one shared methodology (48 kHz, median of 9x400 blocks, 50 warm-up). README documents the known asymmetries (SAF's afSTFT filterbank vs broadband matrix decoders; libspatialaudio's order-1-only built-in HRTF; SAF SIMD off by default). - docs/COMPARISON.md: adds the measured µs/block head-to-head table (encoder/rotator/decoder/binaural, orders 1/3/5), a platforms/SIMD matrix, per-library pros/cons, and a refreshed feature matrix current to July 2026. Numbers captured on a single Xeon; the doc says to re-run before quoting absolutes. The harnesses depend on external libraries (GitHub clones + OpenBLAS/ LAPACKE) so they are a manual reproducibility tool like the Python comparison notebook, not wired into CI. bench/compare/_work/ (the clones) is gitignored; bench/compare/ is excluded from the clang-format gate and .clang-format-ignore (external-style throwaway harnesses, one of them C). README documentation section updated to point at the head-to-head. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ng2WDk5ho2yhzvfC2boRPQ
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two quality/evidence items — and a real bug the fuzzer caught on its first run.
SOFA reader fuzzing 🐛
tests/fuzz/fuzz_sofa_reader.cpp— a libFuzzer harness over the wholeload_sofa→decompose_shpath, the library's only untrusted-file surface. Clang + ASan/UBSan, behind a newAMBITAP_BUILD_FUZZERSoption (requires Clang +AMBITAP_ENABLE_SOFA), with a small deterministic seed corpus (tests/fuzz/corpus/: one valid SOFA + hand-authored malformed cases).load_sofadereferencedData.IR,SourcePosition, andData.SamplingRatethrough the file's declared M/N/R dimensions without checking those arrays were present and sized — a truncated or hostile file that parsed structurally read off a null/short buffer (UBSan: load of nullfloat*atsofa_reader.h:161). Fixed by validating every dereferenced array against its expected element count up front; malformed inputs now throw cleanly.tests/test_sofa.cpp— reject-malformed contract (built on the SOFA CI leg).fuzz (sofa reader smoke)job (clang-18) replays the seed corpus and fuzzes a few minutes on every push.tests/fuzz/README.mddocuments deep-campaign usage.Docs site
docs/CONCEPTS.md— orientation guide: conventions, the real-time contract, the processor lifecycle, the embedded profile.docs/Doxyfile— API reference generated from the header doc-comments (README as main page; AUDIT/EMBEDDED/COMPARISON/CONCEPTS as related pages; generated tables excluded; Graphviz include graphs). The doc-comment warnings it surfaced (undocumented params onmatrix_applier/sh_block_applier/probe_response, a couple of literal angle-bracket tokens) are cleaned up..github/workflows/docs.yml— build on PRs, deploy to GitHub Pages frommain.docs/html/is gitignored (generated).Notes for merge
clang-18+ its exact runtime package (libclang-rt-18-dev), matching the format job's toolchain.Test plan
AMBITAP_ENABLE_SOFA=ON(116 + 2 new SOFA tests)test_sofa.cpp🤖 Generated with Claude Code
https://claude.ai/code/session_01Ng2WDk5ho2yhzvfC2boRPQ
Generated by Claude Code