fusevm 0.9.4

Language-agnostic bytecode VM with fused superinstructions and Cranelift JIT path
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
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397

//! Shell builtin IDs for `CallBuiltin(id, argc)` dispatch.
//!
//! These IDs are used by shell frontends (zshrs) to emit bytecodes
//! that call registered builtin handlers. The VM dispatches through
//! the pre-registered function pointer table — no name lookup at runtime.
//!
//! Usage in frontend compiler:
//! ```ignore
//! use fusevm::shell_builtins::*;
//! builder.emit(Op::CallBuiltin(BUILTIN_CD, 1), line);
//! ```
//!
//! Usage in frontend VM init:
//! ```ignore
//! vm.register_builtin(BUILTIN_CD, |vm, argc| { ... });
//! ```

// ═══════════════════════════════════════════════════════════════════════════
// Core builtins (POSIX + common)
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_CD: u16 = 0;
pub const BUILTIN_PWD: u16 = 1;
pub const BUILTIN_ECHO: u16 = 2;
pub const BUILTIN_PRINT: u16 = 3;
pub const BUILTIN_PRINTF: u16 = 4;
pub const BUILTIN_EXPORT: u16 = 5;
pub const BUILTIN_UNSET: u16 = 6;
pub const BUILTIN_SOURCE: u16 = 7;
pub const BUILTIN_EXIT: u16 = 8;
pub const BUILTIN_RETURN: u16 = 9;
pub const BUILTIN_TRUE: u16 = 10;
pub const BUILTIN_FALSE: u16 = 11;
pub const BUILTIN_TEST: u16 = 12;
pub const BUILTIN_COLON: u16 = 13; // :
pub const BUILTIN_DOT: u16 = 14;   // . (alias for source)

// ═══════════════════════════════════════════════════════════════════════════
// Variable declaration
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_LOCAL: u16 = 20;
pub const BUILTIN_DECLARE: u16 = 21;
pub const BUILTIN_TYPESET: u16 = 22;
pub const BUILTIN_READONLY: u16 = 23;
pub const BUILTIN_INTEGER: u16 = 24;
pub const BUILTIN_FLOAT: u16 = 25;

// ═══════════════════════════════════════════════════════════════════════════
// I/O
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_READ: u16 = 30;
pub const BUILTIN_MAPFILE: u16 = 31;

// ═══════════════════════════════════════════════════════════════════════════
// Control flow
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_BREAK: u16 = 40;
pub const BUILTIN_CONTINUE: u16 = 41;
pub const BUILTIN_SHIFT: u16 = 42;
pub const BUILTIN_EVAL: u16 = 43;
pub const BUILTIN_EXEC: u16 = 44;
pub const BUILTIN_COMMAND: u16 = 45;
pub const BUILTIN_BUILTIN: u16 = 46;
pub const BUILTIN_LET: u16 = 47;

// ═══════════════════════════════════════════════════════════════════════════
// Job control
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_JOBS: u16 = 50;
pub const BUILTIN_FG: u16 = 51;
pub const BUILTIN_BG: u16 = 52;
pub const BUILTIN_KILL: u16 = 53;
pub const BUILTIN_DISOWN: u16 = 54;
pub const BUILTIN_WAIT: u16 = 55;
pub const BUILTIN_SUSPEND: u16 = 56;

// ═══════════════════════════════════════════════════════════════════════════
// History
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_HISTORY: u16 = 60;
pub const BUILTIN_FC: u16 = 61;
pub const BUILTIN_R: u16 = 62;

// ═══════════════════════════════════════════════════════════════════════════
// Aliases
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_ALIAS: u16 = 70;
pub const BUILTIN_UNALIAS: u16 = 71;

// ═══════════════════════════════════════════════════════════════════════════
// Options
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_SET: u16 = 80;
pub const BUILTIN_SETOPT: u16 = 81;
pub const BUILTIN_UNSETOPT: u16 = 82;
pub const BUILTIN_SHOPT: u16 = 83;
pub const BUILTIN_EMULATE: u16 = 84;
pub const BUILTIN_GETOPTS: u16 = 85;

// ═══════════════════════════════════════════════════════════════════════════
// Functions / Autoload
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_AUTOLOAD: u16 = 90;
pub const BUILTIN_FUNCTIONS: u16 = 91;
pub const BUILTIN_UNFUNCTION: u16 = 92;

