Enum HeapValue 

pub enum HeapValue {
    String(Arc<String>),
    Decimal(Arc<Decimal>),
    BigInt(Arc<i64>),
    Future(u64),
    Char(char),
    DataTable(Arc<DataTable>),
    Content(Arc<ContentNode>),
    Instant(Arc<Instant>),
    IoHandle(Arc<IoHandleData>),
    NativeScalar(NativeScalar),
    NativeView(Arc<NativeViewData>),
    TypedObject(TypedObjectPtr),
    ClosureRaw(OwnedClosureBlock),
    TaskGroup(Arc<TaskGroupData>),
    Temporal(Arc<TemporalData>),
    TableView(Arc<TableViewData>),
    HashMap(HashMapKindedRef),
    FilterExpr(Arc<FilterNode>),
    HashSet(Arc<HashSetData>),
    Reference(Arc<RefTarget>),
    Iterator(Arc<IteratorState>),
    Deque(Arc<DequeData>),
    Channel(Arc<ChannelData>),
    PriorityQueue(Arc<PriorityQueueData>),
    Range(Arc<RangeData>),
    Result(Arc<ResultData>),
    Option(Arc<OptionData>),
    TraitObject(TraitObjectPtr),
    Mutex(Arc<MutexData>),
    Atomic(Arc<AtomicData>),
    Lazy(Arc<LazyData>),
    ModuleFn(u64),
    Matrix(Arc<MatrixData>),
    MatrixSlice(Arc<MatrixSliceData>),
}

Compact heap-allocated value. Strict-typed variants only — every payload is either a typed primitive (i64, char, f64 via TypedArray), a typed structure (TypedObject slots, typed FFI pointers, typed temporal data), or a typed handle.

Variants whose payloads depended on the deleted ValueWord dynamic word were removed in the strict-typing Phase-2 bulldozer. See the corresponding HeapKind ordinals (annotated “(removed)”) for the migration target.

Variants

String(Arc<String>)

Decimal(Arc<Decimal>)

BigInt(Arc<i64>)

Future(u64)

Char(char)

DataTable(Arc<DataTable>)

Content(Arc<ContentNode>)

Instant(Arc<Instant>)

IoHandle(Arc<IoHandleData>)

NativeScalar(NativeScalar)

NativeView(Arc<NativeViewData>)

TypedObject(TypedObjectPtr)

Object value with schema-defined typed slots.

ClosureRaw(OwnedClosureBlock)

Track A.5 — the canonical closure representation.

Raw TypedClosureHeader-backed closure. Captures live in a typed C-laid-out block allocated by closure_raw::alloc_typed_closure and owned by the embedded [OwnedClosureBlock]. Cloning / dropping this variant manages the block’s refcount in lockstep with the enclosing Arc<HeapValue>. Readers go through VmClosureHandle for the stable read API. There is no legacy fallback.

TaskGroup(Arc<TaskGroupData>)

Temporal(Arc<TemporalData>)

TableView(Arc<TableViewData>)

HashMap(HashMapKindedRef)

HashMap with string keys + per-V monomorphized values.

Wave 2 Round 3b C2-joint ckpt-2 (2026-05-14): payload flipped from Arc<HashMapData> (non-generic) to HashMapKindedRef (per-V enum carrier) per ADR-006 §2.7.24 Q25.B SUPERSEDED + audit §C.4 option (a.2). The variant tag IS the per-V NativeKind discriminator; per-V dispatch at consumer sites goes through the HashMapKindedRef::{I64, F64, Bool, Char, String, Decimal, TypedObject, TraitObject} arms.

See $crate::heap_value::HashMapData<V> + HashMapKindedRef for the storage shape. Stage C P1(b), 2026-05-07.

FilterExpr(Arc<FilterNode>)

