shape-vm 0.3.1

Stack-based bytecode virtual machine for the Shape programming language
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226

//! Logical operations for the VM executor (ADR-006 §2.7.7 / Q9 — kinded stack).
//!
//! Handles: And, Or, Not, NullCoalesce
//!
//! Wave 6: kinds for both operands are now read from the parallel stack
//! kind track via `pop_kinded()`. Filter-expression dispatch (heap path
//! used by query DSL) discriminates on `NativeKind::Ptr(HeapKind::*)`
//! rather than the deleted `is_heap()` probe.
//!
//! Wave-γ G-heap-filter-expr (ADR-006 §2.3 / §2.7.6 / Q8 amendment,
//! 2026-05-09): the filter-expression branch now labels its
//! `Arc::into_raw(Arc<FilterNode>) as u64` payloads as
//! `NativeKind::Ptr(HeapKind::FilterExpr)`. The earlier label
//! `HeapKind::NativeView` collided with `Arc<NativeViewData>` payloads at
//! the `clone_with_kind` / `drop_with_kind` dispatch tables, causing
//! wrong-type retain/release on every And/Or/Not result. Wave-α
//! D-raw-helpers (commit `a27c0e4`) surfaced the gap; Wave-γ
//! G-heap-filter-expr fixes it by adding `HeapKind::FilterExpr` and
//! mirroring the dispatch arm in every `Q8`/Q10 cell-storage and
//! stack-track table.

use crate::executor::objects::raw_helpers;
use crate::{
    bytecode::{Instruction, OpCode},
    executor::vm_impl::stack::drop_with_kind,
    executor::VirtualMachine,
};
use shape_value::{FilterNode, NativeKind, VMError, heap_value::HeapKind};
use std::sync::Arc;

/// Wave 6: heuristic helper. A pushed slot is a runtime-heap-bearing
/// FilterExpr candidate if its `NativeKind` is one of the heap-arms.
/// Inline scalars (Bool, Int, Float, etc.) trivially are not.
#[inline]
fn kind_is_heap(k: NativeKind) -> bool {
    matches!(k, NativeKind::String | NativeKind::Ptr(_))
}

/// Wave 6: bool truthiness from raw bits + kind. Inline-scalar arms read
/// the bits directly; heap arms are non-null → truthy. The deleted
/// `is_truthy()` probe walked tag bits — Wave 6 dispatches on `kind`.
#[inline]
fn kinded_truthy(bits: u64, kind: NativeKind) -> bool {
    match kind {
        NativeKind::Bool => bits != 0,
        NativeKind::Float64 => f64::from_bits(bits) != 0.0,
        NativeKind::Int8
        | NativeKind::Int16
        | NativeKind::Int32
        | NativeKind::Int64
        | NativeKind::IntSize
        | NativeKind::UInt8
        | NativeKind::UInt16
        | NativeKind::UInt32
        | NativeKind::UInt64
        | NativeKind::UIntSize => bits != 0,
        // Nullable arms: zero-bits convention = null = falsy. Otherwise
        // delegate to the underlying bits being non-zero.
        NativeKind::NullableFloat64
        | NativeKind::NullableInt8
        | NativeKind::NullableInt16
        | NativeKind::NullableInt32
        | NativeKind::NullableInt64
        | NativeKind::NullableIntSize
        | NativeKind::NullableUInt8
        | NativeKind::NullableUInt16
        | NativeKind::NullableUInt32
        | NativeKind::NullableUInt64
        | NativeKind::NullableUIntSize => bits != 0,
        // Round 19 S1.5 W12-nativekind-scalar-additions (2026-05-14):
        // F32 truthy iff `!= 0.0`; Char truthy iff codepoint bits non-zero.
        NativeKind::Float32 => f32::from_bits(bits as u32) != 0.0,
        NativeKind::Char => bits != 0,
        // Wave 2 Agent B W12-StringV2-DecimalV2-NativeKind-additions
        // (2026-05-14): same non-null pointer → truthy rule as
        // String / Ptr(_) below.
        NativeKind::StringV2 | NativeKind::DecimalV2 => bits != 0,
        // Heap-bearing kinds: non-null pointer → truthy.
        NativeKind::String | NativeKind::Ptr(_) => bits != 0,
        // R5b-2-bool-null-sentinel-cluster (ADR-006 §2.7 + §2.7.7/Q9,
        // 2026-05-19): `NativeKind::Null` is the absence-of-value
        // sentinel; falsy by definition.
        NativeKind::Null => false,
    }
}