// ═══════════════════════════════════════════════════════════════════════════
// Traps / Signals
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_TRAP: u16 = 100;

// ═══════════════════════════════════════════════════════════════════════════
// Directory stack
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_PUSHD: u16 = 110;
pub const BUILTIN_POPD: u16 = 111;
pub const BUILTIN_DIRS: u16 = 112;

// ═══════════════════════════════════════════════════════════════════════════
// Type / Which / Hash
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_TYPE: u16 = 120;
pub const BUILTIN_WHENCE: u16 = 121;
pub const BUILTIN_WHERE: u16 = 122;
pub const BUILTIN_WHICH: u16 = 123;
pub const BUILTIN_HASH: u16 = 124;
pub const BUILTIN_REHASH: u16 = 125;
pub const BUILTIN_UNHASH: u16 = 126;

// ═══════════════════════════════════════════════════════════════════════════
// Completion
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_COMPGEN: u16 = 130;
pub const BUILTIN_COMPLETE: u16 = 131;
pub const BUILTIN_COMPOPT: u16 = 132;
pub const BUILTIN_COMPADD: u16 = 133;
pub const BUILTIN_COMPSET: u16 = 134;
pub const BUILTIN_COMPDEF: u16 = 135;
pub const BUILTIN_COMPINIT: u16 = 136;
pub const BUILTIN_CDREPLAY: u16 = 137;

// ═══════════════════════════════════════════════════════════════════════════
// Zsh-specific
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_ZSTYLE: u16 = 140;
pub const BUILTIN_ZMODLOAD: u16 = 141;
pub const BUILTIN_BINDKEY: u16 = 142;
pub const BUILTIN_ZLE: u16 = 143;
pub const BUILTIN_VARED: u16 = 144;
pub const BUILTIN_ZCOMPILE: u16 = 145;
pub const BUILTIN_ZFORMAT: u16 = 146;
pub const BUILTIN_ZPARSEOPTS: u16 = 147;
pub const BUILTIN_ZREGEXPARSE: u16 = 148;

// ═══════════════════════════════════════════════════════════════════════════
// Resource limits
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_ULIMIT: u16 = 150;
pub const BUILTIN_LIMIT: u16 = 151;
pub const BUILTIN_UNLIMIT: u16 = 152;
pub const BUILTIN_UMASK: u16 = 153;

// ═══════════════════════════════════════════════════════════════════════════
// Misc
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_TIMES: u16 = 160;
pub const BUILTIN_CALLER: u16 = 161;
pub const BUILTIN_HELP: u16 = 162;
pub const BUILTIN_ENABLE: u16 = 163;
pub const BUILTIN_DISABLE: u16 = 164;
pub const BUILTIN_NOGLOB: u16 = 165;
pub const BUILTIN_TTYCTL: u16 = 166;
pub const BUILTIN_SYNC: u16 = 167;
pub const BUILTIN_MKDIR: u16 = 168;
pub const BUILTIN_STRFTIME: u16 = 169;
pub const BUILTIN_ZSLEEP: u16 = 170;
pub const BUILTIN_ZSYSTEM: u16 = 171;

// ═══════════════════════════════════════════════════════════════════════════
// PCRE
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_PCRE_COMPILE: u16 = 180;
pub const BUILTIN_PCRE_MATCH: u16 = 181;
pub const BUILTIN_PCRE_STUDY: u16 = 182;

// ═══════════════════════════════════════════════════════════════════════════
// Database (GDBM)
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_ZTIE: u16 = 190;
pub const BUILTIN_ZUNTIE: u16 = 191;
pub const BUILTIN_ZGDBMPATH: u16 = 192;

// ═══════════════════════════════════════════════════════════════════════════
// Prompt
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_PROMPTINIT: u16 = 200;
pub const BUILTIN_PROMPT: u16 = 201;

// ═══════════════════════════════════════════════════════════════════════════
// Async / Parallel (zshrs extensions)
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_ASYNC: u16 = 210;
pub const BUILTIN_AWAIT: u16 = 211;
pub const BUILTIN_PMAP: u16 = 212;
pub const BUILTIN_PGREP: u16 = 213;
pub const BUILTIN_PEACH: u16 = 214;
pub const BUILTIN_BARRIER: u16 = 215;

