shape-runtime 0.3.0

Bytecode compiler, builtins, and runtime infrastructure for Shape
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

/// @module std::core::state
/// Content-Addressed VM State Primitives
///
/// Provides introspection, capture, and resume of VM execution state.
/// Every function, type, and value is content-addressed via SHA-256 hashes,
/// enabling portable state transfer across nodes, programs, and time.

/// A content-addressed function reference.
/// The hash uniquely identifies the function's bytecode, constants, and dependencies.
pub type FunctionRef {
    hash: string,
    name: string,
    param_types: Vec<string>,
    return_type: string,
}

/// A single stack frame — portable, content-addressed.
/// Contains the function reference (by hash), the instruction pointer
/// relative to that function, and captured local state.
pub type Frame<T> {
    function: FunctionRef,
    local_ip: int,
    locals: Vec<T>,
    upvalues: Vec<T>?,
}

/// Full execution state — a chain of frames.
/// Captures the entire call stack plus module-level bindings.
/// Can be serialized, transferred, and resumed on any node that
/// has the referenced function blobs.
pub type VmState<T> {
    frames: Vec<Frame<T>>,
    module_bindings: HashMap<string, T>,
    timestamp: string,
}

/// Current function frame only (lightweight capture).
pub type FrameState<T> {
    function: FunctionRef,
    args: Vec<T>,
    locals: Vec<T>,
    upvalues: Vec<T>?,
}

/// Module-level state capture.
pub type ModuleState<T> {
    bindings: HashMap<string, T>,
    schemas: HashMap<string, string>,
}

/// Ready-to-call payload.
/// Bundles a function reference with arguments for remote invocation.
pub type CallPayload<T> {
    function: FunctionRef,
    args: Vec<T>,
    upvalues: Vec<T>?,
}

/// Delta between two values/states.
/// Used for efficient state synchronization — only transfer what changed.
pub type Delta<T> {
    changed: HashMap<string, T>,
    removed: Vec<string>,
}

// ---------------------------------------------------------------------------
// Capture primitives
// ---------------------------------------------------------------------------

/// Capture the current function's frame state.
builtin fn capture() -> FrameState;

/// Capture the full VM execution state (all frames).
builtin fn capture_all() -> VmState;

/// Capture module-level bindings and type schemas.
builtin fn capture_module() -> ModuleState;

/// Build a ready-to-call payload without executing.
builtin fn capture_call<F>(f: F, args: Vec<F>) -> CallPayload;

// ---------------------------------------------------------------------------
// Resume primitives
// ---------------------------------------------------------------------------

/// Resume full VM state. Does not return — execution continues
/// from the captured point.
builtin fn resume(vm: VmState) -> never;

/// Re-enter a captured function frame and return its result.
builtin fn resume_frame<T>(f: FrameState) -> T;

// ---------------------------------------------------------------------------
// Content addressing
// ---------------------------------------------------------------------------

/// Compute SHA-256 hash of any value.
builtin fn hash<T>(value: T) -> string;

/// Get the content hash of a type's schema definition.
builtin fn schema_hash(type_name: string) -> string;

/// Get a function's content hash (from its FunctionBlob).
builtin fn fn_hash<F>(f: F) -> string;

// ---------------------------------------------------------------------------
// Serialization
// ---------------------------------------------------------------------------

/// Serialize a value to wire format (MessagePack).
builtin fn serialize<T>(value: T) -> Vec<int>;

/// Deserialize wire format bytes back to a value.
builtin fn deserialize<T>(bytes: Vec<int>) -> T;

// ---------------------------------------------------------------------------
// Diffing
// ---------------------------------------------------------------------------

/// Compute the delta between two values using content-hash trees.
builtin fn diff<T>(old: T, new: T) -> Delta;

/// Apply a delta to a base value, producing the updated value.
builtin fn patch<T>(base: T, delta: Delta) -> T;

// ---------------------------------------------------------------------------
// Introspection
// ---------------------------------------------------------------------------

/// Get a reference to the calling function (one frame up).
builtin fn caller() -> FunctionRef?;

/// Get the current function's arguments as an array.
builtin fn args<T>() -> Vec<T>;

/// Get the current scope's local variables as a map.
builtin fn locals<T>() -> HashMap<string, T>;