Filter-expression tree (Arc<FilterNode>) used by the query DSL’s And / Or / Not opcodes (executor/logical/mod.rs). In current code FilterExpr payloads are emitted directly to the kinded stack as Arc::into_raw(Arc<FilterNode>) as u64 with kind NativeKind::Ptr(HeapKind::FilterExpr) and never wrapped in HeapValue. The arm exists to preserve the ADR-005 §1 invariant that every HeapKind discriminator has a HeapValue arm of the same shape — kind() / is_truthy() / type_name() / drop_with_kind() / clone_with_kind() must dispatch a HeapKind::FilterExpr slot as Arc<FilterNode>, not Arc<NativeViewData> (the pre-Wave-γ type-confusion gap surfaced by Wave-α D-raw-helpers, commit a27c0e4).

HashSet(Arc<HashSetData>)

One-keyspace Set carrier. Mirror of HeapValue::HashMap(Arc<HashMapData>) with the values buffer dropped: insertion-ordered Arc<TypedBuffer<Arc< String>>> keys + eager FNV-1a bucket index for O(1) set.has(key). See $crate::heap_value::HashSetData for the storage shape.

Full HeapValue arm (NOT pure-discriminator like FilterExpr / SharedCell): Set values flow through as_heap_value() for method-receiver classification per the §2.7.15 amendment.

Reference(Arc<RefTarget>)

Reference-value carrier (Arc<RefTarget>) used by the MakeRef / MakeFieldRef / MakeIndexRef / DerefLoad / DerefStore / SetIndexRef opcode family (executor/variables/mod.rs). In current code Reference payloads are emitted directly to the kinded stack as Arc::into_raw(Arc<RefTarget>) as u64 with kind NativeKind::Ptr(HeapKind::Reference) and never wrapped in HeapValue. The arm exists to preserve the ADR-005 §1 / ADR-006 §2.3 HeapKind↔HeapValue symmetry — same pattern as HeapValue::FilterExpr (§2.7.9). Calling slot.as_heap_value() on a Reference-labeled slot is undefined behavior; the canonical recovery is Arc::from_raw::<RefTarget>(bits).

Iterator(Arc<IteratorState>)

Lazy iterator pipeline carrier (Arc<IteratorState>). Used by Array.iter / String.iter / HashMap.iter / Range.iter factories and the ITERATOR_METHODS PHF (map / filter / take / skip / flatMap / enumerate / chain / collect / forEach / reduce / count / any / all / find). Slot bits are Arc::into_raw(Arc<IteratorState>) as u64; recovery goes through slot.as_heap_value() → HeapValue::Iterator(arc) per ADR-005 §1 single-discriminator (the lazy-transforms / source / cursor triple is opaque at the dispatch shell — terminals walk arc.transforms and dispatch per stage).

Deque(Arc<DequeData>)

Double-ended queue carrier. Structurally a mirror of HeapValue::HashSet(Arc<HashSetData>) with the dedup keyspace replaced by a VecDeque<Arc<HeapValue>> (heterogeneous-element, order-preserving, no deduplication). See $crate::heap_value::DequeData for the storage shape.

Full HeapValue arm (NOT pure-discriminator like FilterExpr / SharedCell): Deque values flow through as_heap_value() for receiver classification per the §2.7.19 amendment.

Channel(Arc<ChannelData>)

MPSC-style synchronous channel carrier (Arc<ChannelData>). Unlike HashMap/HashSet (immutable-on-clone with Arc::make_mut clone-on-write), ChannelData wraps a Mutex<ChannelInner> so two Arc<ChannelData> shares of the same channel observe each other’s send / recv mutations — the producer/consumer-endpoints shape. See $crate::heap_value::ChannelData for the storage shape and the §2.7.20 amendment for the design rationale.

Full HeapValue arm (NOT pure-discriminator like FilterExpr / SharedCell): Channel values flow through slot.as_heap_value() for receiver classification at method dispatch — same shape as HashSet / Iterator.

PriorityQueue(Arc<PriorityQueueData>)

Min-heap-backed PriorityQueue carrier. Mirror of HeapValue::HashSet(Arc<HashSetData>) with the keys buffer carrying i64 priorities instead of Arc<String>: Arc<TypedBuffer<i64>> heap-ordered values (root = min). See $crate::heap_value::PriorityQueueData for the storage shape.

