AndNot: exact two-pass sizing and sparse-result compaction

[amourao]

Reduces the free AndNot(a, b)'s allocation footprint to exactly its retained result, compacts sparse surviving bitmap containers to array containers, and builds dense results directly inside the result arena. Semantics unchanged. Independent of #44.

What was happening

andNotContainers built its result incrementally, which cost three ways:

1. Doubling churn: res.data grew container by container through fastExpand's capacity doubling — each growth abandoned the previous backing array to GC. Measured downstream (Weaviate BM25 filtered search, one AndNot per segment per query): ~11.5 reallocations per call, allocating ~2.8× the final result size.
2. Temp map: unmatched containers were staged in a map[uint64][]uint16, and its random iteration order made setKey insert keys out of order, memmoving existing keys (O(k·m)).
3. No compaction: a bitmap container whose result dropped to a handful of survivors stayed a full 8KB bitmap container (~15 bytes/value observed on tombstone-heavy data, vs ~2 for an array).

What this PR does

• Exact two-pass sizing: pass 1 computes each pair's result cardinality with an allocation-free andNotResultCard (sorted-merge count via the existing intersection2by2Cardinality, bit tests, or popcount per container combination — with an O(1) cardinality-header shortcut and an early exit once a result is provably dense), so res is grown exactly once via expandConditionally. Allocations per call are constant (TestAndNotAllocsBounded), and total bytes equal the retained result.
• Sparse-result compaction: bitmap-container results with cardinality < 1024 are written out as array containers, built directly inside res — for matched and unmatched containers alike. The cutoff is deliberately below the 4096 encoding break-even: in [1024, 4096) an array saves little space (8KB → 2–8KB) yet turns O(1) bit-test probes into binary searches (measured: threshold 4096 gave the same memory win but a +14% probe-side regression that 1024 eliminates).
• Alignment preserved: compacted sizes are padded to a multiple of 4 uint16s, so every container in the arena keeps the 8-byte alignment that uint16To64SliceUnsafe's *uint64 views rely on (TestAndNotResultAlignment checks every offset, including in-place ops over compacted results).
• Robust to corrupt input: the compaction enumeration clamps to the sized slots, so a container whose cardinality header understates its popcount (corrupt serialized data) degrades deterministically instead of overrunning (TestAndNotCorruptCardinalityNoPanic).
• Dense results build in place: provably-dense results (header shortcut) copy the source container into the reserved arena region and subtract there with a fused popcount — no scratch round-trip.
• Structural coupling: both passes share one ordered walker (andNotWalk) and one density predicate (andNotDenseByHeaders), so sizing and materialization cannot disagree; the temp map is gone and setKey always appends in ascending key order.

Correctness

Full existing suite green. New tests: mixed-shape differential vs brute force (all four container-type combinations, unmatched containers, containers fully erased), compaction threshold boundary, compaction size assertion, arena alignment (fixed shape + 30-trial fuzz + in-place ops over compacted results), corrupt-cardinality no-panic, unmatched-container compaction, and the allocation bound. Downstream, Weaviate's BM25 identity guard (bit-identical top-K vs unmerged filters on a real tombstone-heavy corpus) passes with this implementation.

Benchmarks

2M-value bitmap, vs main (measured on unmodified main via a temp worktree):

heavy shrink (~1% kept, results compact to arrays):
  main:  75.6 us/op   552,449 B/op   8 allocs/op
  PR:   111.7 us/op    49,408 B/op   3 allocs/op    (-91% bytes)

dense (2/3 kept, results stay bitmap containers):
  main:  75.1 us/op   552,449 B/op   8 allocs/op
  PR:    38.4 us/op   262,400 B/op   3 allocs/op    (1.96x faster, -53% bytes)

The heavy-shrink CPU cost is the sizing pass plus the compaction write — in the real downstream workload (AndNot as query setup) it is +5–8% of the merge path, in exchange for:

Weaviate filtered BM25 (one AndNot per segment per query), allocation overhead per query:
  10% filter:  +5.4 MB -> +1.7 MB   (-69%)
  50% filter: +13.6 MB -> +5.3 MB   (-61%)
  90% filter: +23.8 MB -> +7.9 MB   (-67%)

Profile attribution confirms the mechanism: the AndNot chain's allocations went from 779.6 MB of fastExpand doubling churn (whole benchmark run) to 297 MB in a single expandConditionally — exactly the retained results, zero waste.

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[Copilot]

Pull request overview

Optimizes the free AndNot(a, b) implementation to reduce allocation churn and memory footprint by precomputing exact result sizing and compacting sparse bitmap-container results into array containers while preserving arena alignment and semantics.

Changes:

• Introduces a two-pass andNotContainers walk: pass 1 sizes keys/container arena space; pass 2 materializes results in key order (avoids realloc churn and out-of-order insert memmoves).
• Adds sparse-result compaction: bitmap-container results with cardinality < 1024 are emitted as compact array containers with padding to preserve 8-byte alignment for unsafe uint64 views.
• Adds targeted tests/benchmarks for compaction correctness, alignment invariants, corrupt-cardinality robustness, and bounded allocations.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
container.go	Adds allocation-free bitmap-to-array enumeration helper used for compaction writes.
container_opt.go	Adds allocation-free (ac &^ bc) cardinality computation and shared dense-path predicate used by both sizing and materialization passes.
bitmap_opt.go	Reworks andNotContainers into a two-pass implementation, adds compaction sizing/layout helpers, and adds in-place dense subtraction path.
andnot_compact_test.go	Adds new tests/benchmarks covering compaction behavior, alignment, corrupt-cardinality handling, and allocation bounds.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.