pythonrs 0.1.15

Python as a fusevm frontend: lexer, parser, and compiler to fusevm::Chunk on a PyHost heap — the first compiled standalone Python runtime
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
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
//! rkyv-backed bytecode cache for compiled Python scripts (mirrors the fleet's
//! zshrs/rubylang design). Every ordinary `python foo.py` run is transparently
//! cached: the source is hashed, the shard consulted, and on a hit the compiled
//! `fusevm::Chunk`s run directly — lex/parse/lower are skipped entirely. On a
//! miss the program is compiled, stored, then run. `python --build` warms the
//! same shard ahead of time.
//!
//! Layout: a single shard at `~/.pythonrs/scripts.rkyv`, as
//! `[u64 index length][index][blobs]`. The *index* is a zero-copy rkyv archive
//! (`Index`) of `(key, verify, source, offset, length)` rows, validated in
//! place on a memory-mapped shard;
//! each *blob* is a bincode-encoded `CProg` (the compiled `fusevm::Chunk`s +
//! func/try tables) read by offset, because `fusevm::Chunk` is serde-owned, not
//! `rkyv::Archive`. The blobs sit OUTSIDE the archive so that validating it
//! stays proportional to the number of entries rather than to their total size —
//! see `Index`. The key is a 64-bit hash of the source, a schema version, the
//! build's `CARGO_PKG_VERSION`, and a fingerprint of the running executable, so
//! a source, format, release, or REBUILD change misses cleanly instead of
//! loading stale bytecode.
//!
//! A store keeps the most recently stored entries within `MAX_BLOB_BYTES` and
//! drops the rest, oldest first. Entries an earlier build wrote can never hit
//! again; the budget is what retires them.

use crate::ast::Span;
use crate::compiler::Program;
use crate::host::{FuncDef, TryDef};
use fusevm::Chunk;
use rkyv::{Archive, Deserialize as RkyvDe, Serialize as RkyvSer};
use serde::{Deserialize, Serialize};
use std::hash::{Hash, Hasher};
use std::path::PathBuf;