Full HeapValue arm (NOT pure-discriminator like FilterExpr / SharedCell): PriorityQueue values flow through as_heap_value() for method-receiver classification per the §2.7.18 amendment.

i64-priority-only at landing per the §2.7.18 Q19 ruling (typed-payload PriorityQueue<T, K> with key-extractor is a future Phase-2c amendment with measurement; the smoke target is exercised on this shape).

Range(Arc<RangeData>)

Range value carrier (Arc<RangeData>). Built by MakeRange from the start..end / start..=end surface syntax. Slot bits are Arc::into_raw(Arc<RangeData>) as u64 (typed-Arc shape, mirror of HashMap / HashSet / Iterator). Recovery goes through slot.as_heap_value() → HeapValue::Range(arc) for receiver classification at method dispatch (r.contains(x) / r.toArray() / r.iter()). Same dispatch shape as the FilterExpr §2.7.9 amendment for refcount discipline (clone_with_kind / drop_with_kind retain/release Arc<RangeData> directly, NOT through HeapValue).

Result(Arc<ResultData>)

Result<T, E> carrier (Arc<ResultData>). Used by the OkCtor / ErrCtor builtin producers and the op_is_ok / op_is_err / op_unwrap_ok / op_unwrap_err / op_try_unwrap discriminators. Slot bits are Arc::into_raw(Arc<ResultData>) as u64; recovery goes through slot.as_heap_value() → HeapValue::Result(arc) per ADR-005 §1 single-discriminator. The inner payload: KindedSlot owns one strong-count share for the wrapped value; ResultData::Drop (auto-derived from KindedSlot’s explicit Drop) retires the share at refcount=0.

Option(Arc<OptionData>)

Option carrier (Arc<OptionData>). Used by the SomeCtor builtin producer and the op_unwrap_option discriminator (the None half is also constructed as OptionData::none() at compiler emission sites). Same kinded-payload discipline as Result per §2.7.17.

TraitObject(TraitObjectPtr)

dyn Trait carrier (Arc<TraitObjectStorage>). Re-introduces the bulldozer-deleted HeapValue::TraitObject arm as a typed-Arc pair — TraitObjectStorage holds an Arc<TypedObjectStorage> data half + an Arc<VTable> vtable half. Slot bits are Arc::into_raw(Arc<TraitObjectStorage>) as u64; recovery goes through slot.as_heap_value() → HeapValue::TraitObject(arc) per ADR-005 §1 single-discriminator. The compiler-emission tier (W17-trait-object-emission round) populates the slot via OpCode::BoxTraitObject and dispatches method calls via OpCode::DynMethodCall against the recovered trait-object carrier. See ADR-006 §2.7.24 Q25.C.1 (universal-dyn auto-boxing), Q25.C.2 (Self-arg runtime vtable-identity check), Q25.C.3 (generic-method TypeInfo dispatch), Q25.C.5 (VTableEntry 6-variant shape).

