elisprs 0.1.20

Emacs Lisp as a fusevm frontend: a reader and compiler to fusevm::Chunk on an ElispHost object heap, with no bespoke VM or JIT
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
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
//! elisprs — Emacs Lisp as a fusevm frontend.
//!
//! Pipeline: `reader` builds elisp forms as ElispHost heap objects → `compiler`
//! lowers each to a `fusevm::Chunk` → fusevm executes it, calling back into the
//! `host` (via fusevm's extension handler) for elisp-specific operations. There
//! is no bespoke VM or JIT here — execution and codegen live in fusevm.

pub mod aot;
pub mod aot_runtime;
pub mod backquote;
pub mod banner;
pub mod bidi;
pub mod bidi_data;
pub mod builtins;
pub mod bundled;
pub mod cache;
pub mod compiler;
pub mod dap;
pub mod embed;
pub mod fileio;
pub mod freevars;
pub mod host;
pub mod intercepts;
pub mod json;
pub mod lread_fn;
pub mod lsp;
pub mod modhooks;
pub mod prelude;
pub mod prelude_31;
pub mod reader;
pub mod regexp;
pub mod rust_ffi;
pub mod strftime;
pub mod textprop;
pub mod tiers;
pub mod timefns;
pub mod window;

pub use embed::run_program;
pub use fusevm::Value;
pub use host::{reset_host, run_chunk, with_host};

/// Native stack an elisp evaluation needs.
///
/// One elisp call frame costs several native frames — `call_function` →
/// `run_closure` → `run_chunk` → `VM::run` → `ext_dispatch` → `call_function` —
/// and an unoptimized build's frames are large, so the platform defaults (8 MiB
/// on the macOS main thread, 2 MiB for a spawned thread, which is also what the
/// test harness gives a test) ran out at roughly 70 elisp frames while Emacs
/// allows `max-lisp-eval-depth` = 1600. This is address space, not committed
/// memory: pages are backed only as they are touched.
///
/// The depth limit itself is enforced in elisp terms (`max-lisp-eval-depth`, in
/// [`host`]), so runaway recursion signals `excessive-lisp-nesting` and can be
/// caught; this stack only has to be big enough to reach that limit first.
pub const INTERP_STACK_BYTES: usize = 1 << 29; // 512 MiB

/// Run `f` on a thread with [`INTERP_STACK_BYTES`] of stack.
///
/// The host is a thread-local, so `f` gets a fresh interpreter — everything an
/// evaluation touches must run inside this call, not around it.
pub fn with_interpreter_stack<T, F>(f: F) -> T
where
    F: FnOnce() -> T + Send + 'static,
    T: Send + 'static,
{
    std::thread::Builder::new()
        .name("elisprs-interp".to_string())
        .stack_size(INTERP_STACK_BYTES)
        .spawn(f)
        .expect("spawn interpreter thread")
        .join()
        .unwrap_or_else(|e| std::panic::resume_unwind(e))
}

/// Read, lower, and run a source string on fusevm; return the last value.
pub fn eval_str(src: &str) -> Result<Value, String> {
    load_prelude();
    eval_forms(src)
}

/// Read every top-level form of `src` into the reader's s-expression form — the
/// elisp AST. Backs `elisp --dump-ast`; does not macro-expand, lower, or run.
pub fn read_forms(src: &str) -> Result<Vec<Value>, String> {
    host::with_host(|h| reader::read_all(h, src))
}

/// Read + lower `src` into a single fusevm chunk, exactly as an evaluated run
/// would (prelude loaded, top-level `progn` spliced, macros expanded) but
/// WITHOUT running it. Backs `elisp --dump-bytecode` / `--disasm`.
pub fn compile_str(src: &str) -> Result<fusevm::Chunk, String> {
    load_prelude();
    let forms = host::with_host(|h| reader::read_all(h, src).map(|fs| splice_top_forms(h, fs)))?;
    let mut expanded = Vec::with_capacity(forms.len());
    for form in &forms {
        expanded.push(host::macroexpand_all(form)?);
    }
    host::with_host(|h| compiler::compile_program(h, &expanded))
}