/// Bump on any incompatible change to `CProg` / the lowering / the shard layout.
/// v3: new builtin op ids + generator/comprehension-as-function/match/unpack
/// lowering — bytecode compiled by any earlier pythonrs must miss cleanly.
/// v4: `yield from` now lowers to the `GENRET` op (delegated return value); older
/// cached bytecode for a `yield from` would drop the value, so it must miss.
/// v5: `MKFUNC` carries keyword-only defaults + a count below the func id; older
/// bytecode uses the 1-arg-only layout and must miss cleanly.
/// v6: `raise X from Y` now emits `RAISE` with argc 2 (cause pushed under exc);
/// older bytecode dropped the cause, so it must miss cleanly.
/// v7: the lexer decodes `\NNN` octal string escapes; older bytecode baked the
/// undecoded literal into the chunk, so it must miss cleanly.
/// v8: `FuncDef` gained a `posonly` count (positional-only enforcement); older
/// serialized func templates lack it and must miss cleanly.
/// v9: comprehensions now inject a `global`/`nonlocal` declaration for walrus
/// (`:=`) targets so they leak to the enclosing scope; older bytecode lacks the
/// declaration and must miss cleanly.
/// v10: `BUILD_CLASS` takes a 4th arg (the explicit metaclass, or `None`) pushed
/// below the bases; older 3-arg bytecode must miss cleanly.
/// v12: f-string format specs are compiled as their own joined-string so nested
/// replacement fields (`{w}` in `{x:{w}.2f}`) evaluate at runtime; older bytecode
/// baked the spec as a literal constant and must miss cleanly.
/// v15: augmented assignment emits the `INPLACE` op (the CPython in-place-dunder
/// protocol) instead of a plain `x = x <op> y` rebind; `with` uses the hit-flag
/// `__exit__` desugar; chained comparisons bind interior operands to walrus temps
/// for single-evaluation. All three change lowering, so older cached bytecode
/// (which would run the old rebind / re-evaluating forms) must miss cleanly.
/// v16: `yield from` lowers to a single `YIELD_FROM` op (full PEP 380 delegation:
/// sent values, thrown exceptions, and close forwarded into the sub-iterator)
/// instead of the old FORITER/YIELDV/GENRET loop that dropped sent values.
/// v17: a loop whose `break`/`continue` crosses a `try`/`with` boundary lowers
/// its body to a `LOOP_BODY` sub-chunk driven by control signals (so a `finally`
/// runs before the loop exit) instead of an in-chunk jump; `CProg` gained a
/// `warnings` list (compile-time `SyntaxWarning`s). Older bytecode used the jump
/// form (which panicked on that shape) and lacks the field, so it must miss.
/// v18: `match` singleton value patterns (None/True/False) lower to an identity
/// check (`IS`) instead of `NumEq`, matching PEP 634 (`0` no longer matches
/// `case False`). Older bytecode used `NumEq` and would mismatch, so it must miss.
/// v19: `FuncDef` gained a `locals` set (names local to the scope) so a read of a
/// function-local name before it is bound raises `UnboundLocalError` instead of
/// falling through to an enclosing/global binding. Older bytecode lacks the field
/// and would give the wrong error, so it must miss.
/// v20: `FuncDef` gained a `qualname` (`__qualname__`) so function introspection
/// dunders resolve. Older bytecode lacks the field, so it must miss.
/// v21: a class body now lowers its simple annotations (`x: int`) into an
/// `__annotations__` dict (SETUP + per-field SETITEM), so `dataclass`/
/// `typing.NamedTuple` and `Cls.__annotations__` see the fields; also large
/// collection literals (over 255 elements) lower via the `EXTEND_*` ops. Older
/// cached bytecode lacks the annotation/extend lowering and must miss cleanly.
/// v22: `CProg.warnings` entries now carry the full `SyntaxWarning` text (not
/// just a keyword), and the compiler adds the `"is" with a literal` warning.
/// Older cached warnings held bare keywords and would print malformed.
/// v23: `MKFUNC` carries an `__annotations__` dict as its deepest arg (built from
/// param/return annotations at def time) and `FuncVal` gained an `annotations`
/// field; also `...` lowers to the new `ELLIPSIS` op (a distinct `Ellipsis`
/// singleton) instead of `LoadUndef` (`None`). Older bytecode used the
/// annotation-free layout / conflated `...` with `None` and must miss cleanly.
/// v24: `CProg` gained a `positions` list (traceback-caret op-index → span tables)
/// and the loader recomputes each chunk's `op_hash` (skipped by serde) so caret
/// lookups match. Older entries lack the field and must miss cleanly.
/// v25: `Entry` gained a `source` name (script path / `<string>` / `<stdin>`) for
/// `--cacheview` provenance; the added rkyv field changes the shard layout, so
/// older shards fail to decode and rebuild.
/// v26: new `IMPORT_STAR` opcode for `from m import *` — the compiler now emits
/// different bytecode for a star-import, so any entry cached under v25 (which
/// mis-emitted it as an `IMPORT_FROM "*"` attribute fetch) must miss and recompile.
/// v27: `FuncDef` gained `freevars` (drives `func.__closure__`/`co_freevars` and
/// the `CO_NOFREE` flag); recompile so closures carry their free-variable list.
/// v28: new `IMPORT_RELATIVE` opcode — a relative `from . import x` now compiles
/// to a runtime-resolved import (previously the leading dots were dropped and the
/// module name collapsed to `""`), so cached star/relative-import bytecode misses.
/// v29: PEP 695 type parameters (`class C[T]`, `def f[T]`) now parse and emit
/// `T = object` bindings; files that previously failed to compile now do, so any
/// stale negative-cache/relative bytecode must rebuild.
/// v30: `import a.b.c` now binds the TOP package `a` (re-importing it) instead of
/// the leaf submodule, so the emitted bytecode differs for any dotted `import`.
/// v31: a `def`/`lambda` with annotations compiles them as a `<annotate>` thunk
/// (MKFUNC evaluates it with forward-reference NameErrors caught) instead of an
/// inline dict, so annotated-function bytecode differs.
/// v49: private-name mangling — every `__name` written inside a class body
/// compiles as `_Class__name`, so the attribute/name constants of any chunk
/// holding a class with a private member differ. Verified stale: a script
/// cached by the pre-mangling binary at the same `BUILD_VERSION` kept printing
/// `{'__x': 1}` under the new one instead of `{'_C__x': 1}`.
/// v48: the `with` desugar calls its entry through the `.__enter__` /
/// `.__aenter__` sentinel so the context-manager protocol check runs before the
/// call; a chunk cached before this holds the bare name and would skip it.
/// v47: an attribute STORE (`SETATTR`) and both DELETE forms (`DELATTR`,
/// `DELITEM`) now carry the statement line and the target's caret span; a
/// parenthesized with-item list (`with (a as x, b as y):`) parses at all. The
/// line and position tables of any chunk holding one of those differ.
/// v46: a set/dict/list/tuple display, a `{**a, …}` merge, and a subscript
/// STORE now carry the statement's line number and the expression's caret span
/// (they emitted line 0, so an unhashable key rendered `line 0` with no source
/// line). The line table and the position table of any chunk containing one of
/// those differ.
/// v45: a call whose callee is a BARE NAME resolves the name before the
/// arguments (CPython order) and calls by value, so every such call site emits
/// different bytecode.
/// v44: `except*` compiles to its own handler flag on `TryDef` (a new field in
/// the cached record), and `await`/`:=`-in-a-comprehension now fail at compile
/// time — so sources that used to cache successfully must be recompiled.
/// v43: a call whose callee is a slotted local pushes it as a VALUE rather than
/// resolving the name, so any such call site's bytecode differs.
/// v42: an eligible function holds its locals in frame slots (`GetSlot`/
/// `SetSlot`) instead of resolving them by name, so every such function's
/// bytecode differs.
/// v41: a class body seeds `__annotations__` when it annotates a bare name at ANY
/// depth, not only at top level, so a class holding an annotation inside an
/// `if`/`try`/`with` compiles to different bytecode.
/// v40: PEP 750 t-strings — `t"..."` lowers to `INTERPOLATION`/`TEMPLATE` calls
/// (new opcodes), and every f-string field now carries its source text, so any
/// chunk holding a string literal with replacement fields differs.
/// v39: a native counted loop type-guards the values it seeds slots with and is
/// emitted alongside a generic copy to fall back to (loop versioning), so any
/// loop that reads a namespace name compiles to different bytecode.
/// v38: `(a*b) % k` / `(a*b + c) % k` fuse into fusevm `MulModFloor` /
/// `MulAddModFloor`, changing the emitted ops for those expressions.
/// v37: `%` by an integer literal inside a native slot loop lowers to native
/// `Mod` + a branchless floor correction instead of the `BINOP` host call, so
/// loops containing `%` emit different bytecode (and now qualify as native).
/// v50: the shard is split into a small archived INDEX and a raw blob region
/// (`[u64 index_len][index archive][blobs]`) instead of one archive holding the
/// blobs inline. A v49 shard's first eight bytes are archive data, not a length,
/// so it is rejected as unreadable and rebuilt.
/// v51: a method call `recv.name(...)` resolves its callee before the arguments
/// (`LOAD_METHOD`, then `CALL_LOADED`/`CALL_LOADED_KW`/`CALL_LOADED_EX`, the
/// last two reusing the ids of the retired `CALL_METHOD_KW`/`CALL_METHOD_EX`),
/// so every method-call site emits different bytecode.
/// v52: an annotation scope in a class body (`FuncDef::sees_class_scope`, a new
/// field) captures the class environment, so a class body holding an
/// annotation, an annotated method or a `type` alias compiles differently.
/// v53: a function's `__annotate__` is marked (`FuncDef::is_annotate`, a new
/// field) so its code object names the parameter `format`.
/// v54: a `raise` statement's op carries the statement's extent as its caret span.
/// v55: `BUILD_CLASS` carries the class statement's line.
/// v56: `CProg.warnings` leads with the invalid-escape `SyntaxWarning`s the
/// tokenizer and the f-string parser raise.
/// v57: a read of a free variable (`cur_freevars`) lowers to `GETFREE`, whose
/// unbound error is CPython's `cannot access free variable` wording.
/// v58: a chunk's constant pool ends with a hash of its position table, so
/// chunks with identical ops at different source positions hash differently.
/// v59: a slotted function's prologue no longer loads its parameters by name;
/// the call binds them into slots (`FuncDef::params_in_slots`, a new field).
/// v60: the main chunk ends with a copy of each linkable function body
/// (`FuncDef::linked`, a new field), reached by a jump over them.
/// v61: a slot-safe function reads a name it neither slots nor closes over
/// with `GETGLOBAL`.
/// v62: a method that reads `__class__` is marked (`FuncDef::binds_class_cell`,
/// a new field) and the read walks the environment.
/// v63: every function whose body has no `try`/`with` is linked, not only the
/// slot-safe ones.
const SCHEMA: u64 = 63;

