[aliszka]

Adds ZeroedLayout and its buffer variants, which build an empty bitmap shaped like a source, and CloneToBufWithHeadroom, which clones into a pooled buffer with room for new keys. Both families take their buffer from get on CompactedToBuf's terms.

Motivation

A caller that repeatedly ORs subsets of a known bitmap into a scratch bitmap pays for growth on every round: a new container moves everything after it, and a new key past the keys node's capacity moves every container. Starting from an empty bitmap with the source's keys, container sizes and types avoids both, since nothing the subset brings needs room the layout lacks. A caller that instead starts from a copy of the source, and adds values at keys beyond its last one, needs the same headroom CompactedToBufWithHeadroom gives, without compacting.

Approach

The source's layout is kept, not rebuilt: containers keep their position, size and type, dead space included, and only the keys node is resized, to the source's keys plus one spare slot (plus whatever the headroom variants buy). Every offset shifts by the change in the keys node's size, which may be negative when the source had spare slots. That keeps sizing O(1), from the source's length and keys alone, and lets the clone copy all containers at once. Repacking would make the result smaller but costs a pass over the containers, and the zeroed layout would then no longer match the source container for container.

The zeroed builds write only the keys node and the container headers. A pooled buffer may be dirty, so bitmap payloads are cleared; array payloads and dead space keep their old bytes, because nothing reads past an array's cardinality.

Key areas for review

• bitmap.go:writeShiftedKeys: the offset shift, including the negative case wrapping in uint64.
• bitmap_opt.go:shiftedKeysDst: sizing before get, headroom from the buffer's capacity after it.
• bitmap.go:writeZeroedContainers: which bytes of a dirty buffer are cleared, and why the rest are safe.

Testing

• TestZeroedLayout and TestLayoutToBuf build every variant from sources covering nil, empty, key 0 only, arrays, bitmaps, mixed, dead space, emptied containers, spare key slots and oversized capacity, from dirty buffers. They check one get call, the exact layout, and that OR-ing a subset back in keeps capacity, length and offsets.
• TestLayoutToBufWithHeadroom checks that keys added after the last fit without moving any container except an overflowing last array.
• TestLayoutToBufContract covers the panics and zero allocations for the Init variants.
• BenchmarkZeroedLayout compares against cloning and clearing; BenchmarkCloneToBufWithHeadroom against CloneToBuf, each alone and followed by an OR of new keys.

🤖 Generated with Claude Code

[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