/// Splice literal top-level `(progn …)` forms into their subforms (recursively),
/// so an earlier subform's `defmacro`/`defun` is in effect before a later subform
/// is compiled — matching Emacs's top-level handling.
fn splice_top_forms(h: &mut host::ElispHost, forms: Vec<Value>) -> Vec<Value> {
    let mut out = Vec::new();
    for f in forms {
        let progn = match h.list_vec(&f) {
            Some(v) if !v.is_empty() && h.sym_name(&v[0]).as_deref() == Some("progn") => Some(v),
            _ => None,
        };
        match progn {
            Some(v) => out.extend(splice_top_forms(h, v[1..].to_vec())),
            None => out.push(f),
        }
    }
    out
}

/// Read every top-level form from `src` and evaluate them IN THE CURRENT host,
/// one at a time (read → splice → macro-expand → lower → run), so an in-file
/// `defmacro`/`defvar` is already in effect for the forms that follow it. Does
/// NOT reset the host or (re)load the prelude — the caller owns host lifecycle.
///
/// Returns the compiled per-form chunks (for the bytecode cache) and the value
/// of the last form. This is the single "run these forms in the live host"
/// machinery shared by `eval_forms`, `eval_file`'s cache-miss path, and the
/// `load` builtin, so none of them re-implement a divergent evaluator.
///
/// `load_buffer` is the buffer a file being loaded is read through: its forms
/// are read one at a time as `readevalloop` reads them, expanded the way `load`
/// expands them ([`host::macroexpand_for_load`]), and running out of text
/// mid-form is `(end-of-file BUFFER)` (lread.c `end_of_file_error` for a buffer
/// source). `None` stands in for `--eval`: the source is read as a whole first,
/// a truncated form is a bare `(end-of-file)`, and the walk that defers an
/// expander's failure is kept.
pub(crate) fn run_top_forms(
    src: &str,
    load_buffer: Option<Value>,
) -> Result<(Vec<fusevm::Chunk>, Value), String> {
    let loading = load_buffer.is_some();
    // Rewrite any inline `rust { ... }` FFI block into a `(__rust-compile ...)`
    // call before the reader runs (no-op when the source has no `rust` token).
    let src = rust_ffi::desugar(src);
    // The READER is what interns a file's literal symbols, so it counts as
    // compiling too: without this the image stopped carrying them and
    // `(intern-soft "a-symbol-this-file-mentions")` answered nil on a warm cache
    // and the symbol on a cold one.
    let read_forms = |h: &mut host::ElispHost, stream: &mut Option<reader::FormStream>| {
        let prev_read = h.set_compiling_form(true);
        let forms = match stream {
            Some(s) => s
                .next_form(h)
                .map(|f| f.map(|f| splice_top_forms(h, vec![f]))),
            None => reader::read_all(h, &src).map(|fs| Some(splice_top_forms(h, fs))),
        };
        h.set_compiling_form(prev_read);
        forms
    };
    let mut stream = loading.then(|| reader::FormStream::new(&src));
    let mut chunks = Vec::new();
    let mut last = Value::Undef;
    loop {
        let forms = match host::with_host(|h| read_forms(h, &mut stream)) {
            Ok(Some(forms)) => forms,
            Ok(None) => break,
            Err(e) if e == "end-of-file" && loading => {
                return Err(host::with_host(|h| {
                    let sym = h.intern("end-of-file");
                    let buf = load_buffer.clone().unwrap_or(Value::Undef);
                    let obj = h.list_from(vec![sym, buf]);
                    h.set_pending_error(&e, obj);
                    e
                }));
            }
            Err(e) => return Err(e),
        };
        run_forms(&forms, loading, &mut chunks, &mut last)?;
        if stream.is_none() {
            break;
        }
    }
    Ok((chunks, last))
}