/// The shard's INDEX: everything a lookup needs, and nothing it does not.
///
/// The blobs live outside this archive on purpose. rkyv validates a whole
/// archive from its root before anything in it may be read, and validating a
/// `Vec<u8>` is linear in its bytes — so holding the blobs inline made the cost
/// of ANY lookup proportional to the total size of every program ever cached
/// (0.20s of a 0.21s `python empty.py` against a 19.6 MiB shard). Split out, the
/// validated region is the index alone — a few dozen bytes per entry — and the
/// blob is a byte range read by offset, checked by bincode when it is decoded.
#[derive(Archive, RkyvSer, RkyvDe, Default)]
#[archive(check_bytes)]
struct Index {
    entries: Vec<IndexEntry>,
}

#[derive(Archive, RkyvSer, RkyvDe, Clone)]
#[archive(check_bytes)]
struct IndexEntry {
    key: u64,
    /// A second, independent hash of the source. A cache hit requires BOTH `key`
    /// and `verify` to match, so an `FxHash` collision on `key` can never return
    /// a different program's bytecode (which would silently produce wrong
    /// results — far worse than a cache miss).
    verify: u64,
    /// The source name that last produced this entry — a script path, `<string>`
    /// (`-c`), or `<stdin>`. The cache keys by source CONTENT, so this is
    /// best-effort provenance for `--cacheview`, not part of the lookup.
    source: String,
    /// Where this entry's bincode blob starts, relative to the blob region.
    off: u64,
    len: u64,
}

