feature: Masked() and MaskedToBuf() — apply bitmask to keys and merge colliding containers

[aliszka]

Motivation

Bitmap keys encode dimensions in the upper bits. Callers need to project a bitmap onto a sub-dimension by masking out the upper bits and merging containers whose keys collide under the mask — without materialising an intermediate bitmap per dimension.

Approach

Masked(mask uint64) iterates over all source containers, applies the mask to each key, and OR-merges containers that collapse to the same masked key into the result. The lowest 16 bits of the mask are forced to zero since keys never use them.

Two optimisations in the merge loop keep allocations minimal:

• Key space is pre-sized upfront (expandConditionally(an, 0)) so the loop never shifts container data to make room for new keys.
• When an inline OR fails (container grew beyond its current allocation) and the old container sits at the tail of b.data, the slice is trimmed and regrown in place, avoiding a dead container fragment.

MaskedToBuf(mask, buf) is the same operation but writes into a caller-supplied byte slice via NewBitmapToBuf, avoiding heap allocation when the caller can reuse a pre-allocated buffer.

Key areas for review

• bitmap_opt.go:maskedInto — the trim-and-regrow path (b.data = b.data[:boff]) is only safe when boff+len(bc) == len(b.data); verify the condition is tight
• bitmap_opt.go:maskedInto — expandConditionally(an, 0) pre-sizes for the worst case (no key collisions); with heavy collisions the key space is over-allocated, but this is bounded by the source key count

Risks and mitigations

• Trim-and-regrow leaves dead space when container is not at tail: accepted trade-off; sequential key iteration almost always produces containers in append order, so the tail condition hits in the common case
• Mask low-bit truncation is silent: callers passing a mask with low 16 bits set get them silently cleared — documented on the method

Testing

Tests cover nil input, no key overlap, key collision with OR merge (including multi-key collapse under zero mask), mask boundary conditions (zero mask, identity mask, low-16-bits ignored), and the buffer-swap logic in the OR accumulation loop for non-overlapping arrays, overlapping arrays, array-to-bitmap conversion, and three-container chains.

[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

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Secrets	0   0   0   0	View in Orca