/// Macro-expand, lower and run FORMS in order, collecting their chunks.
fn run_forms(
    forms: &[Value],
    loading: bool,
    chunks: &mut Vec<fusevm::Chunk>,
    last: &mut Value,
) -> Result<(), String> {
    for form in forms {
        // Macro-expand + lower with the host marked as COMPILING, so a symbol
        // interned here is recorded as a literal of the file rather than as
        // something the program interned while running. Only the first kind
        // belongs in the cached heap image's obarray (see
        // `ElispHost::compile_interned`); the guard is restored even on the error
        // path, because `macroexpand_all` runs user macro bodies and one of them
        // signalling must not leave the host stuck in compile mode.
        let prev = host::with_host(|h| h.set_compiling_form(true));
        let lowered = (|| -> Result<fusevm::Chunk, String> {
            let expanded = if loading {
                host::macroexpand_for_load(form)?
            } else {
                host::macroexpand_all(form)?
            };
            host::with_host(|h| compiler::compile_top(h, &expanded))
        })();
        host::with_host(|h| h.set_compiling_form(prev));
        let chunk = lowered?;
        chunks.push(chunk.clone());
        *last = host::run_chunk(chunk)?;
    }
    Ok(())
}

/// Evaluate a sequence of top-level forms (macro-expand → lower → run).
fn eval_forms(src: &str) -> Result<Value, String> {
    run_top_forms(src, None).map(|(_, last)| last)
}

/// callproc.c `set_initial_environment`: `process-environment` is the
/// process's environment as `NAME=VALUE` strings, last variable first (each
/// one is consed on in `environ` order), and `initial-environment` a copy.
///
/// Per-run state: it is installed before the prelude loads (env.el's
/// `getenv` reads it there, as Emacs's preloaded Lisp does), again after a
/// snapshot restore, and on every script run, so neither the prelude snapshot
/// nor the bytecode cache's heap image ever supplies a stale environment.
fn install_process_environment() {
    host::with_host(|h| {
        let entries: Vec<String> = std::env::vars_os()
            .map(|(k, v)| format!("{}={}", k.to_string_lossy(), v.to_string_lossy()))
            .collect();
        let strings: Vec<Value> = entries
            .iter()
            .rev()
            .map(|e| h.new_string(e.clone()))
            .collect();
        let copy: Vec<Value> = strings.clone();
        let process_env = h.list_from(strings);
        let initial_env = h.list_from(copy);
        let pe = h.intern("process-environment");
        let ie = h.intern("initial-environment");
        let _ = h.set_value(&pe, process_env);
        let _ = h.set_value(&ie, initial_env);
    });
}

/// startup.el abbreviates file names while Emacs starts, which fixes
/// `abbreviated-home-dir` (and its `home` property) from the `HOME` of that
/// moment; a later change to `HOME` in `process-environment` does not move
/// it. Per-run state like the environment it is computed from.
fn install_abbreviated_home_dir() {
    // The call runs searches; it must not leave its match data behind.
    let saved = host::with_host(|h| h.match_data.clone());
    let f = host::with_host(|h| {
        let var = h.intern("abbreviated-home-dir");
        let _ = h.set_value(&var, Value::Undef);
        h.intern("abbreviate-file-name")
    });
    let root = host::with_host(|h| h.new_string("/".to_string()));
    let _ = host::call_function(&f, &[root]);
    host::with_host(|h| h.match_data = saved);
}