/// The inner, serde/bincode form of a compiled program.
#[derive(Serialize, Deserialize)]
struct CProg {
    main: Chunk,
    functions: Vec<(String, FuncDef)>,
    tries: Vec<TryDef>,
    warnings: Vec<(u32, String)>,
    /// Traceback-caret position tables, `(chunk op_hash, op-index → span)`.
    positions: Vec<(u64, Vec<Span>)>,
}

/// The release this binary was built as. It is hashed into every cache key
/// alongside [`SCHEMA`], so a shard written by one release can never be read by
/// another.
const BUILD_VERSION: &str = env!("CARGO_PKG_VERSION");

/// A fingerprint of the RUNNING BINARY — its own size and modification time.
///
/// This is what actually keeps the cache honest between two builds, and neither
/// of the other two key components can do it:
///
/// * [`BUILD_VERSION`] only changes at a release. Every build in between shares
///   it.
/// * [`SCHEMA`] is bumped BY HAND. Every lowering change is *supposed* to bump
///   it, and the one that forgets ships a binary that silently executes the
///   PREVIOUS build's bytecode out of `~/.pythonrs/scripts.rkyv`. There is no
///   error and no wrong answer to chase — the program simply behaves as it did
///   before the change, and the symptom is "my fix did not take".
///
/// That is not hypothetical: a compiler change that began emitting a
/// `SyntaxWarning` appeared to do nothing for any script already in the shard,
/// on a binary rebuilt seconds earlier, because the key had no term that a
/// rebuild moves. Every script cached before the change kept its old bytecode
/// until the shard was cleared by hand.
///
/// Size and mtime rather than a content hash of the executable: the binary is
/// ~57 MB, and hashing it on every run would cost far more than the compile the
/// cache exists to skip. A rebuild always moves the mtime, and an installed
/// release binary holds both steady, which is exactly the wanted behavior on
/// each side. If the executable cannot be located the fingerprint is `0` and the
/// key falls back to the previous `SCHEMA` + version pair — no worse than before.
fn build_fingerprint() -> u64 {
    static FINGERPRINT: once_cell::sync::Lazy<u64> = once_cell::sync::Lazy::new(|| {
        use std::collections::hash_map::DefaultHasher;
        let Ok(meta) = std::env::current_exe().and_then(std::fs::metadata) else {
            return 0;
        };
        let mut h = DefaultHasher::new();
        meta.len().hash(&mut h);
        if let Ok(t) = meta.modified() {
            if let Ok(d) = t.duration_since(std::time::UNIX_EPOCH) {
                d.as_nanos().hash(&mut h);
            }
        }
        h.finish()
    });
    *FINGERPRINT
}

/// A stable content key for a source string (fast `FxHash`, used for lookup).
///
/// The optimization level is part of the key, as it is part of a `.pyc`'s name
/// (`opt-1`/`opt-2`): a chunk compiled under `-O` has no asserts and one compiled
/// under `-OO` has no docstrings, so neither may be served to a run at another
/// level.
pub fn key_for(src: &str) -> u64 {
    let mut h = rustc_hash::FxHasher::default();
    SCHEMA.hash(&mut h);
    BUILD_VERSION.hash(&mut h);
    build_fingerprint().hash(&mut h);
    crate::host::optimize_level().hash(&mut h);
    src.hash(&mut h);
    h.finish()
}

/// An independent verification hash (std `DefaultHasher`/SipHash), so a hit
/// requires both hashes to agree — collision-proof for correctness.
fn verify_for(src: &str) -> u64 {
    use std::collections::hash_map::DefaultHasher;
    let mut h = DefaultHasher::new();
    SCHEMA.hash(&mut h);
    BUILD_VERSION.hash(&mut h);
    build_fingerprint().hash(&mut h);
    crate::host::optimize_level().hash(&mut h);
    src.len().hash(&mut h);
    src.hash(&mut h);
    h.finish()
}

fn shard_path() -> Option<PathBuf> {
    let dir = dirs::home_dir()?.join(".pythonrs");
    let _ = std::fs::create_dir_all(&dir);
    Some(dir.join("scripts.rkyv"))
}

/// An exclusive advisory lock (`flock`) over the shard, held for the duration of
/// a read-modify-write. Up to 16 instances share one shard; without this, two
/// writers both load the same base, both rewrite it, and the losing rename drops
/// the other's entry. Serializing the whole load→append→write under the lock
/// makes every writer re-read the latest shard, so no entry is ever lost — while
/// keeping the single authoritative store (readers still mmap the renamed file;
/// the lock is a sibling `.lock`, never in the read path).
struct ShardLock(std::fs::File);

