shape_value/
reference.rs

1//! Reference-value carrier — the kinded redesign of the deleted
2//! `nanboxed::RefTarget` / `RefProjection` `ValueWord`-shaped enum.
3//!
4//! ADR-006 §2.7.13 / Q14 (Wave 8 W8-T26, 2026-05-10). Each variant carries
5//! the **`NativeKind` of the projected slot**, threaded from the producing-
6//! opcode emit per §2.7.7 / §2.7.8 / §2.7.10 / §2.7.11 invariant. Loading
7//! and storing through a ref read the carried kind directly — no
8//! tag-bit decoding, no kind fabrication at projection time, no
9//! `is_heap()` probe.
10//!
11//! Slot bits for a `Reference`-labeled slot are
12//! `Arc::into_raw(Arc<RefTarget>) as u64` (mirror of §2.7.9 FilterExpr —
13//! NOT a `Box::into_raw(Box<HeapValue>)` wrap). `clone_with_kind` /
14//! `drop_with_kind` retain/release `Arc<RefTarget>` directly via the
15//! `HeapKind::Reference` dispatch arm. `slot.as_heap_value()` is
16//! undefined behavior on Reference-labeled bits, same as FilterExpr.
17//!
18//! `HeapValue::Reference(Arc<RefTarget>)` is provided ONLY to preserve
19//! the ADR-005 §1 / ADR-006 §2.3 `HeapKind`↔`HeapValue` symmetry
20//! property — no caller materializes a Reference through `HeapValue`
21//! pattern matching.
22
23// V3-S5 ckpt-4 (2026-05-15): `TypedArrayData` import deleted — the enum
24// was retired at ckpt-1 per W12-typed-array-data-deletion-audit §3.5 +
25// ADR-006 §2.7.24 Q25.A SUPERSEDED. `RefTarget::TypedIndex { receiver:
26// Arc<TypedArrayData>, ... }` variant retired in lockstep below;
27// references into typed-array elements cascade-break here for v2-raw
28// `TypedArray<T>` rebuild in a downstream wave (the carrier replacement
29// requires per-element-kind receiver variants — `Arc<TypedArray<f64>>`
30// / `Arc<TypedArray<i64>>` / etc. — not a single `Arc<T>` enum).
31use crate::heap_value::TypedObjectPtr;
32use crate::native_kind::NativeKind;
33
34/// Kinded reference target.
35///
36/// Each variant carries the `NativeKind` of the **projected slot** — what
37/// you get when you deref the reference, not what you reference *into*.
38/// Threaded from the producing-opcode emit at `MakeRef` /
39/// `MakeFieldRef` / `MakeIndexRef` time per ADR-006 §2.7.13.
40#[derive(Debug)]
41pub enum RefTarget {
42    /// Reference to a local stack slot.
43    ///
44    /// `frame_index` is the index into `VirtualMachine.call_stack` at
45    /// `MakeRef` time; `slot_index` is the offset from that frame's
46    /// `base_pointer` (i.e. the local-slot ordinal). `kind` is the
47    /// `NativeKind` of the slot at construction time, sourced from the
48    /// stack's §2.7.7 parallel-kind track.
49    ///
50    /// `Local`-shaped refs do NOT escape their originating frame —
51    /// the MIR ref-escape analysis (`mir/lowering/mod.rs`, ADR-006
52    /// §3.1) rejects closure capture / function return of a `Local`
53    /// ref at compile time.
54    Local {
55        frame_index: u32,
56        slot_index: u32,
57        kind: NativeKind,
58    },
59
60    /// Reference to a module binding.
61    ///
62    /// `binding_idx` is the position in
63    /// `VirtualMachine.module_bindings`; `kind` is sourced from the
64    /// module-binding §2.7.8 parallel-kind track at construction
65    /// time.
66    ModuleBinding {
67        binding_idx: u32,
68        kind: NativeKind,
69    },
70
71    /// Projected reference into a typed-object field.
72    ///
73    /// `receiver` keeps the projected object alive via the v2-raw
74    /// `TypedObjectPtr` carrier (ADR-006 §2.3 typed-Arc carrier — one
75    /// HeapHeader-at-offset-0 refcount share, retained/released through
76    /// `v2_retain` / `TypedObjectStorage::release_elem`). Production
77    /// `TypedObjectStorage` is allocated via the v2-raw `_new` path
78    /// (`op_new_typed_object`), so the receiver slot bits are the raw
79    /// struct pointer (HeapHeader at offset 0); the wrapper matches that
80    /// allocation provenance. `field_offset` is the slot index inside
81    /// `TypedObjectStorage.slots` (the schema-resolved `field_idx` from
82    /// `Operand::TypedField`); `kind` is the projected slot's
83    /// `NativeKind`, sourced from the emitter's `field_type_tag`.
84    TypedField {
85        receiver: TypedObjectPtr,
86        field_offset: u32,
87        kind: NativeKind,
88    },
89
90    // V3-S5 ckpt-4 (2026-05-15): `TypedIndex { receiver: Arc<
91    // TypedArrayData>, index, elem_kind }` variant DELETED. The
92    // `TypedArrayData` enum + `TypedBuffer<T>` wrapper layer were
93    // retired wholesale at ckpt-1..ckpt-4 per W12-typed-array-data-
94    // deletion-audit §3.5 + §B + ADR-006 §2.7.24 Q25.A SUPERSEDED.
95    // The replacement (per-element-kind `Arc<TypedArray<f64>>` /
96    // `Arc<TypedArray<i64>>` / etc. receiver variants) is downstream-
97    // wave territory — same shape as the `IteratorSource::Array`
98    // deletion in `iterator_state.rs`. Refusal #1 binding.
99}
100
101impl RefTarget {
102    /// The `NativeKind` of the projected slot — what `op_deref_load`
103    /// will push, and what `op_deref_store` expects.
104    #[inline]
105    pub fn projected_kind(&self) -> NativeKind {
106        match self {
107            // V3-S5 ckpt-4: `RefTarget::TypedIndex` arm deleted in
108            // lockstep with the variant.
109            RefTarget::Local { kind, .. }
110            | RefTarget::ModuleBinding { kind, .. }
111            | RefTarget::TypedField { kind, .. } => *kind,
112        }
113    }
114}
shape_value/reference.rs

shape_value/
reference.rs
