Module tagged_offset_ptr 

TaggedOffsetPtr<T, const TAG_BITS: u32> - high-bit-stealing variant of OffsetPtr.

Steals the TOP TAG_BITS bits of the u32 index for a small type tag, leaving (32 - TAG_BITS) bits of index space.

Why high-bit stealing

Classical tagged pointers steal the LOW bits because aligned pointers have low bits guaranteed zero. We work with INDICES, not addresses, so alignment is irrelevant. The natural free bits in an index are the HIGH bits, because most regions don’t fill all 4 billion u32 slots. With TAG_BITS = 4 you still get 268M slots and 16 type IDs - plenty for most data structures.

Typical sizes

TAG_BITS	Max tag	Max index	Typical use
1	1	2.1B	Generation parity / dirty bit
2	3	1.07B	4-state machine
3	7	537M	8-color / 8-type discriminator
4	15	268M	16 node types in a tree
8	255	16.7M	256 distinct kinds; still huge index space

Bit layout

  bit 31                            bit 0
  [TAG_BITS][         32 - TAG_BITS         ]
    tag              index

NIL is u32::MAX (all-ones, both tag and index saturated). Distinguishable from any meaningful (tag, index) pair as long as the caller doesn’t create one with tag == max_tag AND index == max_index. For safety, use NIL constant rather than constructing all-ones manually.

Integration with SharedRegion

Pass ptr.index() to SharedRegion::get / set. The tag bits are caller-managed: type discriminator, state flag, color, generation parity, whatever the data structure encodes.

Structs

TaggedOffsetPtr

A 32-bit position-independent pointer with TAG_BITS high bits reserved for a caller-defined tag. Packs (tag, index) into one u32. Cross-process safe: same raw bits resolve to the same (tag, index) in every process.

Enums

TaggedPtrError