impl Drop for ShardLock {
    /// Release the advisory lock explicitly. Dropping the `File` would release
    /// it anyway (closing the fd drops the `flock`), but unlocking by name keeps
    /// the guard's whole purpose visible at the point it happens — and reads the
    /// field, which is otherwise held purely for that side effect.
    fn drop(&mut self) {
        use std::os::unix::io::AsRawFd;
        // SAFETY: `self.0` is an open fd for the lifetime of this guard.
        unsafe { libc::flock(self.0.as_raw_fd(), libc::LOCK_UN) };
    }
}

impl ShardLock {
    fn acquire() -> Option<Self> {
        use std::os::unix::io::AsRawFd;
        let path = shard_path()?.with_extension("lock");
        let f = std::fs::OpenOptions::new()
            .create(true)
            .write(true)
            // A lock file carries no data; never truncate a peer holder's file.
            .truncate(false)
            .open(&path)
            .ok()?;
        // Blocking exclusive lock; released when `f` is dropped (fd closed).
        if unsafe { libc::flock(f.as_raw_fd(), libc::LOCK_EX) } != 0 {
            return None;
        }
        Some(ShardLock(f))
    }
}

/// The fixed prefix: the byte length of the index archive that follows it.
const INDEX_LEN_BYTES: usize = 8;

/// Split shard bytes into `(index archive, blob region)`.
///
/// Every malformed shape — too short to hold the length, a length that overruns
/// the file, a v49 archive whose first eight bytes happen to parse as a huge
/// number — answers `None`, which the callers read as "no usable cache" and
/// rebuild. A shard is a cache: an unreadable one costs a recompile, never an
/// error.
fn split_shard(bytes: &[u8]) -> Option<(&[u8], &[u8])> {
    let raw = bytes.get(..INDEX_LEN_BYTES)?;
    let n = u64::from_le_bytes(raw.try_into().ok()?) as usize;
    let rest = bytes.get(INDEX_LEN_BYTES..)?;
    (n <= rest.len()).then(|| rest.split_at(n))
}

/// Map the shard read-only. A lookup touches only the index and one blob, so
/// reading the whole file made every script start pay for the size of every
/// program ever cached.
fn map_shard() -> Option<memmap2::Mmap> {
    let file = std::fs::File::open(shard_path()?).ok()?;
    // SAFETY: the shard is never modified in place. `write_shard` renames a
    // complete temp file over it, which leaves an existing mapping on the old
    // inode, and `clear` only unlinks it.
    unsafe { memmap2::Mmap::map(&file) }.ok()
}

/// The whole shard file alongside its decoded index — the form the rare paths
/// (`store`, `--cacheview`, `--doctor`) want, since they walk every entry. A
/// LOOKUP must not come through here: it would pay for decoding the index rows
/// it will not read. [`load`] reads the index in place instead.
fn read_shard() -> Option<(memmap2::Mmap, Index)> {
    let bytes = map_shard()?;
    let (index, _) = split_shard(&bytes)?;
    let index: Index = rkyv::from_bytes(index).ok()?;
    Some((bytes, index))
}

/// Remove temp files left by writers that died between `write` and `rename`.
/// Only called while holding [`ShardLock`], which `store` holds across that
/// window, so a temp file seen here is orphaned rather than in progress. (A
/// writer that could not take the lock writes unlocked; deleting its temp file
/// fails its rename, which costs it the entry and nothing else.)
fn remove_orphan_temps() {
    let Some(path) = shard_path() else {
        return;
    };
    let (Some(dir), Some(name)) = (path.parent(), path.file_name()) else {
        return;
    };
    let prefix = format!("{}.tmp.", name.to_string_lossy());
    let Ok(listing) = std::fs::read_dir(dir) else {
        return;
    };
    for entry in listing.flatten() {
        if entry.file_name().to_string_lossy().starts_with(&prefix) {
            let _ = std::fs::remove_file(entry.path());
        }
    }
}

/// Write an index and its blob region as one shard file.
fn write_shard(index: &Index, blobs: &[u8]) -> Result<(), String> {
    let path = shard_path().ok_or("no home dir for cache")?;
    let archived = rkyv::to_bytes::<_, 4096>(index).map_err(|e| format!("cache serialize: {e}"))?;
    let mut bytes = Vec::with_capacity(INDEX_LEN_BYTES + archived.len() + blobs.len());
    bytes.extend_from_slice(&(archived.len() as u64).to_le_bytes());
    bytes.extend_from_slice(&archived);
    bytes.extend_from_slice(blobs);
    // Atomic replace (write temp + rename) so a concurrent reader — up to 16
    // instances run against the shared shard — never sees a torn file. A losing
    // concurrent writer just drops its entry (recompiled next run); it can never
    // corrupt the shard. The temp name is unique per WRITE (pid + a monotonic
    // counter), not just per process, so concurrent writers within one process
    // (e.g. parallel test threads) never clobber each other's temp file.
    static SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
    let n = SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    let tmp = path.with_extension(format!("rkyv.tmp.{}.{n}", std::process::id()));
    std::fs::write(&tmp, &bytes).map_err(|e| format!("cache write: {e}"))?;
    std::fs::rename(&tmp, &path).map_err(|e| {
        let _ = std::fs::remove_file(&tmp);
        format!("cache rename: {e}")
    })
}

