shape-vm 0.3.0

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

//! Array join operations
//!
//! Handles: inner_join, left_join, cross_join
//!
//! ## V3-S5 ckpt-3 consumer-cascade tier 2 surface (2026-05-15) — drive-by
//!
//! This file's pickup is a drive-by from ckpt-2's `array_transform.rs`
//! cross-module helper deletion: the imports at original lines 51-55
//! (`bump_closure_share / collect_homogeneous_results / element_kinded /
//! typed_array_arc_from_kinded / typed_array_len`) reference helpers that
//! were deleted in ckpt-2 (every one took `&TypedArrayData` or produced
//! `Arc<TypedArrayData>`). Per dispatch enumeration this file has 0
//! TypedArrayData:: refs in its own body, but the imports are E0432
//! cascade-broken.
//!
//! Per V3-S5 ckpt-1 close (commit `aac8495e`, 2026-05-15), the
//! `TypedArrayData` enum + impl blocks + `Display for TypedArrayData` +
//! `typed_array_structural_eq` fn were DELETED at
//! `crates/shape-value/src/heap_value.rs` per W12-typed-array-data-deletion
//! audit §3.5 + ADR-006 §2.7.24 Q25.A SUPERSEDED.
//!
//! Public handler bodies (`handle_inner_join_v2 / handle_left_join_v2 /
//! handle_cross_join_v2`) are replaced with structured surface-and-stop
//! returning `VMError::NotImplemented`. Local helpers (`typed_array_arc /
//! closure_arg / key_eq`) and the deleted cross-module imports are
//! DELETED.
//!
//! ## Cascade migration target (post-ckpt-6 STRICT close)
//!
//! Per W12-typed-array-data-deletion audit §A.3 + §2.1 scalar recipe +
//! §2.2 heap-element variants, the join body's element-read (left/right
//! TypedArrayData walks) migrates to the v2-raw `TypedArray<T>` flat-
//! struct carrier — per-T direct `*buf.data.add(i)` reads. The
//! closure-callback ABI (ADR-006 §2.7.11 / Q12 `vm.call_value_immediate_nb`)
//! and the join-shape algorithm (linear key-cache + cross-array match
//! emit + homogeneous-result collect) are unchanged and re-instate
//! once the receiver-shape migration lands across all element kinds.
//!
//! Bodies REFUSED ON SIGHT under Refusal #1 (resurrection under rename
//! per ckpt-1 close-marker at `heap_value.rs:3956`).

use shape_runtime::context::ExecutionContext;
use crate::executor::VirtualMachine;
use shape_value::heap_value::HeapKind;
use shape_value::{KindedSlot, NativeKind, VMError};

// ═══════════════════════════════════════════════════════════════════════════
// V3-S5 ckpt-3 surface-and-stop builder
// ═══════════════════════════════════════════════════════════════════════════

/// Common surface-and-stop body for every public handler in this file.
#[cold]
#[inline(never)]
fn ckpt3_surface(op: &'static str, args: &[KindedSlot]) -> VMError {
    let receiver_kind = if args.is_empty() {
        "<no args>".to_string()
    } else {
        format!("{:?}", args[0].kind)
    };
    VMError::NotImplemented(format!(
        "{op}: SURFACE — V3-S5 ckpt-3 consumer-cascade tier 2 surface \
         (drive-by from ckpt-2 cross-module helper deletion). \
         `TypedArrayData` enum DELETED at ckpt-1 (2026-05-15) per W12-\
         typed-array-data-deletion audit §3.5 + ADR-006 §2.7.24 Q25.A \
         SUPERSEDED. The 5-import E0432 cluster at this file's deleted \
         `use` block referenced helpers (`bump_closure_share / \
         collect_homogeneous_results / element_kinded / \
         typed_array_arc_from_kinded / typed_array_len`) that were \
         deleted in ckpt-2 at array_transform.rs (every one took \
         `&TypedArrayData` or produced `Arc<TypedArrayData>`). The 3 \
         public handlers in this file dispatch the join shape (linear \
         right-key cache + cross-array match emit + homogeneous-result \
         collect) entirely through those deleted helpers. Post-deletion \
         target is the v2-raw `TypedArray<T>` flat-struct carrier per \
         audit §1.2 + §A.3 + §3.1 scalar recipe; per-T monomorphization \
         landing across ckpt-3 (this file plus array_ops/typed_array_methods/\
         iterator_methods/array_sort/concat/property_access/array_query) + \
         ckpt-4 (Buf<T> / HeapValue::TypedArray arm / \
         HeapKind::TypedArray ordinal) + ckpt-5 (wire/json/marshal + \
         4-table lockstep) + ckpt-6 (JIT FFI). Closure-callback ABI \
         (ADR-006 §2.7.11 / Q12 `vm.call_value_immediate_nb`) is \
         unaffected and re-instates once receiver-shape migration lands. \
         Receiver kind: {kind}. UNREACHABLE until ckpt-6 STRICT close. \
         REFUSED ON SIGHT: TypedArrayData resurrection under any rename \
         (Refusal #1, W12 audit §7).",
        op = op,
        kind = receiver_kind,
    ))
}