/// Load the derived-surface prelude once per host, best-effort (a broken
/// definition is skipped, not fatal).
fn load_prelude() {
    if host::prelude_loaded() {
        return;
    }
    // A thread that has loaded the prelude once keeps the resulting host, so a
    // later `reset_host` restores it by copy rather than lowering every
    // preloaded-Lisp form again. See `host::restore_prelude_snapshot`.
    if host::restore_prelude_snapshot() {
        install_process_environment();
        host::with_host(crate::builtins::install_exec_path);
        install_abbreviated_home_dir();
        return;
    }
    host::set_prelude_loaded(true);
    install_process_environment();
    // The prelude models Emacs's *preloaded* Lisp, which a real Emacs ships
    // byte-compiled. See `compiler::OPEN_CODED`.
    host::set_prelude_compiling(true);
    // The nadvice segment is loaded after the core PRELUDE because it depends on
    // oclosure/gv/cl-lib defined there (and is kept separate — see prelude::NADVICE).
    for src in [prelude::PRELUDE, prelude::NADVICE]
        .into_iter()
        .chain(prelude_31::SEGMENTS)
    {
        let Ok(forms) = host::with_host(|h| reader::read_all(h, src)) else {
            continue;
        };
        for form in &forms {
            let r = (|| -> Result<(), String> {
                let expanded = host::macroexpand_all(form)?;
                let chunk = host::with_host(|h| compiler::compile_top(h, &expanded))?;
                host::run_chunk(chunk)?;
                Ok(())
            })();
            if let Err(e) = r {
                eprintln!("elisprs: prelude form failed: {e}");
            }
        }
    }
    // Emacs's preloaded Lisp is byte-compiled, so the macros it expands never
    // advance `gensym-counter' at startup: `emacs -Q' answers `g0' to its first
    // `(gensym)'. Expanding the prelude here did advance it.
    host::with_host(|h| {
        let counter = h.intern("gensym-counter");
        let _ = h.set_raw_global(&counter, Value::Int(0));
    });
    unload_rx_after_prelude();
    host::with_host(|h| {
        let end = h.arena_len();
        h.set_prelude_end(end);
    });
    host::set_prelude_compiling(false);
    host::save_prelude_snapshot();
    install_abbreviated_home_dir();
}

/// Put `rx` back where a dumped Emacs has it: not a feature, its entry points
/// autoloads. lisp-mode.el's `rx` / `rx-define` forms are expanded when Emacs
/// byte-compiles it, so `emacs -Q` never loads rx.el at startup; expanding them
/// while the prelude loads did, through the autoloads. The `"rx"` entries of
/// [`prelude_31::AUTOLOADS`] are re-installed after unbinding what rx.el
/// defined over them (`autoload` leaves a non-autoload definition alone).
fn unload_rx_after_prelude() {
    let Ok(forms) = host::with_host(|h| reader::read_all(h, prelude_31::AUTOLOADS)) else {
        return;
    };
    let fmakunbound = host::with_host(|h| h.intern("fmakunbound"));
    for form in &forms {
        let target = host::with_host(|h| {
            let v = h.list_vec(form)?;
            let is_rx = h.sym_name(v.first()?).as_deref() == Some("autoload")
                && h.str_text(v.get(2)?) == Some("rx");
            // (autoload 'SYM "rx" ...): SYM is the second element of (quote SYM).
            is_rx.then(|| h.list_vec(&v[1])?.get(1).cloned()).flatten()
        });
        let Some(sym) = target else { continue };
        let r = (|| -> Result<(), String> {
            host::call_function(&fmakunbound, &[sym])?;
            let expanded = host::macroexpand_all(form)?;
            let chunk = host::with_host(|h| compiler::compile_top(h, &expanded))?;
            host::run_chunk(chunk)?;
            Ok(())
        })();
        if let Err(e) = r {
            eprintln!("elisprs: prelude form failed: {e}");
        }
    }
    host::with_host(|h| {
        let features = h.intern("features");
        let rx = h.intern("rx");
        let kept: Vec<Value> = h
            .raw_global_value(&features)
            .ok()
            .and_then(|l| h.list_vec(&l))
            .unwrap_or_default()
            .into_iter()
            .filter(|f| !h.values_eq(f, &rx))
            .collect();
        let list = h.list_from(kept);
        let _ = h.set_raw_global(&features, list);
    });
}

/// Render a value (prin1 style when `readable`).
pub fn print(v: &Value, readable: bool) -> String {
    host::with_host(|h| h.print(v, readable))
}

/// Render an internal error string as Emacs's `error-message-string` would: a
/// condition like `void-variable: foo` becomes "Symbol's value as variable is
/// void: foo". Falls back to the raw string if formatting fails.
pub fn format_error(e: &str) -> String {
    let obj = host::with_host(|h| h.make_error_object(e));
    let func = host::with_host(|h| h.intern("error-message-string"));
    match host::call_function(&func, &[obj]) {
        Ok(v) => {
            host::with_host(|h| h.str_text(&v).map(str::to_string)).unwrap_or_else(|| e.to_string())
        }
        _ => e.to_string(),
    }
}