/// Look up a compiled program for `src`, if present and current.
///
/// The INDEX is read as an archive and never deserialized: `check_archived_root`
/// validates it and hands back a reference into the bytes already read, so a
/// lookup allocates nothing but the one blob it decodes. `rkyv::from_bytes`
/// rebuilt every entry in the file — 2485 of them — to answer a question about
/// one, which was 0.42s of a 0.44s `python empty.py`; see `Index` for why
/// validating in place is not enough on its own.
pub fn load(src: &str) -> Option<Program> {
    let key = key_for(src);
    let verify = verify_for(src);
    let bytes = map_shard()?;
    let (index, blobs) = split_shard(&bytes)?;
    let index = rkyv::check_archived_root::<Index>(index).ok()?;
    let entry = index
        .entries
        .iter()
        .find(|e| e.key == key && e.verify == verify)?;
    let (off, len) = (entry.off.value() as usize, entry.len.value() as usize);
    // Deserializing a `Chunk` recomputes its `op_hash` (fusevm's `ChunkWire`),
    // so every chunk comes back keyed as the cached position tables are.
    let cp: CProg = bincode::deserialize(blobs.get(off..off.checked_add(len)?)?).ok()?;
    Some(Program {
        main: cp.main,
        functions: cp.functions,
        procs: Vec::new(),
        tries: cp.tries,
        warnings: cp.warnings,
        positions: cp.positions,
    })
}

// ── Introspection (`--doctor` / `--cacheview` / `--cache-clear`) ─────────────
// Read-only accessors mirroring the fleet's cache-introspection surface
// (elisprs `src/cache.rs`): the CLI extensions render these; the hot path
// (`load`/`store`) never touches them.

/// The schema version stamped into every cache key. Bumping it (see `SCHEMA`)
/// invalidates every prior entry cleanly.
pub const fn schema_version() -> u64 {
    SCHEMA
}

/// Path to the on-disk bytecode shard (`~/.pythonrs/scripts.rkyv`). Falls back to
/// a `/tmp` path only when there is no home directory.
pub fn default_cache_path() -> PathBuf {
    shard_path().unwrap_or_else(|| PathBuf::from("/tmp/.pythonrs/scripts.rkyv"))
}

/// `PYTHONRS_CACHE=0|false|no` disables the transparent bytecode cache (every run
/// recompiles). Any other value — or unset — leaves it on.
pub fn cache_enabled() -> bool {
    !matches!(
        std::env::var("PYTHONRS_CACHE").as_deref(),
        Ok("0") | Ok("false") | Ok("no")
    )
}

/// Entry count and on-disk byte size of the shard (`0`/`0` when absent).
pub fn stats() -> (usize, u64) {
    let count = read_shard().map_or(0, |(_, i)| i.entries.len());
    let bytes = default_cache_path()
        .metadata()
        .map(|m| m.len())
        .unwrap_or(0);
    (count, bytes)
}

/// Delete the on-disk shard. A missing shard is success (nothing to clear).
pub fn clear() -> std::io::Result<()> {
    let Some(path) = shard_path() else {
        return Ok(());
    };
    match std::fs::remove_file(&path) {
        Ok(()) => Ok(()),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(e) => Err(e),
    }
}

/// A read-only summary of one cached program, for `--cacheview`. The counts are
/// decoded from the inner bincode blob; a blob that fails to decode (stale
/// format) reports zeros rather than aborting the listing.
pub struct EntryInfo {
    /// The `FxHash` lookup key (source + schema).
    pub key: u64,
    /// The source name that produced the entry (script path / `<string>` /
    /// `<stdin>`), for provenance in the listing.
    pub source: String,
    /// The independent SipHash verification hash.
    pub verify: u64,
    /// On-disk size of the compiled blob in bytes.
    pub blob_len: usize,
    /// Ops in the `__main__` chunk.
    pub main_ops: usize,
    /// Compiled top-level functions.
    pub functions: usize,
    /// `try` bodies (own chunks, not in `main.sub_chunks`).
    pub tries: usize,
    /// Compile-time `SyntaxWarning`s stored with the program.
    pub warnings: usize,
}