impl VirtualMachine {
    #[inline(always)]
    pub(in crate::executor) fn exec_logical(
        &mut self,
        instruction: &Instruction,
    ) -> Result<(), VMError> {
        use OpCode::*;
        match instruction.opcode {
            And => {
                let (b_bits, b_kind) = self.pop_kinded()?;
                let (a_bits, a_kind) = self.pop_kinded()?;
                if kind_is_heap(a_kind) || kind_is_heap(b_kind) {
                    if let (Some(left), Some(right)) = (
                        raw_helpers::extract_filter_expr(a_bits, a_kind),
                        raw_helpers::extract_filter_expr(b_bits, b_kind),
                    ) {
                        let combined = Arc::new(FilterNode::And(
                            Box::new(left.clone()),
                            Box::new(right.clone()),
                        ));
                        // Filter-expr operands consumed; release shares.
                        drop_with_kind(a_bits, a_kind);
                        drop_with_kind(b_bits, b_kind);
                        let raw = Arc::into_raw(combined) as u64;
                        self.push_kinded(raw, NativeKind::Ptr(HeapKind::FilterExpr))?;
                    } else {
                        let r = kinded_truthy(a_bits, a_kind) && kinded_truthy(b_bits, b_kind);
                        drop_with_kind(a_bits, a_kind);
                        drop_with_kind(b_bits, b_kind);
                        self.push_kinded(r as u64, NativeKind::Bool)?;
                    }
                } else {
                    let r = kinded_truthy(a_bits, a_kind) && kinded_truthy(b_bits, b_kind);
                    self.push_kinded(r as u64, NativeKind::Bool)?;
                }
            }
            Or => {
                let (b_bits, b_kind) = self.pop_kinded()?;
                let (a_bits, a_kind) = self.pop_kinded()?;
                if kind_is_heap(a_kind) || kind_is_heap(b_kind) {
                    if let (Some(left), Some(right)) = (
                        raw_helpers::extract_filter_expr(a_bits, a_kind),
                        raw_helpers::extract_filter_expr(b_bits, b_kind),
                    ) {
                        let combined = Arc::new(FilterNode::Or(
                            Box::new(left.clone()),
                            Box::new(right.clone()),
                        ));
                        drop_with_kind(a_bits, a_kind);
                        drop_with_kind(b_bits, b_kind);
                        let raw = Arc::into_raw(combined) as u64;
                        self.push_kinded(raw, NativeKind::Ptr(HeapKind::FilterExpr))?;
                    } else {
                        let r = kinded_truthy(a_bits, a_kind) || kinded_truthy(b_bits, b_kind);
                        drop_with_kind(a_bits, a_kind);
                        drop_with_kind(b_bits, b_kind);
                        self.push_kinded(r as u64, NativeKind::Bool)?;
                    }
                } else {
                    let r = kinded_truthy(a_bits, a_kind) || kinded_truthy(b_bits, b_kind);
                    self.push_kinded(r as u64, NativeKind::Bool)?;
                }
            }
            Not => {
                let (bits, kind) = self.pop_kinded()?;
                if kind_is_heap(kind) {
                    if let Some(node) = raw_helpers::extract_filter_expr(bits, kind) {
                        let combined = Arc::new(FilterNode::Not(Box::new(node.clone())));
                        drop_with_kind(bits, kind);
                        let raw = Arc::into_raw(combined) as u64;
                        self.push_kinded(raw, NativeKind::Ptr(HeapKind::FilterExpr))?;
                    } else {
                        let r = !kinded_truthy(bits, kind);
                        drop_with_kind(bits, kind);
                        self.push_kinded(r as u64, NativeKind::Bool)?;
                    }
                } else {
                    self.push_kinded(!kinded_truthy(bits, kind) as u64, NativeKind::Bool)?;
                }
            }
            _ => unreachable!(
                "exec_logical called with non-logical opcode: {:?}",
                instruction.opcode
            ),
        }
        Ok(())
    }

    /// Null coalescing operator: returns left if not null, otherwise right.
    /// Wave 6: null detection via the parallel kind track + zero-bits
    /// convention (Nullable* arms encode null as zero bits).
    pub(in crate::executor) fn op_null_coalesce(&mut self) -> Result<(), VMError> {
        let (right_bits, right_kind) = self.pop_kinded()?;
        let (left_bits, left_kind) = self.pop_kinded()?;

        let left_is_null = is_null_kinded(left_bits, left_kind);
        if left_is_null {
            // Discard left, push right.
            drop_with_kind(left_bits, left_kind);
            self.push_kinded(right_bits, right_kind)
        } else {
            // Discard right, push left.
            drop_with_kind(right_bits, right_kind);
            self.push_kinded(left_bits, left_kind)
        }
    }
}

/// Wave 6: null detection from raw bits + kind. Replaces the deleted
/// `ValueWord::is_none()`. Heap-bearing kinds are null when the pointer
/// bits are zero; nullable scalar arms encode null as zero bits.
///
/// R5b-2-bool-null-sentinel-cluster (ADR-006 §2.7 + §2.7.7/Q9,
/// 2026-05-19): mirror of `comparison/mod.rs::is_null_kinded` —
/// `NativeKind::Null` is the canonical absence-of-value discriminator;
/// `NativeKind::Bool` slots carry only legitimate `{0, 1}` bit patterns
/// and are NEVER null.
#[inline]
fn is_null_kinded(bits: u64, kind: NativeKind) -> bool {
    match kind {
        // R5b-2 disposition: Null IS the absence-of-value discriminator.
        NativeKind::Null => true,
        NativeKind::String | NativeKind::Ptr(_) => bits == 0,
        NativeKind::NullableFloat64 => f64::from_bits(bits).is_nan(),
        NativeKind::NullableInt8
        | NativeKind::NullableInt16
        | NativeKind::NullableInt32
        | NativeKind::NullableInt64
        | NativeKind::NullableIntSize
        | NativeKind::NullableUInt8
        | NativeKind::NullableUInt16
        | NativeKind::NullableUInt32
        | NativeKind::NullableUInt64
        | NativeKind::NullableUIntSize => bits == 0,
        // Non-nullable scalar kinds are never null. R5b-2 disposition:
        // Bool slots carry only `{0, 1}` real bool bit patterns —
        // `false` is NOT null.
        _ => false,
    }
}