/// Bind `load-file-name`/`load-true-file-name`/`load-in-progress` to `path`'s
/// absolute form for the duration of `run`, then restore them (even on error).
///
/// Emacs never evaluates an init/startup file "bare": it loads it via `load`
/// (`emacs -l FILE`, and the startup init-file load), so `load-file-name` is
/// bound to the file while its forms run. `eval_file` is elisprs's `emacs -l`
/// path, so it binds the same vars — otherwise `(file-name-directory
/// load-file-name)`, which real init files (e.g. Spacemacs `init.el`) use to
/// locate sibling files, sees a void/nil variable.
///
/// `lexical-binding` is bound to the file's cookie as well
/// ([`host::file_lexical_cookie`]), which is what `load` does.
fn with_load_file_name<T>(
    path: &str,
    src: &str,
    run: impl FnOnce() -> Result<T, String>,
) -> Result<T, String> {
    let abs = host::with_host(|h| {
        let text = host::load_abspath(path).to_string_lossy().into_owned();
        h.new_string(text)
    });
    let depth = host::with_host(|h| {
        let d = h.specdepth();
        let lfn = h.intern("load-file-name");
        let ltn = h.intern("load-true-file-name");
        let lip = h.intern("load-in-progress");
        let _ = h.specbind(&lfn, abs.clone());
        let _ = h.specbind(&ltn, abs.clone());
        let _ = h.specbind(&lip, Value::Bool(true));
        let lb = h.intern("lexical-binding");
        let _ = h.specbind(&lb, Value::Bool(host::file_lexical_cookie(src)));
        d
    });
    let r = run();
    host::with_host(|h| h.unbind_to(depth));
    r
}

/// Which Emacs invocation `elisp FILE` is standing in for.
///
/// The two differ in the buffer the file's forms run in, and therefore in the
/// syntax table every `char-syntax` / `\sC` / `skip-syntax-*` answer comes from.
/// Measured on GNU Emacs 30.2 with the same probe file:
///
/// ```text
/// emacs -Q --batch -l probe.el  => buffer "*scratch*", lisp-interaction-mode,
///                                  (char-syntax ?.) => 95 (?_)
/// emacs --script    probe.el    => buffer " *load*",   fundamental-mode,
///                                  (char-syntax ?.) => 46 (?.)
/// ```
///
/// [`EntryPoint::Load`] is the default and the column `scripts/fuzz_parity.sh`
/// compares against.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum EntryPoint {
    /// `emacs -l FILE`: the file is loaded, `*scratch*` stays current.
    Load,
    /// `emacs --script FILE`: the file is evaluated *in* the ` *load*` buffer, so
    /// it reads the standard syntax table rather than the elisp-mode one.
    Script,
}

