Module nanbox 

NaN-Boxing Implementation

Encodes Seq values into 8 bytes using IEEE 754 NaN-boxing. This reduces Value size from 40 bytes to 8 bytes, improving cache utilization and reducing memory bandwidth.

Encoding Scheme

IEEE 754 doubles use specific bit patterns for NaN. We encode non-float values in the negative quiet NaN space (>= 0xFFF8_0000_0000_0000):

Float (normal):    [any valid IEEE 754 double below 0xFFF8_0000_0000_0000]
Boxed values:      0xFFF8 + (tag << 47) + payload
                   Bits 63:51 = 0x1FFF (negative quiet NaN)
                   Bits 50:47 = 4-bit type tag (0-15)
                   Bits 46:0  = 47-bit payload

Type Tags

• 0x0: Int (47-bit signed integer, range ~±70 trillion)
• 0x1: Bool (0 or 1 in low bit)
• 0x2: String (47-bit pointer to SeqString)
• 0x3: Symbol (47-bit pointer to SeqString)
• 0x4: Variant (47-bit pointer to Arc)
• 0x5: Map (47-bit pointer to Box)
• 0x6: Quotation (47-bit pointer to QuotationData)
• 0x7: Closure (47-bit pointer to ClosureData)
• 0x8: Channel (47-bit pointer to Arc)
• 0x9: WeaveCtx (47-bit pointer to WeaveCtxData)

Float Handling

Real float values are stored directly as IEEE 754 doubles. To distinguish them from boxed values, we canonicalize NaN results to a specific pattern that doesn’t collide with our tagged encoding.

Structs

ClosureData

Closure data stored on the heap for NaN-boxing

NanBoxedValue

An 8-byte NaN-boxed value

QuotationData

Quotation data stored on the heap for NaN-boxing

WeaveCtxData

Weave context data stored on the heap for NaN-boxing

Enums

NanBoxTag

Type tags for NaN-boxed values

Constants

CANONICAL_NAN

Canonical NaN value (used when float operations produce NaN) This is a positive quiet NaN that doesn’t collide with our boxed encoding

MAX_NANBOX_INT

Maximum 47-bit signed integer: 2^46 - 1 = 70,368,744,177,663 (~70 trillion)

MIN_NANBOX_INT

Minimum 47-bit signed integer: -2^46 = -70,368,744,177,664