Wave 2 Round 4 D4 ckpt-final-prime² (2026-05-14): payload flipped from Arc<TraitObjectStorage> to TraitObjectPtr (#[repr(transparent)] newtype around *const TraitObjectStorage) per the §Q25.C.5 amendment + Path B ratification. Mirror of the TypedObject flip in the same commit — the newtype owns one v2-raw HeapHeader-at- offset-0 refcount share; Clone via v2_retain, Drop via TraitObjectStorage::release_elem.

Mutex(Arc<MutexData>)

Mutex<T> concurrency-primitive carrier (Arc<MutexData>). The inner MutexData wraps a Mutex<MutexInner> so two Arc<MutexData> shares of the same mutex observe each other’s set mutations — the same interior-mutability shape as HeapValue::Channel. Full HeapValue arm — Mutex values flow through slot.as_heap_value() for receiver classification at method dispatch.

Atomic(Arc<AtomicData>)

Atomic<i64> concurrency-primitive carrier (Arc<AtomicData>). The inner AtomicData wraps a std::sync::atomic::AtomicI64 for atomic load / store / fetch_add / fetch_sub / compare_exchange. i64-only at landing per ADR-006 §2.7.25 — typed-payload Atomic<T> is a future Phase-2c amendment with measurement.

Lazy(Arc<LazyData>)

Lazy<T> initialize-once carrier (Arc<LazyData>). Wraps an initializer closure and cached value slot. Closure-call path is unlocked by W17-make-closure (merged at aa47364). Full HeapValue arm.

ModuleFn(u64)

Module-function reference inline-scalar carrier — labels a slot whose bits decode to a module_fn_id: u64 indexing VirtualMachine.module_fn_table. Inline-scalar payload (no Arc<T>, no heap state) — same shape as HeapValue::Future(u64) / HeapValue::Char(char).

Pure-discriminator pattern: in current code ModuleFn payloads are emitted directly to the kinded stack / TypedObject slot as module_fn_id as u64 with kind NativeKind::Ptr(HeapKind::ModuleFn) and never wrapped in HeapValue. The arm exists to preserve the ADR-005 §1 / ADR-006 §2.3 HeapKind↔HeapValue symmetry — same pattern as HeapValue::FilterExpr (§2.7.9) / HeapValue::Reference (§2.7.13). Calling slot.as_heap_value() on a ModuleFn-labeled slot is undefined behavior; the canonical recovery is reading the raw u64 bits as the module_fn_id.

Matrix(Arc<MatrixData>)

Matrix value carrier (Arc<MatrixData>). Built by op_new_matrix from the matrix(rows, cols, [data...]) surface form. In current code Matrix payloads are emitted directly to the kinded stack / TypedObject slot as Arc::into_raw(Arc<MatrixData>) as u64 with kind NativeKind::Ptr(HeapKind::Matrix) and never wrapped in HeapValue. The arm exists to preserve the ADR-005 §1 / ADR-006 §2.3 HeapKind↔HeapValue symmetry — same pattern as HeapValue::FilterExpr (§2.7.9) / HeapValue::Reference (§2.7.13). Calling slot.as_heap_value() on a Matrix-labeled slot is undefined behavior; the canonical recovery is Arc::<MatrixData>::from_raw(bits).

MatrixSlice(Arc<MatrixSliceData>)

Matrix-projection carrier (Arc<MatrixSliceData>). Built by Matrix.row(i) / Matrix.col(i) from a parent matrix. MatrixSliceData { parent: Arc<MatrixData>, offset, len } preserves the aliasing-into-parent semantics from the pre-amendment TypedArrayData::FloatSlice shape. Same typed-Arc pure-discriminator dispatch shape as HeapValue::Matrix.

Implementations

impl HeapValue

pub fn kind(&self) -> HeapKind

Get the kind discriminator for fast dispatch without full pattern matching.

pub fn is_truthy(&self) -> bool

Check if this heap value is truthy.

pub fn type_name(&self) -> &'static str

Get the type name for this heap value.

impl HeapValue

pub fn as_closure_handle(&self) -> Option<VmClosureHandle<'_>>

Obtain a crate::vm_closure_handle::VmClosureHandle over this heap value, if it is a HeapValue::ClosureRaw.

Closure spec §14.2: the handle is the stable read API for closure state. Returns None for non-closure heap values.

pub fn structural_eq(&self, other: &HeapValue) -> bool

Structural equality comparison for HeapValue.

ADR-006 §2.3: TypedArray and Temporal payloads are now Arc<TypedArrayData> / Arc<TemporalData>; the per-arm dispatch dereferences the Arc once at the outer match and forwards into the inner enum via typed_array_structural_eq / direct match.

pub fn equals(&self, other: &HeapValue) -> bool

Check equality between two heap values.

Trait Implementations

impl Clone for HeapValue

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HeapValue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for HeapValue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.