/// Entry-point state that depends on *this* invocation rather than on the
/// prelude, applied to a host that is ready to run the script's forms.
///
/// All of it must be applied on the cache-hit path as well as the cache-miss
/// path: a hit skips the prelude entirely, and the argument list is different on
/// every run, so none of it can be baked into the heap image.
///
/// - ` *load*` is the buffer `load` reads the file through. `emacs -Q --batch
///   --eval` reports three buffers, `emacs -Q --batch -l FILE` reports four; the
///   slot is reserved in the built-in prefix (see `ElispHost::open_load_buffer`)
///   precisely so both cache paths see the same arena handle. Under
///   [`EntryPoint::Script`] it also becomes *current*, which is the whole
///   observable difference between the two entry points.
/// - `command-line-args-left` (and its alias `argv`) is everything after the
///   script path, matching `emacs -l FILE a b c` => `("a" "b" "c")`;
///   `command-line-args` is the whole invocation.
fn install_entry_point_state(path: &str, src: &str, entry: EntryPoint) {
    install_process_environment();
    host::with_host(crate::builtins::install_exec_path);
    install_abbreviated_home_dir();
    // The initial buffer's syntax table, re-installed on EVERY run.
    //
    // The prelude ends by running `initial-major-mode` in `*scratch*`, which
    // installs `lisp-interaction-mode-syntax-table` as `emacs -Q --batch` does.
    // That is a BUFFER-LOCAL binding, and buffer locals live in the buffer
    // struct, not in the arena — so the heap image does not carry it and a
    // cache hit, which skips the prelude entirely, left the
    // initial buffer on `standard-syntax-table`. The whole `char-syntax` /
    // `\sC` / `skip-syntax-*` / `forward-sexp` family then answered the
    // `--script` column on a warm cache and the `-l` column on a cold one:
    //
    //   $ elisp probe.el   # cold: (char-syntax ?.) => 95   (correct)
    //   $ elisp probe.el   # warm: (char-syntax ?.) => 46   (the standard table)
    //
    // Setting it here — the one place both cache paths run through — is the
    // same treatment `command-line-args` gets below, and for the same reason:
    // per-run state must never be reconstructed from the image. It happens
    // before the ` *load*` buffer is opened or selected, so it lands on the
    // initial buffer; `--script` then selects ` *load*`, whose own local is
    // unset, and correctly reads the standard table.
    host::with_host(|h| {
        let tbl_sym = h.intern("lisp-interaction-mode-syntax-table");
        if let Ok(tbl) = h.get_value(&tbl_sym) {
            let cur = h.intern("--current-syntax-table--");
            let _ = h.set_value(&cur, tbl);
        }
    });
    let load_buf = host::with_host(|h| h.open_load_buffer(src, true));
    if entry == EntryPoint::Script {
        host::with_host(|h| {
            let obj = h.buffer_object(load_buf);
            let _ = h.set_buffer(&obj);
        });
    }
    let args: Vec<String> = std::env::args().collect();
    // Everything after the script argument. `main` picks the first non-flag
    // argument as the file, so find that same one rather than assuming a slot.
    let tail: Vec<String> = match args.iter().position(|a| a == path) {
        Some(i) => args[i + 1..].to_vec(),
        None => Vec::new(),
    };
    host::with_host(|h| {
        let left: Vec<Value> = tail.into_iter().map(|s| h.new_string(s)).collect();
        let all: Vec<Value> = args.iter().cloned().map(|s| h.new_string(s)).collect();
        let all = h.list_from(all);
        let left = h.list_from(left);
        let cla = h.intern("command-line-args");
        let left_sym = h.intern("command-line-args-left");
        let _ = h.set_value(&cla, all);
        let _ = h.set_value(&left_sym, left);
    });
}

/// Run a `.el` file as `emacs -l FILE` would. See [`eval_file_as`].
pub fn eval_file(path: &str) -> Result<Value, String> {
    eval_file_as(path, EntryPoint::Load)
}

/// Run a `.el` file as `emacs --script FILE` would: the forms are evaluated in
/// the ` *load*` buffer, whose syntax table is the standard one.
pub fn eval_script(path: &str) -> Result<Value, String> {
    eval_file_as(path, EntryPoint::Script)
}