// ═══════════════════════════════════════════════════════════════════════════
// Intercept (AOP)
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_INTERCEPT: u16 = 220;
pub const BUILTIN_INTERCEPT_PROCEED: u16 = 221;

// ═══════════════════════════════════════════════════════════════════════════
// Debug / Profile
// ═══════════════════════════════════════════════════════════════════════════

pub const BUILTIN_DOCTOR: u16 = 230;
pub const BUILTIN_DBVIEW: u16 = 231;
pub const BUILTIN_PROFILE: u16 = 232;
pub const BUILTIN_ZPROF: u16 = 233;

/// Maximum builtin ID (for pre-allocating the handler table)
pub const BUILTIN_MAX: u16 = 240;

/// Map builtin name to ID. Returns None for non-builtins.
#[inline]
pub fn builtin_id(name: &str) -> Option<u16> {
    match name {
        "cd" | "chdir" => Some(BUILTIN_CD),
        "pwd" => Some(BUILTIN_PWD),
        "echo" => Some(BUILTIN_ECHO),
        "print" => Some(BUILTIN_PRINT),
        "printf" => Some(BUILTIN_PRINTF),
        "export" => Some(BUILTIN_EXPORT),
        "unset" => Some(BUILTIN_UNSET),
        "source" | "." => Some(BUILTIN_SOURCE),
        "exit" | "bye" | "logout" => Some(BUILTIN_EXIT),
        "return" => Some(BUILTIN_RETURN),
        "true" => Some(BUILTIN_TRUE),
        "false" => Some(BUILTIN_FALSE),
        "test" | "[" => Some(BUILTIN_TEST),
        ":" => Some(BUILTIN_COLON),
        "local" => Some(BUILTIN_LOCAL),
        "declare" | "typeset" => Some(BUILTIN_TYPESET),
        "readonly" => Some(BUILTIN_READONLY),
        "integer" => Some(BUILTIN_INTEGER),
        "float" => Some(BUILTIN_FLOAT),
        "read" => Some(BUILTIN_READ),
        "mapfile" | "readarray" => Some(BUILTIN_MAPFILE),
        "break" => Some(BUILTIN_BREAK),
        "continue" => Some(BUILTIN_CONTINUE),
        "shift" => Some(BUILTIN_SHIFT),
        "eval" => Some(BUILTIN_EVAL),
        "exec" => Some(BUILTIN_EXEC),
        "command" => Some(BUILTIN_COMMAND),
        "builtin" => Some(BUILTIN_BUILTIN),
        "let" => Some(BUILTIN_LET),
        "jobs" => Some(BUILTIN_JOBS),
        "fg" => Some(BUILTIN_FG),
        "bg" => Some(BUILTIN_BG),
        "kill" => Some(BUILTIN_KILL),
        "disown" => Some(BUILTIN_DISOWN),
        "wait" => Some(BUILTIN_WAIT),
        "suspend" => Some(BUILTIN_SUSPEND),
        "history" => Some(BUILTIN_HISTORY),
        "fc" => Some(BUILTIN_FC),
        "r" => Some(BUILTIN_R),
        "alias" => Some(BUILTIN_ALIAS),
        "unalias" => Some(BUILTIN_UNALIAS),
        "set" => Some(BUILTIN_SET),
        "setopt" => Some(BUILTIN_SETOPT),
        "unsetopt" => Some(BUILTIN_UNSETOPT),
        "shopt" => Some(BUILTIN_SHOPT),
        "emulate" => Some(BUILTIN_EMULATE),
        "getopts" => Some(BUILTIN_GETOPTS),
        "autoload" => Some(BUILTIN_AUTOLOAD),
        "functions" => Some(BUILTIN_FUNCTIONS),
        "unfunction" => Some(BUILTIN_UNFUNCTION),
        "trap" => Some(BUILTIN_TRAP),
        "pushd" => Some(BUILTIN_PUSHD),
        "popd" => Some(BUILTIN_POPD),
        "dirs" => Some(BUILTIN_DIRS),
        "type" => Some(BUILTIN_TYPE),
        "whence" => Some(BUILTIN_WHENCE),
        "where" => Some(BUILTIN_WHERE),
        "which" => Some(BUILTIN_WHICH),
        "hash" => Some(BUILTIN_HASH),
        "rehash" => Some(BUILTIN_REHASH),
        "unhash" => Some(BUILTIN_UNHASH),
        "compgen" => Some(BUILTIN_COMPGEN),
        "complete" => Some(BUILTIN_COMPLETE),
        "compopt" => Some(BUILTIN_COMPOPT),
        "compadd" => Some(BUILTIN_COMPADD),
        "compset" => Some(BUILTIN_COMPSET),
        "compdef" => Some(BUILTIN_COMPDEF),
        "compinit" => Some(BUILTIN_COMPINIT),
        "cdreplay" => Some(BUILTIN_CDREPLAY),
        "zstyle" => Some(BUILTIN_ZSTYLE),
        "zmodload" => Some(BUILTIN_ZMODLOAD),
        "bindkey" | "bind" => Some(BUILTIN_BINDKEY),
        "zle" => Some(BUILTIN_ZLE),
        "vared" => Some(BUILTIN_VARED),
        "zcompile" => Some(BUILTIN_ZCOMPILE),
        "zformat" => Some(BUILTIN_ZFORMAT),
        "zparseopts" => Some(BUILTIN_ZPARSEOPTS),
        "zregexparse" => Some(BUILTIN_ZREGEXPARSE),
        "ulimit" => Some(BUILTIN_ULIMIT),
        "limit" => Some(BUILTIN_LIMIT),
        "unlimit" => Some(BUILTIN_UNLIMIT),
        "umask" => Some(BUILTIN_UMASK),
        "times" => Some(BUILTIN_TIMES),
        "caller" => Some(BUILTIN_CALLER),
        "help" => Some(BUILTIN_HELP),
        "enable" => Some(BUILTIN_ENABLE),
        "disable" => Some(BUILTIN_DISABLE),
        "noglob" => Some(BUILTIN_NOGLOB),
        "ttyctl" => Some(BUILTIN_TTYCTL),
        "sync" => Some(BUILTIN_SYNC),
        "mkdir" => Some(BUILTIN_MKDIR),
        "strftime" => Some(BUILTIN_STRFTIME),
        "zsleep" => Some(BUILTIN_ZSLEEP),
        "zsystem" => Some(BUILTIN_ZSYSTEM),
        "pcre_compile" => Some(BUILTIN_PCRE_COMPILE),
        "pcre_match" => Some(BUILTIN_PCRE_MATCH),
        "pcre_study" => Some(BUILTIN_PCRE_STUDY),
        "ztie" => Some(BUILTIN_ZTIE),
        "zuntie" => Some(BUILTIN_ZUNTIE),
        "zgdbmpath" => Some(BUILTIN_ZGDBMPATH),
        "promptinit" => Some(BUILTIN_PROMPTINIT),
        "prompt" => Some(BUILTIN_PROMPT),
        "async" => Some(BUILTIN_ASYNC),
        "await" => Some(BUILTIN_AWAIT),
        "pmap" => Some(BUILTIN_PMAP),
        "pgrep" => Some(BUILTIN_PGREP),
        "peach" => Some(BUILTIN_PEACH),
        "barrier" => Some(BUILTIN_BARRIER),
        "intercept" => Some(BUILTIN_INTERCEPT),
        "intercept_proceed" => Some(BUILTIN_INTERCEPT_PROCEED),
        "doctor" => Some(BUILTIN_DOCTOR),
        "dbview" => Some(BUILTIN_DBVIEW),
        "profile" => Some(BUILTIN_PROFILE),
        "zprof" => Some(BUILTIN_ZPROF),
        _ => None,
    }
}

/// Check if a command name is a builtin.
#[inline]
pub fn is_builtin(name: &str) -> bool {
    builtin_id(name).is_some()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_builtin_lookup() {
        assert_eq!(builtin_id("cd"), Some(BUILTIN_CD));
        assert_eq!(builtin_id("chdir"), Some(BUILTIN_CD));
        assert_eq!(builtin_id("echo"), Some(BUILTIN_ECHO));
        assert_eq!(builtin_id("typeset"), Some(BUILTIN_TYPESET));
        assert_eq!(builtin_id("declare"), Some(BUILTIN_TYPESET));
        assert_eq!(builtin_id("ls"), None);
        assert_eq!(builtin_id("grep"), None);
    }

    #[test]
    fn test_is_builtin() {
        assert!(is_builtin("cd"));
        assert!(is_builtin("export"));
        assert!(!is_builtin("ls"));
        assert!(!is_builtin("cat"));
    }
}