/// Summarize every entry in the shard (decoding each blob's counts), in shard
/// order. Used only by `--cacheview`.
pub fn entries() -> Vec<EntryInfo> {
    let Some((bytes, index)) = read_shard() else {
        return Vec::new();
    };
    let Some((_, blobs)) = split_shard(&bytes) else {
        return Vec::new();
    };
    index
        .entries
        .iter()
        .map(|e| {
            let (off, len) = (e.off as usize, e.len as usize);
            let (main_ops, functions, tries, warnings) = blobs
                .get(off..off.saturating_add(len))
                .and_then(|b| bincode::deserialize::<CProg>(b).ok())
                .map(|cp| {
                    (
                        cp.main.ops.len(),
                        cp.functions.len(),
                        cp.tries.len(),
                        cp.warnings.len(),
                    )
                })
                .unwrap_or((0, 0, 0, 0));
            EntryInfo {
                key: e.key,
                source: e.source.clone(),
                verify: e.verify,
                blob_len: len,
                main_ops,
                functions,
                tries,
                warnings,
            }
        })
        .collect()
}

/// Store `prog` (compiled from `src`) into the shard, replacing any prior entry.
/// The `--cacheview` provenance label defaults to the runtime's traceback
/// filename (a script path, `<string>`, or `<stdin>`).
pub fn store(src: &str, prog: &Program) -> Result<(), String> {
    let source = crate::host::with_host(|h| h.tb_filename.clone());
    store_labeled(src, prog, &source)
}

/// [`store`] with an explicit provenance `source` label. Imported modules pass
/// their own file path here so `--cacheview` shows the module — otherwise every
/// module compiled during a `python -c` run would inherit the `<string>` label
/// of that run and the listing would read as `-c` churn instead of real modules.
pub fn store_labeled(src: &str, prog: &Program, source: &str) -> Result<(), String> {
    let key = key_for(src);
    let verify = verify_for(src);
    let source = source.to_string();
    let cp = CProg {
        main: prog.main.clone(),
        functions: prog.functions.clone(),
        tries: prog.tries.clone(),
        warnings: prog.warnings.clone(),
        positions: prog.positions.clone(),
    };
    let blob = bincode::serialize(&cp).map_err(|e| format!("cache encode: {e}"))?;
    // Serialize the whole read-modify-write against the other instances sharing
    // the shard, so concurrent writers merge instead of clobbering. The lock is
    // held until this function returns (the guard drops). If the lock cannot be
    // taken, fall through unlocked — a dropped entry only costs a recompile.
    let guard = ShardLock::acquire();
    if guard.is_some() {
        remove_orphan_temps();
    }
    // Rebuild the shard: the surviving blobs are COPIED, never decoded, so a
    // store costs one pass over the file rather than a round trip through every
    // program in it.
    let existing = read_shard();
    let old_blobs = existing
        .as_ref()
        .and_then(|(bytes, _)| split_shard(bytes).map(|(_, b)| b))
        .unwrap_or(&[]);
    let mut index = Index::default();
    let mut blobs: Vec<u8> = Vec::new();
    if let Some((_, old)) = existing.as_ref() {
        let budget = MAX_BLOB_BYTES.saturating_sub(blob.len() as u64);
        for e in retained(old, key, budget) {
            let (off, len) = (e.off as usize, e.len as usize);
            let Some(b) = old_blobs.get(off..off.saturating_add(len)) else {
                continue;
            };
            index.entries.push(IndexEntry {
                off: blobs.len() as u64,
                ..e.clone()
            });
            blobs.extend_from_slice(b);
        }
    }
    index.entries.push(IndexEntry {
        key,
        verify,
        source,
        off: blobs.len() as u64,
        len: blob.len() as u64,
    });
    blobs.extend_from_slice(&blob);
    write_shard(&index, &blobs)
}

/// Upper bound on the shard's blob region. Every cache miss rewrites the whole
/// shard, so its size is paid on each new script and each newly imported module.
/// At the ~43 KB a typical entry takes, this holds several hundred programs.
const MAX_BLOB_BYTES: u64 = 32 << 20;