/// Run a `.el` file, using the rkyv bytecode cache at `~/.elisprs/scripts.rkyv`.
/// On a fresh hit, the per-form chunks + a clean heap image are loaded and run
/// directly — skipping read / macro-expand / lower AND the prelude rebuild.
pub fn eval_file_as(path: &str, entry: EntryPoint) -> Result<Value, String> {
    let mtime_ns = std::fs::metadata(path)
        .ok()
        .and_then(|m| m.modified().ok())
        .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
        .map(|d| d.as_nanos() as i64)
        .unwrap_or(0);

    // Schema key folds the builtin layout + prelude into the version, so editing
    // either invalidates stale bytecode without a manual version bump. Computed
    // on a builtins-only host (no user file loaded yet) so it's stable per build.
    // The entry point is folded in: it selects the buffer the forms run in, and a
    // top-level form that reads the buffer can change how a *later* form
    // macro-expands, so chunks compiled under one entry point must not be
    // replayed under the other.
    let schema_key = {
        host::reset_host();
        let base = cache::schema_key(host::with_host(|h| h.builtin_fingerprint()));
        match entry {
            EntryPoint::Load => base,
            EntryPoint::Script => format!("{base}-script"),
        }
    };

    // The source is needed on BOTH paths, not just the miss: ` *load*` holds the
    // file's text in Emacs, so skipping the read on a hit would make `buffer-size`
    // depend on whether the cache was warm. Reading a script is negligible next to
    // the parse + macro-expand + lower + prelude rebuild the cache actually skips.
    let src = std::fs::read_to_string(path).map_err(|e| e.to_string())?;

    let debug = std::env::var_os("ELISPRS_CACHE_DEBUG").is_some();
    if let Some(cached) = cache::get(path, mtime_ns, &schema_key) {
        let cache::CachedScript {
            chunks,
            heap,
            oclosure_meta,
            introspection_cells,
            builtin_cells,
            buffer_state,
            base_len,
        } = cached;
        if debug {
            eprintln!("elisprs: cache HIT  {path} ({} chunks)", chunks.len());
        }
        host::reset_host();
        host::with_host(|h| {
            let end = h.builtin_count() + base_len;
            h.import_heap_image(heap);
            h.set_prelude_end(end);
            // The OClosure table is built when the prelude runs, which this hit
            // skips — restore it or every prelude OClosure comes back as a plain
            // closure.
            h.import_oclosure_meta(oclosure_meta);
            // Same for the introspection function cells: `when`/`unless` register
            // theirs from the prelude, so without this a warm run answers
            // `(fboundp 'when)` nil where a cold one answers `t`.
            h.import_intrinsic_macro_cells(introspection_cells);
            // The prelude's writes to symbols BELOW `builtin_count` — the ones
            // `heap` cannot carry because it starts at that line. Without this a
            // warm run lost every prelude-installed cell on a builtin symbol.
            h.import_builtin_cells(builtin_cells);
            // The always-local slots and every buffer's locals, which the
            // prelude builds in the buffer structs rather than the arena.
            h.import_buffer_state(buffer_state);
        });
        install_entry_point_state(path, &src, entry);
        return with_load_file_name(path, &src, || {
            let mut last = Value::Undef;
            for chunk in chunks {
                last = host::run_chunk(chunk)?;
            }
            Ok(last)
        });
    }
    if debug {
        eprintln!("elisprs: cache MISS {path}");
    }

    // Cache miss: compile + run form-by-form (so an in-file defmacro is in effect
    // before later forms), capturing each chunk and a clean heap image.
    host::reset_host();
    load_prelude();
    let builtin_count = host::with_host(|h| h.builtin_count());
    let prelude_end = host::with_host(|h| h.arena_len());
    // The clean prelude heap, captured BEFORE the file runs: this is the state the
    // cached chunks replay onto, so it must not contain any of their effects.
    // Also before `install_entry_point_state`, so THIS run's argv never reaches
    // the cached image and the next run's `install_entry_point_state` is the only
    // thing that sets it.
    let clean_prelude = host::with_host(|h| h.export_heap_range(builtin_count, prelude_end));
    // Captured with `clean_prelude` and for the same reason: this is the state a
    // hit replays the cached chunks onto, so it must predate the file's own run.
    let clean_builtin_cells = host::with_host(|h| h.export_builtin_cells());
    let clean_buffer_state = host::with_host(|h| h.export_buffer_state());
    install_entry_point_state(path, &src, entry);

    // Bind load-file-name only while the forms run; unbind before the clean heap
    // image is captured so the cached image carries no transient load binding.
    let load_buffer = host::with_host(|h| h.load_buffer_object());
    let (chunks, last) = with_load_file_name(path, &src, || {
        run_top_forms(&src, Some(load_buffer.clone()))
    })?;
    // Only the part of the image this FILE owns: `clean_prelude` is the rest,
    // and the cache stores it once per shard rather than once per entry.
    let heap_tail = host::with_host(|h| h.export_heap_tail_clean(prelude_end));
    let oclosure_meta = host::with_host(|h| h.export_oclosure_meta());
    let introspection_cells = host::with_host(|h| h.export_intrinsic_macro_cells());
    cache::put(
        path,
        mtime_ns,
        &schema_key,
        cache::ScriptParts {
            chunks: &chunks,
            prelude_heap: &clean_prelude,
            heap_tail: &heap_tail,
            oclosure_meta: &oclosure_meta,
            introspection_cells: &introspection_cells,
            builtin_cells: &clean_builtin_cells,
            buffer_state: &clean_buffer_state,
        },
    );
    Ok(last)
}