feat: make section store hashes content-aware

[SkyeAv]

Content-aware .tablassert/store keys now invalidate cached sections when their actual local source files change, while preserving cache reuse for unchanged content.

Content-Aware Store Keys

• File hashing: Adds rs.xxh64_file() in rust/src/lib.rs, using streaming 8 MiB reads with bounded memory and explicit OSError propagation.
• Key derivation: Adds file_content_hash() and section_store_key() in src/tablassert/utils.py.
• Pipeline wiring: build_graph_pipeline() now combines the section configuration hash with the source-file content hash.
• Per-run memoization: Shared source files are hashed once per (resolved_path, mtime_ns, size) signature during a build. A changed signature triggers a fresh hash.
• Validation behavior: Validation pipelines remain configuration-only and do not require source files to exist.
• Errors: Missing, unreadable, and directory sources raise the coded source-file-unreadable error with configuration, section, and path context.

Store Invalidation

• Changed files: Editing a source file creates a new store parquet and rebuilds the affected section.
• Unchanged files: Touching a file without changing its bytes preserves the content-derived key.
• Legacy entries: Existing configuration-only parquet files become orphans; they are never read, modified, renamed, or deleted automatically.
• Agent builds: Existing agent build and storage workflows continue to pass.

Performance

• Streaming throughput: On a deterministic 1 GiB CSV using 8 MiB chunks, xxh64_file measured 1.848 GiB/s.
• Raw-read comparison: The same-file pure-read floor measured 25.095 GiB/s.
• Cached-build overhead: Eight sections sharing one 4 MiB source measured a content-aware Stage-3 delta of 0.313 ms/file versus configuration-only hashing.
• Benchmark: Added the opt-in tests/bench_file_hash_bench.py harness and a non-gated 4 MiB smoke ceiling.

Documentation

• Documents file_content_hash(), section_store_key(), the combined key formula, source-edit invalidation, and the one-time rebuild after upgrading.
• Documents that orphaned legacy parquets are retained rather than automatically deleted.

Testing

• make check → Python 1188 passed, 43 skipped; Rust tests 109 + 10 + 14 passed, 1 ignored; clippy clean.
• uv run pytest -q → 1189 passed, 43 skipped.
• uv run pytest tests/test_store_keying.py tests/test_store_invalidation_e2e.py tests/test_utils.py tests/test_rs.py tests/test_errors.py -n 0 -q → passed.
• uv run pytest tests/test_docs_cli_coverage.py tests/test_agent_docs.py tests/test_docs_examples.py -n 0 -q --no-cov → 32 passed.
• TABLASSERT_BENCH=1 uv run pytest tests/bench_file_hash_bench.py -s -n 0 -q --no-cov → 1 passed with the benchmark results above.
• PYRIGHT_PYTHON_FORCE_VERSION=latest uv run pyright → 0 errors, 0 warnings.
• uv run mkdocs build --strict --site-dir /tmp/tablassert-mkdocs-audit → passed.
• Independent final audit → approved with no blockers, should-fix items, or nits.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: e74d39ef-5e67-4963-8d96-7b3892fa9de8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}