/// The entries of `old` that a store of `new_key` carries forward, in shard
/// order: all but the one being replaced, newest first, while they fit in
/// `budget` blob bytes. A store appends at the end, so dropping from the front
/// drops the entries least recently stored.
fn retained(old: &Index, new_key: u64, budget: u64) -> Vec<&IndexEntry> {
    let mut kept = Vec::new();
    let mut used = 0u64;
    for e in old.entries.iter().rev() {
        if e.key == new_key {
            continue;
        }
        used += e.len;
        if used > budget {
            break;
        }
        kept.push(e);
    }
    kept.reverse();
    kept
}

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

    /// Both cache hashes must depend on the build version, not on `SCHEMA`
    /// alone. `SCHEMA` is bumped by hand: the release that forgets it would
    /// otherwise read the PREVIOUS release's bytecode out of the shared shard
    /// and run the wrong program with no error. Recompute each hash here with
    /// the version left out and require the real one to differ, so removing
    /// either `BUILD_VERSION.hash(&mut h)` line fails this test.
    #[test]
    fn cache_keys_depend_on_the_build_version() {
        use std::collections::hash_map::DefaultHasher;
        let src = "x = 1\n";

        let mut without = rustc_hash::FxHasher::default();
        SCHEMA.hash(&mut without);
        src.hash(&mut without);
        assert_ne!(
            key_for(src),
            without.finish(),
            "key_for must hash the build version, not just SCHEMA"
        );

        let mut without = DefaultHasher::new();
        SCHEMA.hash(&mut without);
        src.len().hash(&mut without);
        src.hash(&mut without);
        assert_ne!(
            verify_for(src),
            without.finish(),
            "verify_for must hash the build version, not just SCHEMA"
        );

        // …and the version that is hashed is this build's, so a release bump
        // rotates the whole shard.
        assert_eq!(BUILD_VERSION, env!("CARGO_PKG_VERSION"));
    }

    fn entry(key: u64, len: u64) -> IndexEntry {
        IndexEntry {
            key,
            verify: key,
            source: String::new(),
            off: 0,
            len,
        }
    }

    fn kept_keys(old: &Index, new_key: u64, budget: u64) -> Vec<u64> {
        retained(old, new_key, budget)
            .iter()
            .map(|e| e.key)
            .collect()
    }

    /// A re-store replaces its own entry instead of keeping both copies.
    #[test]
    fn a_store_drops_the_entry_it_replaces() {
        let old = Index {
            entries: vec![entry(1, 10), entry(2, 10), entry(3, 10)],
        };
        assert_eq!(kept_keys(&old, 2, u64::MAX), [1, 3]);
    }

    /// Over budget, the oldest entries go first and the survivors keep their
    /// shard order. The entry that crosses the budget is dropped with everything
    /// older, even when an older one would still fit. Without the budget every
    /// rebuild's entries were carried forward forever, and the shard grew past
    /// a gigabyte that each cache miss rewrote.
    #[test]
    fn a_store_over_budget_keeps_the_newest_entries_in_order() {
        let old = Index {
            entries: vec![entry(1, 1), entry(2, 50), entry(3, 30), entry(4, 30)],
        };
        assert_eq!(kept_keys(&old, 0, 60), [3, 4]);
        assert_eq!(kept_keys(&old, 0, 111), [1, 2, 3, 4]);
        assert!(kept_keys(&old, 0, 0).is_empty());
    }

    /// The framing must reject every malformed shard rather than panic on one.
    ///
    /// A v49 shard is the case that actually occurs: its first eight bytes are
    /// archive data, so they read as an enormous index length. Slicing with
    /// that would panic inside the interpreter's startup, on a file the user
    /// never asked about — so the length is range-checked against what follows
    /// it and an unusable shard degrades to a recompile.
    #[test]
    fn a_malformed_shard_is_rejected_not_panicked_on() {
        assert!(split_shard(&[]).is_none(), "empty file");
        assert!(split_shard(&[0; 7]).is_none(), "shorter than the length");
        let mut overrun = u64::MAX.to_le_bytes().to_vec();
        overrun.extend_from_slice(b"legacy archive bytes");
        assert!(split_shard(&overrun).is_none(), "length overruns the file");
        let mut short = 32u64.to_le_bytes().to_vec();
        short.extend_from_slice(&[0; 31]);
        assert!(split_shard(&short).is_none(), "index runs past the end");
    }

    /// The framing splits exactly where it was written, with no blob region
    /// when there are no entries.
    #[test]
    fn the_framing_round_trips() {
        let mut bytes = 3u64.to_le_bytes().to_vec();
        bytes.extend_from_slice(b"idxBLOBS");
        let (index, blobs) = split_shard(&bytes).expect("well-formed framing");
        assert_eq!(index, b"idx");
        assert_eq!(blobs, b"BLOBS");

        let empty = 0u64.to_le_bytes();
        let (index, blobs) = split_shard(&empty).expect("a zero-length index");
        assert!(index.is_empty() && blobs.is_empty());
    }

    /// A cached chunk's caret table is keyed by the `op_hash` the compiler
    /// registered, which `ChunkBuilder::build` computes; deserializing must
    /// reproduce it for every chunk the compiler emits, flagged or not, or every
    /// traceback after a cache hit loses its carets. fusevm recomputes it on the
    /// way in, so a cache read has nothing to restore.
    #[test]
    fn a_cached_chunk_keeps_its_built_op_hash() {
        for nan_hook in [false, true] {
            let mut b = fusevm::ChunkBuilder::new();
            b.set_nan_result_hook(nan_hook);
            b.emit(fusevm::Op::LoadInt(7), 1);
            b.emit(fusevm::Op::Return, 1);
            let built = b.build();
            let cached: Chunk = bincode::deserialize(&bincode::serialize(&built).unwrap()).unwrap();
            assert_eq!(
                cached.op_hash, built.op_hash,
                "nan_result_hook = {nan_hook}"
            );
        }
    }
}