# Coefficient-cache audit
> **AI-generated, for agentic coding.** This document was written by an AI agent
> as reference material for AI agents (and humans) working on this repository.
> It may contain errors — check it against the code and tests rather than
> trusting it blindly.
Revision `65f923657c28f0e6fbc91658313927520527f43b`; `cgc-gen`; crate-internal workload, so consumer revision is N/A. Measured with `rustc 1.96.0 (ac68faa2)`, macOS/aarch64, release test binary, and the test-only wrapper around `System`.
Run:
```text
RACAH_AUDIT_REVISION=65f923657c28f0e6fbc91658313927520527f43b cargo test --release --features cgc-gen --lib cache_audit::coefficient_cache_audit -- --ignored --nocapture
```
The audit adapts the repeated exact-symbol regime in `benches/wigner.rs::bench_repeated_labels`, the SU(N) channel selections in `benches/sun_cgc.rs::cases` and `benches/sun_fr.rs::cases`, and product collection in `benches/sun_product.rs::run_racah_generation_workload`. The concrete reduced audit generators are `src/cache_audit.rs::{su2,su3,su4}`, driven by `src/cache_audit.rs::coefficient_cache_audit`; they use one representative admissible SU(2), SU(3), and SU(4) case rather than reproducing each benchmark's complete case list. It records every base and generated tier as `[entries, charged bytes, hits, misses, evictions]`; raw rows are in [coefficient-cache-audit-trace.jsonl](coefficient-cache-audit-trace.jsonl). `cold` is an empty-cache phase, `warm` reruns it, and `reset_before_each_query` is the production-faithful no-reuse control. It is not called “cache disabled”: reset has the normal production semantics.
| phase | cold ns, median ± MAD | warm ns, median ± MAD | reset-before-each ns, median ± MAD |
| --- | ---: | ---: | ---: |
| SU(2) | 122750 ± 4334 | 750 ± 42 | 43541 ± 1499 |
| SU(3) | 15306750 ± 226167 | 2958 ± 1 | 17897167 ± 56250 |
| SU(4) | 22424666 ± 206584 | 2708 ± 83 | 30360291 ± 160251 |
The forward and reverse fresh-reset sequential traces end at the same occupancy: SU(2) `3j/6j/F = 1/2/1` entries and `182/357/56` charged bytes; SU(N) product/CGC/F = `4/8/2` and `1352/6688/1184` bytes. All evictions were zero. The SU-only leaf intentionally does not exercise B/C/D CGC/F: their rows remain zero and are not a measurement of those tiers. The exact prime/factorial support tables grow to 122 rows, 30 primes, and 13240 conservative retained-capacity bytes.
`charged bytes` are cache-entry charge only. The System wrapper records requested live bytes routed through Rust `GlobalAlloc`, not allocator-live memory: it excludes C/library allocations and allocator metadata. Each timed phase resets its peak to its starting requested-live value; this is an approximate observed requested-live peak under backend concurrency. `transient_requested_live_lower_bound` is `peak - max(start, end)`, so retained cache/output growth is excluded. macOS samples current RSS with `ps -o rss= -p PID` outside timed sections; the representative trace records the samples.
Linux parses `VmRSS:` from `/proc/self/status` (KiB to bytes), avoiding a fixed page-size assumption. This post-measurement portability change does not affect the audited macOS `ps` path, so the report retains the measured macOS revision above.
Five fresh test processes produced the median/MAD table above; their raw values are in [coefficient-cache-audit-timings.jsonl](coefficient-cache-audit-timings.jsonl). The checked-in JSONL is one complete representative trace (metadata, every phase, sequential intermediate, clone, and retention records), not an aggregate.
Public return allocation is measured by monotonic successful allocation requests, not noisy live deltas. The representative 1/9 retained calls request respectively exact SU(2) `48/1008` B, owned `directproduct` `376/3576` B, public CGC `408/4504` B, and public F `344/3544` B; these include public-call overhead, not payload-only attribution. The selected warm CGC is asserted nonempty. The harness also proves the one public shared-product `Arc` survives cache reset: cache reset reduces its strong count by exactly one and the returned channels remain readable. CGC and F public APIs return deep clones, so they cannot externally retain their internal cache `Arc`.
## Policy decision
1. Configurable small/default/HPC budgets: **defer** to #66; this leaf establishes only a tiny SU working set, not a budget choice.
2. Deterministic `trim_to`: **defer** to #67; no policy implementation belongs in this measurement leaf.
3. Aggregate scaling without shared LRU: **defer**; the tiny no-eviction trace gives no evidence to replace the current independent tiers or to introduce cross-tier competition. #66 needs broader pressure measurements.
4. Internal shared `Arc<Cgc>` / `Arc<FBlock>` consumption where ownership permits: **defer**; public clone slopes motivate investigation, while any consumer-visible shared accessor remains a separate ownership/API decision.
5. Prime/factorial table policy: **recommend** retaining the new private observation; defer any bound/reset policy until workloads above the observed 122-row support table are measured.
No persistent layer, R cache, cache tier, production instrumentation, policy/budget, or public API was added. Admission bypasses are not separately observable: SU(2) invalid/overflow requests bypass a tier before lookup; generated fallible input/generation also may not reach a tier; an oversized admitted entry follows the existing immediate-eviction path already counted in `misses`/`evictions`.