/// Validate a closure callee kind. Accepts Closure / function-ref;
/// rejects anything else with a `RuntimeError`.
#[inline]
fn validate_closure_kind(op: &str, idx: usize, args: &[KindedSlot]) -> Option<VMError> {
    let Some(slot) = args.get(idx) else {
        return Some(VMError::RuntimeError(format!(
            "{}: missing closure argument at index {}",
            op, idx
        )));
    };
    match slot.kind {
        NativeKind::Ptr(HeapKind::Closure) | NativeKind::UInt64 => None,
        other => Some(VMError::RuntimeError(format!(
            "{}: argument {} must be a closure or function ref, got kind {:?}",
            op, idx, other
        ))),
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// MethodFnV2 handlers — surface-and-stop stubs
// Signatures preserved for method_registry.rs PHF integrity.
// ═══════════════════════════════════════════════════════════════════════════

/// v2 `innerJoin` — inner join two arrays with key functions.
///
/// args: [left_array, right_array, left_key_fn, right_key_fn, result_selector_fn]
pub(crate) fn handle_inner_join_v2(
    _vm: &mut VirtualMachine,
    args: &[KindedSlot],
    _ctx: Option<&mut ExecutionContext>,
) -> Result<KindedSlot, VMError> {
    if args.len() < 5 {
        return Err(VMError::RuntimeError(
            "innerJoin: expected (left, right, leftKey, rightKey, selector)".to_string(),
        ));
    }
    for idx in [2, 3, 4] {
        if let Some(err) = validate_closure_kind("innerJoin", idx, args) {
            return Err(err);
        }
    }
    Err(ckpt3_surface("innerJoin", args))
}

/// v2 `leftJoin` — left join two arrays with key functions.
///
/// args: [left_array, right_array, left_key_fn, right_key_fn, result_selector_fn]
pub(crate) fn handle_left_join_v2(
    _vm: &mut VirtualMachine,
    args: &[KindedSlot],
    _ctx: Option<&mut ExecutionContext>,
) -> Result<KindedSlot, VMError> {
    if args.len() < 5 {
        return Err(VMError::RuntimeError(
            "leftJoin: expected (left, right, leftKey, rightKey, selector)".to_string(),
        ));
    }
    for idx in [2, 3, 4] {
        if let Some(err) = validate_closure_kind("leftJoin", idx, args) {
            return Err(err);
        }
    }
    Err(ckpt3_surface("leftJoin", args))
}

/// v2 `crossJoin` — cross join two arrays (Cartesian product).
///
/// args: [left_array, right_array, result_selector_fn]
pub(crate) fn handle_cross_join_v2(
    _vm: &mut VirtualMachine,
    args: &[KindedSlot],
    _ctx: Option<&mut ExecutionContext>,
) -> Result<KindedSlot, VMError> {
    if args.len() < 3 {
        return Err(VMError::RuntimeError(
            "crossJoin: expected (left, right, selector)".to_string(),
        ));
    }
    if let Some(err) = validate_closure_kind("crossJoin", 2, args) {
        return Err(err);
    }
    Err(ckpt3_surface("crossJoin", args))
}