Skip to main content

moonseed/
snapshot.rs

1//! Versioned checkpoint codec.
2//!
3//! Object references are [`ObjectId`](crate::id::ObjectId)s. Arena indexes and
4//! generations are not written. The CRC detects accidental corruption; it does
5//! not authenticate the sender.
6
7use std::collections::HashSet;
8
9use crate::check;
10use crate::heap::{
11    AssignTarget, ClosureObj, Frame, Heap, NativeClosureObj, Pending, Proto, Status, StringObj,
12    TableObj, ThreadObj, UpvalueObj, UpvalueState,
13};
14use crate::host::HostRegistry;
15use crate::id::{Handle, Kind, ObjectId, SnapshotError, TerminationReason};
16use crate::opcode::{self, Op};
17use crate::runtime::Limits;
18use crate::runtime::Runtime;
19use crate::table::{Slot, Table, TableKey};
20use crate::value::Value;
21
22/// Default bound on a snapshot, written or read (`Config::max_snapshot_bytes`,
23/// `Limits::max_snapshot_bytes`): twice the default logical-heap quota. A
24/// snapshot measured 0.33 to 0.92 bytes per logical byte (threads to
25/// userdata) at every heap size up to the quota (ADR 0052).
26pub(crate) const MAX_SNAPSHOT_BYTES: u64 = 128 << 20;
27
28/// What a snapshot bound is clamped to: lengths and offsets stay `u32`
29/// on every target, and a 32-bit host can hold the bytes.
30pub(crate) const SNAPSHOT_BYTES_RANGE: std::ops::RangeInclusive<u64> = 4_096..=1 << 31;
31
32/// Byte offset of the string-object count when no VM wait has completed.
33/// Kept in lockstep with [`write_image`].
34#[cfg(test)]
35pub(crate) const STRING_COUNT_OFFSET: usize = 276;
36/// Structural ceilings: what any runtime could hold. A snapshot is also
37/// held to the limits it is restored into ([`Limits`]), and every count to
38/// what is left of its bytes and to the decode budget.
39const MAX_OBJECTS: u32 = crate::heap::OBJECTS_CEILING;
40const MAX_STRING_BYTES: u32 = crate::heap::STRING_CEILING as u32;
41/// Slots of one table: each is an entry of the logical heap.
42const MAX_TABLE_ENTRIES: u32 = 1 << 28;
43/// Values, and numbers, a native closure keeps (ADR 0035).
44const MAX_CLOSURE_VALUES: u32 = 16;
45const MAX_USER_VALUES: u32 = crate::userdata::MAX_USER_VALUES as u32;
46const MAX_USERDATA_BYTES: u32 = crate::userdata::MAX_USERDATA_BYTES as u32;
47const MAX_FRAMES: u32 = crate::runtime::MAX_FRAMES as u32;
48/// The largest stack a thread may have: the top of the range
49/// `Config::max_stack_slots` is clamped to (ADR 0028).
50const MAX_STACK_SLOTS: u32 = *crate::runtime::STACK_SLOTS_RANGE.end();
51const MAX_INSTRUCTIONS: u32 = crate::limits::MAX_INSTRUCTIONS as u32;
52const MAX_CONSTS: u32 = crate::limits::MAX_CONSTS as u32;
53const MAX_PROTOS: u32 = crate::limits::MAX_PROTOS as u32;
54const MAX_UPVALUES: u32 = crate::limits::MAX_UPVALUES as u32;
55/// The most source a `load` frame holds while it reads (ADR 0031): what
56/// `load` accepts.
57const MAX_SOURCE_BYTES: u32 = crate::limits::DEFAULT_SOURCE_BYTES as u32;
58
59const MAGIC: &[u8; 4] = b"MNSD";
60/// Container schema: the wire layout of the object graph. Schema 3: table
61/// slots are live entries or dead traversal anchors. `next_live` links are
62/// rebuilt from slot order and are not written. Schema 4: a native-function
63/// symbol section, native values and keys (by index into it), and the
64/// native pending-call states. Schema 5: a table's metatable, and a
65/// frame's in-progress metamethod call. Schema 6: a prototype's constants
66/// are references to its string objects; the GC policy revision and the
67/// automatic-collection state. Schema 7: a metamethod call's event names how
68/// it finishes: store (1), drop (2), drop and step the assignment (3), truth
69/// (4), negated truth (5). Schema 8: the logical-heap quota, the reserved
70/// error strings, boundary frames, a thread's unwind state, and a failed
71/// thread's error (ADR 0024, ADR 0025). Schema 9: a thread's to-be-closed
72/// list and coroutine and closing flags, a frame's `Close` event and idle
73/// phase, and an unwind whose error may be absent (ADR 0026). Older
74/// schemas are not restored. Adding an instruction does not change this
75/// number. Schema 10: a vararg frame's extra arguments sit below its
76/// registers, so a frame records only their count; the thread stack bound
77/// (ADR 0028). Schema 11: the reserved strings also hold the type names
78/// and the booleans' text, after five new error classes; a boundary frame
79/// may be a base function waiting on a call it made, with its task
80/// (ADR 0031). Schema 12: the standard libraries' state (the random
81/// generator and the entropy stream), a library function's task in a
82/// base-function frame, a call deferred to the next step, and the reserved
83/// names `integer` and `float` after four new error classes (ADR 0032,
84/// ADR 0033). Schema 13: each basic type's shared metatable, native
85/// closures, string functions' tasks, and new error classes (ADR 0034,
86/// ADR 0035). Schema 14: the Lua registry, package tasks, prototypes'
87/// debug information and chunk names, the tail-call mark of a frame, and
88/// new error classes (ADR 0039, ADR 0040). Schema 15: full userdata with
89/// their metatables, user values, and byte or host payloads, light
90/// userdata values and keys, and no shared metatable for full userdata
91/// (ADR 0042 to ADR 0045). Schema 16: the finalization lists and flags,
92/// finalizer frames, and `collectgarbage`'s frame waiting for them
93/// (ADR 0047, ADR 0048). Schema 17: the incremental collector's state:
94/// its parameters and schedule, its phase, every object's mark but the
95/// current white, its gray, scanned, weak, ephemeron and waiting lists, and
96/// the sweep's count; dead objects waiting for the sweep are not written
97/// (ADR 0050). Schema 18: generational collection: the mode and its
98/// multipliers, the last major collection's base, falling back, every
99/// object's age, the young lists, the objects remembered for the next
100/// young collection, and a young collection's progress; a `collectgarbage`
101/// frame's result is a tag (ADR 0051). Schema 19: what each thread is
102/// charged beyond its object, the bytes a sweep has freed, and where the
103/// registered objects are known old; the logical heap is counted again,
104/// never read (ADR 0051). Schema 20: the string limit, after the stack
105/// bound; no bound on all strings' bytes together, and wider structural
106/// ceilings (ADR 0052). Schema 21: native continuation frames, host wait
107/// payloads, completed VM wait keys, main-thread host calls, and halted
108/// callback misuse; rebindable host userdata as payload tag 3, a type
109/// symbol and an external key of at most 4 KiB (ADR 0053). Schema 22:
110/// native continuation frames retain the original external effect sequence.
111// Schema 25: pending exit status, close policy and shutdown phase; typed
112// capability pending/completed work (pending tag 8).
113// 0.1.1: boundary tag 8 is a non-yielding native frame; tag 5 is unchanged.
114const VERSION: u16 = 25;
115/// Instruction-set revision of the prototypes inside the snapshot. It changes
116/// when an opcode is added or an existing opcode's encoding or meaning
117/// changes. A decoder accepts exactly its own revision, so an older runtime
118/// rejects newer code at the header, before any prototype is decoded.
119/// Revision 1: tags 1-30. Revision 2: `LoadBool` (31), `CloseUpvalues` (32),
120/// `JumpIfFalse` (33). Revision 3: `Compare` (34). Revision 4: `Neg` (35),
121/// `ForPrep` (36), `ForLoop` (37). Revision 5: `Index` (38), `SetIndex` (39),
122/// `GetField` (40), `SetField` (41), `SetList` (42); `AssignField` stores
123/// with language-level assignment; a chunk's one capture is its `_ENV`.
124/// Revision 6: `Index`, `SetIndex`, `GetField`, `SetField`, and assignment
125/// stores follow `__index` / `__newindex`; `Len` (43).
126/// Revision 7: `Len` passes `__len` its operand twice, as Lua 5.4 does, and
127/// calls any `__len` value; `Call` follows `__call`; `Add`, `Neg`, and
128/// `Compare` take numeric strings and metamethods; `Arith` (44), `BNot`
129/// (45), `Concat` (46).
130/// Revision 8: `MarkClose` (47), `CloseScope` (48), `CloseThread` (49);
131/// `Return` closes the frame's to-be-closed values before it returns.
132/// Revision 9: `GenericForLoop` (50).
133/// Revision 10: `Vararg` reads a frame's extras below its registers
134/// (ADR 0028); `Vararg` and `VarargLen` appear only in vararg prototypes.
135/// Revision 11: `TailCall` (51), always followed by the `Return` of its
136/// open window (ADR 0029). Revision 12: jump offsets are signed 32-bit;
137/// constant, field-name, and child indexes are unsigned 32-bit. Registers
138/// and host symbols keep their widths. Revision 13: `ArithK` (52), with
139/// an exact integer immediate and the original operand order. Revision 14:
140/// `CompareBranch` (53); Truth's reserved destination 255 finishes its branch.
141pub(crate) const BYTECODE_REVISION: u16 = 14;
142/// Table semantics revision: insertion-order `next`, dead anchors, and the
143/// smallest-border raw length (ADR 0010). Revision 2: the float 2^63 is a
144/// float key, not `math.maxinteger`; a float key stored as an integer is
145/// returned by `next` as that integer; an update keeps the entry's key object.
146/// Revision 3: tables have metatables (ADR 0018). Revision 4: an insert
147/// keeps the dead anchors until they outnumber half the live entries, so a
148/// key may have anchors before its live slot (Phase 3.30).
149const TABLES_REVISION: u16 = 4;
150/// Fuel revision: one logical unit per executed instruction. Revision 2:
151/// and one per step of a base function that called Lua, when it goes on
152/// from the call's result (ADR 0031). Revision 3: a math or table
153/// function's step runs up to 32 semantic operations, and each step after
154/// the first costs one unit; a function the VM implements, called by
155/// another's frame, is called in its own step, which costs one unit
156/// (ADR 0033). Revision 4: a string function's step does a bounded amount of
157/// work (bytes built, pattern, format, or pack steps), and a string that
158/// takes part in arithmetic does so through the string metatable's
159/// metamethods, called as functions (ADR 0034). Revision 5: starting a
160/// finalizer costs one unit, as a call does (ADR 0048). Revision 6: the
161/// collector's work costs one unit per `gc::WORK_PER_FUEL` units of it,
162/// what a unit paid for and was not used carrying over (ADR 0050).
163const FUEL_REVISION: u16 = 7;
164/// GC policy revision: the logical costs and the threshold rule that decide
165/// where automatic collections run (ADR 0021). A decoder accepts exactly its
166/// own, so a restored run collects where the original would have.
167/// Revision 2: the threshold is also capped at half the room under the
168/// heap quota; a table store the quota refuses collects and tries again;
169/// a protected call that caught a memory error collects before it returns
170/// (ADR 0025). Revision 3: the source a `load` reader has given so far is
171/// charged to the logical heap and counted by every collection (ADR 0031).
172/// Revision 4: so is the text `table.concat` has built (ADR 0033).
173/// Revision 5: so are the bytes a string function has built, and native
174/// closures have a logical size (ADR 0034, ADR 0035).
175/// Revision 6: a prototype's debug information is charged to the logical
176/// heap, and a `require` task's searcher messages (ADR 0039, ADR 0040).
177/// Revision 7: so is every slot of a thread's stack, now that source can
178/// make threads (ADR 0041). Revision 8: full userdata count their user
179/// values and their payload's bytes, or what their host type declares
180/// (ADR 0042, ADR 0044). Revision 9: tables with `__mode` are weak,
181/// weak-key tables are ephemerons, and registered objects found dead are
182/// queued for their finalizers and kept until they have run (ADR 0046,
183/// ADR 0047); no collection starts while a finalizer runs. Revision 10:
184/// the collector is incremental: cycles start after `pause` percent of
185/// what the last kept, steps every 2^`stepsize` bytes do `stepmul` units of
186/// work per KiB, and the work units are counted exactly (ADR 0050).
187/// Revision 11: generational mode, the default: young collections every
188/// `minormul` percent of what the last kept (at least the minimum debt),
189/// a major collection once memory grows `majormul` percent past the last
190/// one's, and whole cycles after a bad major (ADR 0051). Revision 12: the
191/// quota is on the exact logical heap; a thread is charged for the stack
192/// slots and builtin bytes it has held since a collection last traced it;
193/// a young collection looks only at the objects registered since the one
194/// before it (ADR 0051).
195const GC_REVISION: u16 = 12;
196
197/// Positions of an image's strings and threads, by id (see [`Image::index`]).
198#[derive(Clone, Debug, Default)]
199pub(crate) struct ImageIndex {
200    strings: std::cell::OnceCell<std::collections::HashMap<u64, usize>>,
201    threads: std::cell::OnceCell<std::collections::HashMap<u64, usize>>,
202}
203
204impl Image {
205    /// The bytes of the string `id`.
206    pub(crate) fn string(&self, id: u64) -> Option<&[u8]> {
207        let at = self.index.strings.get_or_init(|| {
208            self.strings
209                .iter()
210                .enumerate()
211                .map(|(at, (id, _))| (*id, at))
212                .collect()
213        });
214        at.get(&id).map(|at| self.strings[*at].1.as_slice())
215    }
216
217    /// The thread `id`.
218    pub(crate) fn thread(&self, id: u64) -> Option<&ThreadImage> {
219        let at = self.index.threads.get_or_init(|| {
220            self.threads
221                .iter()
222                .enumerate()
223                .map(|(at, thread)| (thread.id, at))
224                .collect()
225        });
226        at.get(&id).map(|at| &self.threads[*at])
227    }
228}
229
230#[derive(Clone, Debug)]
231pub(crate) struct Image {
232    pub(crate) iteration_profile: crate::IterationProfile,
233    pub(crate) effect_domain: u64,
234    pub(crate) next_object_id: u64,
235    pub(crate) next_sequence: u64,
236    pub(crate) fuel_consumed: u64,
237    pub(crate) fuel_limit: Option<u64>,
238    pub(crate) last_completed_wait: Option<u64>,
239    pub(crate) completed_waits: Vec<u64>,
240    pub(crate) host_call: bool,
241    pub(crate) callback_failed: bool,
242    pub(crate) trap: u8,
243    pub(crate) max_objects: u32,
244    /// `Config::max_stack_slots`: every thread's stack and slot index
245    /// stays within it.
246    pub(crate) max_stack_slots: u32,
247    /// `Config::max_string_bytes` (ADR 0052).
248    pub(crate) max_string: u32,
249    pub(crate) gc: crate::heap::GcState,
250    /// The standard libraries' state (ADR 0032).
251    pub(crate) library: crate::library::LibraryState,
252    /// Each basic type's shared metatable, by `heap::basic_type`, or 0
253    /// (ADR 0034).
254    pub(crate) type_metatables: [u64; crate::heap::BASIC_TYPES],
255    pub(crate) globals: u64,
256    /// Lua's registry, or 0 (ADR 0039).
257    pub(crate) registry: u64,
258    pub(crate) active: u64,
259    pub(crate) entry: u64,
260    pub(crate) strings: Vec<(u64, Vec<u8>)>,
261    /// Native-function symbols; `EncValue::Native(i)` is `natives[i]`.
262    pub(crate) natives: Vec<String>,
263    /// Ids of the reserved strings, in `heap::reserved_texts` order.
264    pub(crate) reserved: Vec<u64>,
265    pub(crate) protos: Vec<ProtoImage>,
266    pub(crate) tables: Vec<TableImage>,
267    pub(crate) upvalues: Vec<UpImage>,
268    pub(crate) closures: Vec<ClosureImage>,
269    pub(crate) native_closures: Vec<NativeClosureImage>,
270    pub(crate) threads: Vec<ThreadImage>,
271    pub(crate) userdata: Vec<UserdataImage>,
272    pub(crate) finalizers: FinalizersImage,
273    pub(crate) collector: CollectorImage,
274    /// Where each string and each thread is, by id: made once, on first
275    /// use, so validation looks objects up in constant time.
276    pub(crate) index: ImageIndex,
277}
278
279/// The incremental collector's state (ADR 0050), objects by id.
280#[derive(Clone, Debug, Default)]
281pub(crate) struct CollectorImage {
282    pub(crate) phase: u8,
283    pub(crate) atomic: u8,
284    pub(crate) white: u8,
285    pub(crate) gray: Vec<u64>,
286    /// The object being scanned, its position, and how (0 a thread or a
287    /// prototype, 1 table entries, 2 an ephemeron table) with the mode.
288    pub(crate) scan: Option<(u64, u32, u8, bool, bool)>,
289    pub(crate) weak: Vec<(u64, bool, bool)>,
290    pub(crate) late: u32,
291    pub(crate) ephemerons: Vec<u64>,
292    /// By key id, ascending.
293    pub(crate) waiting: Vec<(u64, Vec<EncValue>)>,
294    pub(crate) cursor: u32,
295    pub(crate) inner: u32,
296    pub(crate) marked_bytes: u64,
297    pub(crate) debt_base: u64,
298    pub(crate) marking_debt: u64,
299    pub(crate) work_base: u64,
300    pub(crate) sweep_left: u64,
301    pub(crate) reset: bool,
302    /// Every object whose mark is not the default, with its age: the
303    /// default is black and old off the young lists in generational form,
304    /// the current white otherwise.
305    pub(crate) marks: Vec<(u64, u8, u8)>,
306    /// The arenas' lists of objects gray again, in kind order.
307    pub(crate) again: Vec<u64>,
308    /// Generational form, a young collection running, a sweep making
309    /// survivors old, what the cycle decides (ADR 0051).
310    pub(crate) generational: bool,
311    pub(crate) minor: bool,
312    pub(crate) to_old: bool,
313    pub(crate) decide: u8,
314    /// What the sweep running has freed and has still to free, logical
315    /// bytes: left in the logical heap until it ends.
316    pub(crate) unreleased: u64,
317    pub(crate) promoted: u64,
318    /// White objects whose mark or age is not the default, with the age.
319    pub(crate) ages: Vec<(u64, u8)>,
320    /// The arenas' young lists, in kind order, but entries freed or
321    /// promoted.
322    pub(crate) young: Vec<u64>,
323    pub(crate) revisit: Vec<u64>,
324    pub(crate) touched: Vec<u64>,
325}
326
327/// Finalization state (ADR 0047): object ids, in order.
328#[derive(Clone, Debug, Default)]
329pub(crate) struct FinalizersImage {
330    /// Registered, oldest first.
331    pub(crate) registered: Vec<u64>,
332    /// Where the registered objects are known old, and where those
333    /// registered since the last young collection begin (ADR 0051).
334    pub(crate) old_until: u32,
335    pub(crate) new_from: u32,
336    /// Waiting for their finalizers, in the order they run.
337    pub(crate) pending: Vec<u64>,
338    pub(crate) running: bool,
339    pub(crate) closing: bool,
340    /// The entry thread's status before closing began, while it closes
341    /// with no frames of its own, or 0.
342    pub(crate) closed: u8,
343    /// The closure of the finalizer frames while closing, or 0.
344    pub(crate) close_closure: u64,
345    pub(crate) exit: Option<crate::heap::ExitState>,
346}
347
348/// A full userdata (ADR 0042, ADR 0045).
349#[derive(Clone, Debug)]
350pub(crate) struct UserdataImage {
351    pub(crate) id: u64,
352    /// The metatable's id, or 0.
353    pub(crate) metatable: u64,
354    pub(crate) user_values: Vec<EncValue>,
355    pub(crate) payload: PayloadImage,
356    /// The logical bytes the payload counts.
357    pub(crate) charge: u64,
358}
359
360#[derive(Clone, Debug)]
361pub(crate) enum PayloadImage {
362    Bytes(Vec<u8>),
363    File(crate::iolib::FileState),
364    /// A portable host value: its type's symbol and its codec's bytes.
365    Host {
366        symbol: String,
367        bytes: Vec<u8>,
368    },
369    /// A host resource identified by a bounded external key.
370    Rebind {
371        symbol: String,
372        key: Vec<u8>,
373    },
374}
375
376#[derive(Clone, Debug)]
377pub(crate) struct ProtoImage {
378    pub(crate) id: u64,
379    pub(crate) max_reg: u8,
380    pub(crate) params: u8,
381    pub(crate) vararg: bool,
382    pub(crate) ops: Vec<Op>,
383    /// Ids of the prototype's constant strings; this is what is written.
384    pub(crate) const_ids: Vec<u64>,
385    /// Their bytes, filled from the string section when decoding.
386    pub(crate) byte_consts: Vec<Vec<u8>>,
387    pub(crate) captures: Vec<crate::opcode::Capture>,
388    pub(crate) children: Vec<u64>,
389    /// The chunk name's string id, or 0 (ADR 0040).
390    pub(crate) source: u64,
391    pub(crate) debug: Option<Box<crate::debuginfo::DebugInfo>>,
392}
393
394#[derive(Clone, Debug)]
395pub(crate) struct TableImage {
396    pub(crate) id: u64,
397    /// The metatable's id, or 0.
398    pub(crate) metatable: u64,
399    pub(crate) slots: Vec<SlotImage>,
400}
401
402#[derive(Clone, Debug)]
403pub(crate) struct SlotImage {
404    pub(crate) ordinal: u32,
405    pub(crate) body: SlotBody,
406}
407
408#[derive(Clone, Debug)]
409pub(crate) enum SlotBody {
410    Live { key: EncValue, value: EncValue },
411    Dead(DeadKey),
412}
413
414/// Identity of a deleted key. Not a GC edge. Object ids may name an object
415/// that was collected before the snapshot.
416#[derive(Clone, Debug)]
417pub(crate) enum DeadKey {
418    Bool(bool),
419    Integer(i64),
420    Float(u64),
421    Bytes(Vec<u8>),
422    Object(u64),
423    Native(u32),
424    Light(crate::value::LightDomain, u64),
425}
426
427#[derive(Clone, Debug)]
428pub(crate) struct UpImage {
429    pub(crate) id: u64,
430    pub(crate) state: UpImageState,
431}
432
433#[derive(Clone, Debug)]
434pub(crate) enum UpImageState {
435    Closed(EncValue),
436    Open { thread: u64, slot: u32 },
437}
438
439/// A native closure (ADR 0035): its builtin by native index, its values,
440/// and its numbers.
441#[derive(Clone, Debug)]
442pub(crate) struct NativeClosureImage {
443    pub(crate) id: u64,
444    pub(crate) native: u32,
445    pub(crate) values: Vec<EncValue>,
446    pub(crate) state: Vec<i64>,
447}
448
449#[derive(Clone, Debug)]
450pub(crate) struct ClosureImage {
451    pub(crate) id: u64,
452    pub(crate) proto: u64,
453    pub(crate) upvalues: Vec<u64>,
454}
455
456#[derive(Clone, Debug)]
457pub(crate) struct UnwindImage {
458    /// Class tag and object; `None` only while a thread that had not
459    /// failed is being closed.
460    pub(crate) error: Option<(u8, EncValue)>,
461    pub(crate) phase: crate::heap::UnwindPhase,
462}
463
464/// A frame's metamethod call (ADR 0019), or its closes (ADR 0026).
465#[derive(Clone, Debug)]
466pub(crate) struct MetaImage {
467    pub(crate) event: EventImage,
468    pub(crate) slot: u32,
469    pub(crate) nargs: u8,
470    pub(crate) phase: crate::heap::MetaPhase,
471}
472
473#[derive(Clone, Debug)]
474pub(crate) enum EventImage {
475    /// Every event but `Close`: plain numbers.
476    Plain(crate::heap::MetaEvent),
477    Close {
478        from: u32,
479        next: NextImage,
480    },
481}
482
483#[derive(Clone, Debug)]
484pub(crate) enum NextImage {
485    Advance,
486    Return { src: u32, produced: u32 },
487    Unwind(UnwindImage),
488}
489
490#[derive(Clone, Debug)]
491pub(crate) enum BoundaryImage {
492    Protect {
493        func: u32,
494        advance_caller: bool,
495        handler: Option<EncValue>,
496    },
497    Handler {
498        slot: u32,
499        protect: u32,
500        target: u32,
501        depth: u8,
502        fault: u8,
503    },
504    /// A base function waiting on the call it made (ADR 0031). Its task
505    /// holds no values.
506    Builtin {
507        func: u32,
508        passed: u32,
509        advance_caller: bool,
510        task: crate::heap::Task,
511    },
512    Native {
513        func: u32,
514        passed: u32,
515        advance_caller: bool,
516        symbol: u32,
517        tag: u32,
518        kept: u32,
519        sequence: Option<u64>,
520        error: Option<(u8, EncValue)>,
521        resuming: bool,
522        no_yield: bool,
523    },
524    Hook {
525        func: u32,
526        saved_top: u32,
527        target: u32,
528        instruction: Option<(usize, u32, u8)>,
529        after: crate::runtime::hooks::AfterHook,
530    },
531    HookNative {
532        func: u32,
533        passed: u32,
534        callee: EncValue,
535        advance_caller: bool,
536        phase: u8,
537        produced: u32,
538        result: u32,
539    },
540    /// A finalizer's call (ADR 0048).
541    Finalizer { func: u32, saved_top: u32 },
542}
543
544impl BoundaryImage {
545    /// The slot of the call the frame stands for.
546    fn call_slot(&self) -> u32 {
547        match self {
548            Self::Protect { func, .. } => func.saturating_add(1),
549            Self::Handler { slot, .. } => *slot,
550            Self::Builtin {
551                func, passed, task, ..
552            } => func
553                .saturating_add(1)
554                .saturating_add(*passed)
555                .saturating_add(task.scratch()),
556            Self::Native {
557                func, passed, kept, ..
558            } => func
559                .saturating_add(1)
560                .saturating_add(*passed)
561                .saturating_add(*kept),
562            Self::Finalizer { func, .. }
563            | Self::Hook { func, .. }
564            | Self::HookNative { func, .. } => *func,
565        }
566    }
567
568    /// The results that call wants.
569    fn call_wants(&self) -> u8 {
570        match self {
571            Self::Protect { .. } | Self::Native { .. } => crate::opcode::COUNT_OPEN,
572            Self::Handler { .. } => 1,
573            Self::Builtin { task, .. } => task.wants(),
574            Self::Finalizer { .. } | Self::Hook { .. } => 0,
575            Self::HookNative { .. } => crate::opcode::COUNT_OPEN,
576        }
577    }
578
579    /// Whether an error raised above stops here: a protected call, or
580    /// `load` reading.
581    fn catches(&self) -> bool {
582        match self {
583            Self::Protect { .. } | Self::Native { .. } => true,
584            Self::Handler { .. } => false,
585            Self::Builtin { task, .. } => task.catches(),
586            Self::Finalizer { .. } => true,
587            Self::Hook { .. } | Self::HookNative { .. } => false,
588        }
589    }
590
591    /// The slot of its caller's `Call` that the frame's end moves past.
592    fn advances(&self) -> Option<u32> {
593        match self {
594            Self::Protect {
595                func,
596                advance_caller: true,
597                ..
598            }
599            | Self::Builtin {
600                func,
601                advance_caller: true,
602                ..
603            }
604            | Self::Native {
605                func,
606                advance_caller: true,
607                ..
608            } => Some(*func),
609            _ => None,
610        }
611    }
612}
613
614/// Whether an unwind with no target may pass a frame: it holds no
615/// boundary that catches or handles errors.
616fn passes(frame: &FrameImage) -> bool {
617    match &frame.boundary {
618        None => true,
619        Some(BoundaryImage::Handler { .. }) => false,
620        Some(boundary) => !boundary.catches(),
621    }
622}
623
624#[derive(Clone, Debug)]
625pub(crate) struct ThreadImage {
626    pub(crate) id: u64,
627    pub(crate) status: u8,
628    pub(crate) resumed_by: u64,
629    pub(crate) top: u32,
630    pub(crate) stack: Vec<EncValue>,
631    pub(crate) results: Vec<EncValue>,
632    pub(crate) frames: Vec<FrameImage>,
633    /// A failed thread's error: class tag and object.
634    pub(crate) error: Option<(u8, EncValue)>,
635    pub(crate) unwind: Option<UnwindImage>,
636    pub(crate) coroutine: bool,
637    pub(crate) closing: bool,
638    /// Active to-be-closed slots, strictly increasing.
639    pub(crate) tbc: Vec<u32>,
640    /// What the thread is charged beyond its object: stack slots, and
641    /// bytes its builtins hold (ADR 0051).
642    pub(crate) charged_slots: u32,
643    pub(crate) charged_held: u64,
644    pub(crate) hook: Option<HookImage>,
645}
646
647#[derive(Clone, Debug)]
648pub(crate) enum HookTargetImage {
649    None,
650    Lua(EncValue),
651    Host(String),
652    InheritedLua,
653}
654#[derive(Clone, Debug)]
655pub(crate) struct HookImage {
656    pub(crate) target: HookTargetImage,
657    pub(crate) mask: u8,
658    pub(crate) base_count: i32,
659    pub(crate) remaining_count: i32,
660    pub(crate) allow_hook: bool,
661    pub(crate) old_pc: Option<(usize, u32, Option<u32>)>,
662    pub(crate) pending: Option<crate::runtime::hooks::PendingEvent>,
663    pub(crate) hook_yield: bool,
664    pub(crate) names: Vec<EncValue>,
665    pub(crate) instruction: Option<(usize, u32, u8)>,
666    pub(crate) after: crate::runtime::hooks::AfterHook,
667    pub(crate) transfer: Option<(u32, u32, u32)>,
668    pub(crate) restore_cursor: Option<(usize, u32, Option<u32>)>,
669}
670
671#[derive(Clone, Debug)]
672pub(crate) struct FrameImage {
673    pub(crate) closure: u64,
674    pub(crate) pc: u32,
675    pub(crate) base: u32,
676    pub(crate) limit: u32,
677    pub(crate) nresults: u8,
678    pub(crate) vararg_len: u32,
679    pub(crate) tail: bool,
680    pub(crate) return_hook: bool,
681    pub(crate) pending: PendingImage,
682    pub(crate) wait_request: Option<(String, Vec<EncValue>)>,
683    pub(crate) targets: Vec<TargetImage>,
684    pub(crate) meta: Option<MetaImage>,
685    pub(crate) boundary: Option<BoundaryImage>,
686}
687
688#[derive(Clone, Debug)]
689pub(crate) enum TargetImage {
690    Register(u32),
691    Field { table: EncValue, key: EncValue },
692}
693
694#[derive(Clone, Debug)]
695pub(crate) enum PendingImage {
696    None,
697    Prepared {
698        sequence: u64,
699        symbol: String,
700        arg: i64,
701        dest: u8,
702    },
703    Waiting {
704        sequence: u64,
705        symbol: String,
706        arg: i64,
707        dest: u8,
708        wait_key: u64,
709    },
710    Resuming {
711        child: u64,
712        dest: u8,
713        nresults: u8,
714    },
715    Assigning {
716        src: u32,
717        nvalues: u16,
718        next: u16,
719    },
720    NativePrepared {
721        sequence: u64,
722    },
723    NativeWaiting {
724        sequence: Option<u64>,
725        wait_key: u64,
726    },
727    Capability {
728        sequence: u64,
729        wait_key: u64,
730        completed: bool,
731    },
732    /// A builtin's call left for the next step (ADR 0033).
733    Deferred,
734}
735
736#[derive(Clone, Debug)]
737pub(crate) enum EncValue {
738    Nil,
739    Bool(bool),
740    Integer(i64),
741    Float(u64),
742    String(u64),
743    Table(u64),
744    Closure(u64),
745    Thread(u64),
746    Native(u32),
747    NativeClosure(u64),
748    Userdata(u64),
749    Light(crate::value::LightDomain, u64),
750}
751
752impl Runtime {
753    /// The checkpoint of this runtime, refused with
754    /// `SnapshotError::LimitExceeded` past `Config::max_snapshot_bytes`.
755    /// Host userdata growth stays charged past the quota (ADR 0044);
756    /// Userdata charges or collection accounting past it refuse the
757    /// snapshot (ADR 0052).
758    ///
759    /// # Errors
760    ///
761    /// Returns `SnapshotError` for callback/poisoned or invalid VM state,
762    /// nonportable userdata/resources, mismatched userdata registrations, or exceeded
763    /// snapshot, stack, object or logical heap limits.
764    ///
765    /// # Panics
766    ///
767    /// Propagates panics from host userdata encoders and resource backends.
768    pub fn snapshot(&self) -> Result<Vec<u8>, SnapshotError> {
769        if self.in_callback() {
770            return Err(SnapshotError::InvalidStructure);
771        }
772        let image = self.to_image()?;
773        check_pending_resources(&image, None)?;
774        if !slots_fit(&image, image.max_stack_slots) {
775            return Err(SnapshotError::LimitExceeded);
776        }
777        let userdata_bytes = image.userdata.iter().fold(0u64, |total, object| {
778            total.saturating_add(crate::heap::userdata_cost(
779                object.user_values.len(),
780                object.charge,
781            ))
782        });
783        if userdata_bytes > image.gc.quota
784            || image.gc.major_base > image.gc.quota
785            || image.collector.unreleased > image.gc.quota
786        {
787            return Err(SnapshotError::LimitExceeded);
788        }
789        encode_within(&image, self.max_snapshot())
790    }
791
792    /// Restore a checkpoint into the default [`Limits`]: see
793    /// [`Runtime::from_snapshot_with_limits`].
794    ///
795    /// # Errors
796    ///
797    /// Returns the decode, policy and resource errors described by
798    /// [`Self::from_snapshot_with_limits`].
799    ///
800    /// # Panics
801    ///
802    /// Propagates host codec/rebind panics as described by [`Self::restore`].
803    pub fn from_snapshot(
804        bytes: &[u8],
805        registry: &HostRegistry,
806        expected_domain: u64,
807    ) -> Result<Self, SnapshotError> {
808        Self::from_snapshot_with_limits(bytes, registry, expected_domain, Limits::default())
809    }
810
811    /// Restore a checkpoint into the host's `limits` (ADR 0052). The
812    /// restored runtime runs under, for each limit, the smaller of the
813    /// snapshot's and the host's: equal or larger host limits restore the
814    /// runtime exactly as it was, and a host limit is never raised. A
815    /// smaller host limit the state does not fit (more live objects, a
816    /// longer stack or string, a larger logical heap) refuses the
817    /// snapshot with `SnapshotError::LimitExceeded` before any runtime
818    /// exists. A snapshot longer than `limits.max_snapshot_bytes` is
819    /// refused unread, and decoding allocates at most about four times
820    /// the logical heap it may restore, plus the snapshot's length.
821    ///
822    /// # Errors
823    ///
824    /// Returns `SnapshotError` for malformed state, incompatible revisions,
825    /// a wrong effect domain, missing/denied registrations, failed userdata
826    /// decoding/rebinding, nonportable resources or exceeded host/snapshot limits.
827    ///
828    /// # Panics
829    ///
830    /// Propagates host codec/rebind panics as described by [`Self::restore`].
831    pub fn from_snapshot_with_limits(
832        bytes: &[u8],
833        registry: &HostRegistry,
834        expected_domain: u64,
835        limits: Limits,
836    ) -> Result<Self, SnapshotError> {
837        Self::restore(
838            bytes,
839            &crate::Host::new(registry.clone())
840                .limits(limits)
841                .effect_domain(expected_domain),
842        )
843        .map_err(|error| match error {
844            crate::Error::Vm(crate::VmError::Snapshot(error)) => error,
845            _ => SnapshotError::InvalidStructure,
846        })
847    }
848
849    /// Restore against the host's registrations, policies, resources, and limits.
850    /// Validation, codecs, and rebinds finish before a runtime is constructed.
851    /// Moonseed library symbols allowed by [`crate::Host::libraries`] are supplied
852    /// automatically; the host registry needs only host callbacks, hooks and
853    /// userdata types. A denied library or absent host symbol returns
854    /// [`SnapshotError::UnknownHostSymbol`] wrapped in [`crate::Error::Vm`].
855    /// Execution capabilities are optional: `print` without a sink writes nowhere.
856    /// Old rooted [`crate::Value`] objects belong to the original runtime;
857    /// reacquire them through globals or [`Runtime::object`] after restore.
858    /// The host retains the journal separately and supplies it to `run` again;
859    /// the expected effect domain identifies that journal's run lineage.
860    ///
861    /// # Errors
862    ///
863    /// Returns `Error::Vm(VmError::Snapshot(..))` for malformed data,
864    /// incompatible revisions, a wrong effect domain, missing/denied registrations,
865    /// failed userdata codecs/rebinds, nonportable resources or exceeded limits.
866    ///
867    /// # Panics
868    ///
869    /// Propagates panics from host userdata decoders, rebinds and resource backends.
870    pub fn restore(bytes: &[u8], host: &crate::Host) -> crate::Result<Self> {
871        Self::restore_snapshot(bytes, host)
872            .map_err(|error| crate::Error::Vm(crate::VmError::Snapshot(error)))
873    }
874
875    fn restore_snapshot(bytes: &[u8], host: &crate::Host) -> Result<Self, SnapshotError> {
876        let limits = host.limits.clamped();
877        let image = decode_within(bytes, &limits)?;
878        if image.effect_domain != host.effect_domain {
879            return Err(SnapshotError::EffectDomainMismatch);
880        }
881        if image.iteration_profile != host.iteration_profile {
882            return Err(SnapshotError::IterationProfileMismatch);
883        }
884        let registry = host.restore_registry(&image.natives)?;
885        check_pending_resources(&image, Some(&host.capabilities))?;
886        let mut runtime = realize(&image, &registry, &limits, &host.capabilities)?;
887        runtime.restore_memory_error_policy(host.memory_error_policy);
888        runtime.native_panic_policy = host.native_panic_policy;
889        runtime.iteration_profile = host.iteration_profile;
890        runtime.apply_capabilities(&host.capabilities);
891        runtime.refresh_hook_trap();
892        Ok(runtime)
893    }
894
895    pub(crate) fn to_image(&self) -> Result<Image, SnapshotError> {
896        let heap = self.heap();
897        let mut strings = Vec::new();
898        for (_, _, object) in heap.strings.iter() {
899            strings.push((object.id.raw(), object.bytes.to_vec()));
900        }
901        let mut protos = Vec::new();
902        for (_, _, proto) in heap.protos.iter() {
903            protos.push(proto_image(heap, proto)?);
904        }
905        let mut tables = Vec::new();
906        for (_, _, table) in heap.tables.iter() {
907            tables.push(table_image(heap, table)?);
908        }
909        let mut upvalues = Vec::new();
910        for (_, _, upvalue) in heap.upvalues.iter() {
911            upvalues.push(up_image(heap, upvalue)?);
912        }
913        let mut closures = Vec::new();
914        for (_, _, closure) in heap.closures.iter() {
915            closures.push(closure_image(heap, closure)?);
916        }
917        let mut threads = Vec::new();
918        for (_, _, thread) in heap.threads.iter() {
919            threads.push(thread_image(heap, self.host_registry(), thread)?);
920        }
921        let mut native_closures = Vec::new();
922        for (_, _, closure) in heap.native_closures.iter() {
923            native_closures.push(NativeClosureImage {
924                id: closure.id.raw(),
925                native: closure.native,
926                values: closure
927                    .values
928                    .iter()
929                    .map(|value| enc_value(heap, *value))
930                    .collect::<Result<_, _>>()?,
931                state: closure.state.clone(),
932            });
933        }
934        let mut userdata = Vec::new();
935        for (_, _, object) in heap.userdata.iter() {
936            userdata.push(self.userdata_image(object)?);
937        }
938        Ok(Image {
939            iteration_profile: self.iteration_profile,
940            effect_domain: self.effect_domain(),
941            next_object_id: heap.next_object_id,
942            next_sequence: self.next_sequence(),
943            fuel_consumed: self.fuel_consumed(),
944            fuel_limit: self.fuel_limit(),
945            last_completed_wait: self.last_completed_wait(),
946            completed_waits: self.completed_waits(),
947            host_call: self.host_call(),
948            callback_failed: self.callback_failed(),
949            trap: trap_tag(self.trap_reason()),
950            max_objects: self.max_objects(),
951            max_stack_slots: self.max_stack_slots_public(),
952            max_string: heap.max_string as u32,
953            gc: heap.gc.clone(),
954            library: heap.library.clone(),
955            type_metatables: {
956                let mut ids = [0; crate::heap::BASIC_TYPES];
957                for (id, handle) in ids.iter_mut().zip(heap.type_metatables) {
958                    *id = optional_table_id(heap, handle)?;
959                }
960                ids
961            },
962            globals: optional_table_id(heap, heap.globals)?,
963            registry: optional_table_id(heap, heap.registry)?,
964            active: optional_thread_id(heap, heap.active)?,
965            entry: optional_thread_id(heap, heap.entry)?,
966            strings,
967            natives: heap.natives.clone(),
968            reserved: heap
969                .reserved
970                .iter()
971                .map(|handle| {
972                    heap.strings
973                        .get(*handle)
974                        .map(|string| string.id.raw())
975                        .ok_or(SnapshotError::DanglingReference)
976                })
977                .collect::<Result<_, _>>()?,
978            protos,
979            tables,
980            upvalues,
981            closures,
982            threads,
983            native_closures,
984            userdata,
985            finalizers: {
986                let fin = &heap.finalizers;
987                let ids = |list: &mut dyn Iterator<Item = &crate::heap::FinRef>| {
988                    list.map(|fin| {
989                        heap.object_id_of_value(fin.value())
990                            .map(ObjectId::raw)
991                            .ok_or(SnapshotError::DanglingReference)
992                    })
993                    .collect::<Result<Vec<_>, _>>()
994                };
995                FinalizersImage {
996                    registered: ids(&mut fin.registered.iter())?,
997                    old_until: fin.old_until,
998                    new_from: fin.new_from,
999                    pending: ids(&mut fin.pending.iter())?,
1000                    running: fin.running,
1001                    closing: fin.closing,
1002                    exit: fin.exit,
1003                    closed: fin.closed.map_or(0, Status::tag),
1004                    close_closure: match fin.close_closure {
1005                        Some(handle) => heap
1006                            .closures
1007                            .get(handle)
1008                            .ok_or(SnapshotError::DanglingReference)?
1009                            .id
1010                            .raw(),
1011                        None => 0,
1012                    },
1013                }
1014            },
1015            collector: collector_image(heap)?,
1016            index: ImageIndex::default(),
1017        })
1018    }
1019
1020    /// A full userdata's image. A host value goes through its type's
1021    /// codec; a type without one refuses the snapshot (ADR 0045).
1022    fn userdata_image(
1023        &self,
1024        object: &crate::heap::UserdataObj,
1025    ) -> Result<UserdataImage, SnapshotError> {
1026        use crate::userdata::Payload;
1027        let heap = self.heap();
1028        let payload = match &object.payload {
1029            Payload::File(file) => {
1030                if !file.closed && file.policy == crate::hostcaps::HandlePolicy::Refuse {
1031                    return Err(SnapshotError::NonPortableResource { object: object.id });
1032                }
1033                PayloadImage::File((**file).clone())
1034            }
1035            Payload::Bytes(bytes) => PayloadImage::Bytes(bytes.to_vec()),
1036            Payload::Host { symbol, value } => {
1037                let host = self
1038                    .registry()
1039                    .userdata_type(symbol)
1040                    .ok_or(SnapshotError::UnknownUserdataType)?;
1041                // Restore refuses a value that counts more than its charge:
1042                // refuse it here, so no checkpoint is written that cannot
1043                // be restored.
1044                if (host.size)(value.as_ref()).is_none_or(|size| size > object.charge) {
1045                    return Err(SnapshotError::UserdataCharge);
1046                }
1047                match host.policy {
1048                    crate::userdata::Policy::Refuse => {
1049                        return Err(SnapshotError::NonPortableUserdata);
1050                    }
1051                    crate::userdata::Policy::Portable(codec) => {
1052                        let bytes = (codec.encode)(value.as_ref())
1053                            .ok_or(SnapshotError::UnknownUserdataType)?;
1054                        if bytes.len() > crate::userdata::MAX_USERDATA_BYTES {
1055                            return Err(SnapshotError::LimitExceeded);
1056                        }
1057                        PayloadImage::Host {
1058                            symbol: (*symbol).to_string(),
1059                            bytes,
1060                        }
1061                    }
1062                    crate::userdata::Policy::Rebind { key, .. } => {
1063                        let key = key(value.as_ref()).ok_or(SnapshotError::UnknownUserdataType)?;
1064                        if key.len() > crate::MAX_REBIND_KEY {
1065                            return Err(SnapshotError::LimitExceeded);
1066                        }
1067                        PayloadImage::Rebind {
1068                            symbol: (*symbol).to_string(),
1069                            key,
1070                        }
1071                    }
1072                }
1073            }
1074        };
1075        Ok(UserdataImage {
1076            id: object.id.raw(),
1077            metatable: optional_table_id(heap, object.metatable)?,
1078            user_values: object
1079                .user_values
1080                .iter()
1081                .map(|value| enc_value(heap, *value))
1082                .collect::<Result<_, _>>()?,
1083            payload,
1084            charge: object.charge,
1085        })
1086    }
1087}
1088
1089impl Runtime {
1090    fn trap_reason(&self) -> Option<TerminationReason> {
1091        self.trap_public()
1092    }
1093
1094    fn max_objects(&self) -> u32 {
1095        self.max_objects_public()
1096    }
1097}
1098
1099/// The collector's state, objects by id (ADR 0050). Dead objects waiting
1100/// for the sweep are not in the image, nor their marks.
1101/// The logical size of the objects a snapshot writes: every live one.
1102fn live_bytes(heap: &Heap) -> u64 {
1103    use crate::heap::LogicalSize;
1104    let mut total = 0u64;
1105    for kind in crate::gc::KINDS {
1106        let bytes: u64 = crate::heap::on_arena!(heap, kind, arena => {
1107            arena.iter().map(|(_, _, object)| object.logical_size()).sum()
1108        });
1109        total = total.saturating_add(bytes);
1110    }
1111    total
1112}
1113
1114fn collector_image(heap: &Heap) -> Result<CollectorImage, SnapshotError> {
1115    use crate::gc::{How, Phase};
1116    use crate::heap::TraceRef;
1117    let collector = &heap.collector;
1118    let id = |object: TraceRef| {
1119        heap.id_of(object)
1120            .map(ObjectId::raw)
1121            .ok_or(SnapshotError::DanglingReference)
1122    };
1123    let table = |index| TraceRef {
1124        kind: Kind::Table,
1125        index,
1126    };
1127    let (phase, atomic) = match collector.phase {
1128        Phase::Pause => (0, 0),
1129        Phase::Begin => (1, 0),
1130        Phase::Propagate => (2, 0),
1131        Phase::Atomic(step) => (3, step.tag()),
1132        Phase::Sweep => (4, 0),
1133        Phase::Touched => (5, 0),
1134    };
1135    let scan = match collector.scan {
1136        Some(scan) => {
1137            let (how, keys, values) = match scan.how {
1138                How::Object => (0, false, false),
1139                How::Entries { keys, values } => (1, keys, values),
1140                How::Ephemeron => (2, false, false),
1141            };
1142            Some((id(scan.object)?, scan.pos, how, keys, values))
1143        }
1144        None => None,
1145    };
1146    let mut waiting = collector
1147        .waiting
1148        .iter()
1149        .map(|(&(kind, index), values)| {
1150            Ok((
1151                id(TraceRef { kind, index })?,
1152                values
1153                    .iter()
1154                    .map(|value| enc_value(heap, *value))
1155                    .collect::<Result<Vec<_>, _>>()?,
1156            ))
1157        })
1158        .collect::<Result<Vec<_>, SnapshotError>>()?;
1159    waiting.sort_by_key(|(key, _)| *key);
1160    let mut marks = Vec::new();
1161    let mut again = Vec::new();
1162    let mut ages = Vec::new();
1163    let mut young = Vec::new();
1164    macro_rules! arena {
1165        ($arena:ident, $kind:expr) => {
1166            // A young collection's sweep leaves freed and promoted entries
1167            // behind it; what it passed is told by marks and ages.
1168            let mut listed = HashSet::new();
1169            for &index in heap.$arena.young() {
1170                // Dead ones a young collection's sweep has not reached
1171                // are not written, like any dead object.
1172                let dead = heap.$arena.mark_of(index).is_none_or(|found| {
1173                    crate::heap::mark::is_white(found) && found != collector.white
1174                });
1175                if index == crate::gc::TOMB
1176                    || dead
1177                    || heap.$arena.age_of(index) > crate::heap::age::SURVIVAL
1178                {
1179                    continue;
1180                }
1181                if let Some(found) = heap.id_of(TraceRef { kind: $kind, index }) {
1182                    listed.insert(index);
1183                    young.push(found.raw());
1184                }
1185            }
1186            // Only what differs from the default is written: in
1187            // generational form, black and old off the young lists; white
1188            // and new otherwise.
1189            for (index, _, object) in heap.$arena.iter() {
1190                let mark = heap.$arena.mark_of(index).unwrap_or(collector.white);
1191                let age = heap.$arena.age_of(index);
1192                let default = if collector.generational && !listed.contains(&index) {
1193                    (crate::heap::mark::BLACK, crate::heap::age::OLD)
1194                } else {
1195                    (collector.white, crate::heap::age::NEW)
1196                };
1197                if (mark, age) == default {
1198                    continue;
1199                }
1200                if mark != collector.white {
1201                    marks.push((object.id.raw(), mark, age));
1202                } else {
1203                    ages.push((object.id.raw(), age));
1204                }
1205            }
1206            // An entry no longer gray (a young object a young collection's
1207            // sweep made white) costs nothing when taken, so is left out.
1208            for &index in heap.$arena.again() {
1209                if heap.$arena.mark_of(index) == Some(crate::heap::mark::GRAY) {
1210                    again.push(id(TraceRef { kind: $kind, index })?);
1211                }
1212            }
1213        };
1214    }
1215    arena!(strings, Kind::String);
1216    arena!(tables, Kind::Table);
1217    arena!(protos, Kind::Proto);
1218    arena!(upvalues, Kind::Upvalue);
1219    arena!(closures, Kind::Closure);
1220    arena!(threads, Kind::Thread);
1221    arena!(native_closures, Kind::NativeClosure);
1222    arena!(userdata, Kind::Userdata);
1223    Ok(CollectorImage {
1224        phase,
1225        atomic,
1226        white: collector.white,
1227        gray: collector
1228            .gray
1229            .iter()
1230            .map(|object| id(*object))
1231            .collect::<Result<_, _>>()?,
1232        scan,
1233        weak: collector
1234            .weak
1235            .iter()
1236            .map(|entry| Ok((id(table(entry.table))?, entry.keys, entry.values)))
1237            .collect::<Result<_, SnapshotError>>()?,
1238        late: collector.late,
1239        ephemerons: collector
1240            .ephemerons
1241            .iter()
1242            .map(|index| id(table(*index)))
1243            .collect::<Result<_, _>>()?,
1244        waiting,
1245        cursor: collector.cursor,
1246        inner: collector.inner,
1247        marked_bytes: collector.marked_bytes,
1248        debt_base: collector.debt_base,
1249        marking_debt: collector.marking_debt,
1250        work_base: collector.work_base,
1251        sweep_left: collector.sweep_left,
1252        reset: collector.reset,
1253        marks,
1254        again,
1255        generational: collector.generational,
1256        minor: collector.minor,
1257        to_old: collector.to_old,
1258        decide: collector.decide.tag(),
1259        // The dead objects are not written: what they count is.
1260        unreleased: heap.gc.used.saturating_sub(live_bytes(heap)),
1261        promoted: collector.promoted,
1262        ages,
1263        young,
1264        revisit: collector
1265            .revisit
1266            .iter()
1267            .map(|object| id(*object))
1268            .collect::<Result<_, _>>()?,
1269        touched: collector
1270            .touched
1271            .iter()
1272            .map(|object| id(*object))
1273            .collect::<Result<_, _>>()?,
1274    })
1275}
1276
1277fn trap_tag(trap: Option<TerminationReason>) -> u8 {
1278    match trap {
1279        None => 0,
1280        Some(TerminationReason::FuelLimitExceeded) => 1,
1281        Some(TerminationReason::MemoryLimit) => 2,
1282        Some(TerminationReason::ObjectIdExhausted) => 3,
1283    }
1284}
1285
1286fn trap_from(tag: u8) -> Result<Option<TerminationReason>, SnapshotError> {
1287    Ok(match tag {
1288        0 => None,
1289        1 => Some(TerminationReason::FuelLimitExceeded),
1290        2 => Some(TerminationReason::MemoryLimit),
1291        3 => Some(TerminationReason::ObjectIdExhausted),
1292        _ => return Err(SnapshotError::InvalidTag),
1293    })
1294}
1295
1296fn optional_table_id(heap: &Heap, handle: Option<Handle<TableObj>>) -> Result<u64, SnapshotError> {
1297    match handle {
1298        Some(handle) => Ok(heap
1299            .tables
1300            .get(handle)
1301            .ok_or(SnapshotError::DanglingReference)?
1302            .id
1303            .raw()),
1304        None => Ok(0),
1305    }
1306}
1307
1308fn optional_thread_id(
1309    heap: &Heap,
1310    handle: Option<Handle<ThreadObj>>,
1311) -> Result<u64, SnapshotError> {
1312    match handle {
1313        Some(handle) => Ok(heap
1314            .threads
1315            .get(handle)
1316            .ok_or(SnapshotError::DanglingReference)?
1317            .id
1318            .raw()),
1319        None => Ok(0),
1320    }
1321}
1322
1323fn proto_image(heap: &Heap, proto: &Proto) -> Result<ProtoImage, SnapshotError> {
1324    let mut children = Vec::new();
1325    for child in &proto.children {
1326        children.push(
1327            heap.protos
1328                .get(*child)
1329                .ok_or(SnapshotError::DanglingReference)?
1330                .id
1331                .raw(),
1332        );
1333    }
1334    let mut const_ids = Vec::with_capacity(proto.const_strings.len());
1335    for string in &proto.const_strings {
1336        const_ids.push(
1337            heap.strings
1338                .get(*string)
1339                .ok_or(SnapshotError::DanglingReference)?
1340                .id
1341                .raw(),
1342        );
1343    }
1344    Ok(ProtoImage {
1345        id: proto.id.raw(),
1346        max_reg: proto.max_reg,
1347        params: proto.params,
1348        vararg: proto.vararg,
1349        ops: proto.ops.clone(),
1350        const_ids,
1351        byte_consts: proto.byte_consts.clone(),
1352        captures: proto.captures.clone(),
1353        children,
1354        source: match proto.source {
1355            Some(handle) => heap
1356                .strings
1357                .get(handle)
1358                .ok_or(SnapshotError::DanglingReference)?
1359                .id
1360                .raw(),
1361            None => 0,
1362        },
1363        debug: proto.debug.clone(),
1364    })
1365}
1366
1367fn table_image(heap: &Heap, table: &TableObj) -> Result<TableImage, SnapshotError> {
1368    let mut slots = Vec::new();
1369    for (index, slot) in table.table.slots().iter().enumerate() {
1370        let body = match slot.pair() {
1371            Some((key, value)) => SlotBody::Live {
1372                key: enc_value(heap, key)?,
1373                value: enc_value(heap, value)?,
1374            },
1375            None => SlotBody::Dead(dead_key(&slot.key)?),
1376        };
1377        slots.push(SlotImage {
1378            ordinal: u32::try_from(index).map_err(|_| SnapshotError::LimitExceeded)?,
1379            body,
1380        });
1381    }
1382    let metatable = match table.metatable {
1383        Some(handle) => heap
1384            .tables
1385            .get(handle)
1386            .ok_or(SnapshotError::DanglingReference)?
1387            .id
1388            .raw(),
1389        None => 0,
1390    };
1391    Ok(TableImage {
1392        id: table.id.raw(),
1393        metatable,
1394        slots,
1395    })
1396}
1397
1398fn dead_key(key: &TableKey) -> Result<DeadKey, SnapshotError> {
1399    Ok(match key {
1400        TableKey::Bool(bit) => DeadKey::Bool(*bit),
1401        TableKey::Integer(integer) => DeadKey::Integer(*integer),
1402        TableKey::Float(bits) => DeadKey::Float(*bits),
1403        TableKey::String(key) => DeadKey::Bytes(key.bytes().to_vec()),
1404        TableKey::Object(id) => DeadKey::Object(id.raw()),
1405        TableKey::Native(index) => DeadKey::Native(*index),
1406        TableKey::Light(domain, bits) => DeadKey::Light(*domain, *bits),
1407    })
1408}
1409
1410fn up_image(heap: &Heap, upvalue: &UpvalueObj) -> Result<UpImage, SnapshotError> {
1411    let state = match &upvalue.state {
1412        UpvalueState::Closed(value) => UpImageState::Closed(enc_value(heap, *value)?),
1413        UpvalueState::Open { thread, slot } => UpImageState::Open {
1414            thread: heap
1415                .threads
1416                .get(*thread)
1417                .ok_or(SnapshotError::DanglingReference)?
1418                .id
1419                .raw(),
1420            slot: *slot,
1421        },
1422    };
1423    Ok(UpImage {
1424        id: upvalue.id.raw(),
1425        state,
1426    })
1427}
1428
1429fn closure_image(heap: &Heap, closure: &ClosureObj) -> Result<ClosureImage, SnapshotError> {
1430    let proto = heap
1431        .protos
1432        .get(closure.proto)
1433        .ok_or(SnapshotError::DanglingReference)?
1434        .id
1435        .raw();
1436    let mut upvalues = Vec::new();
1437    for upvalue in &closure.upvalues {
1438        upvalues.push(
1439            heap.upvalues
1440                .get(*upvalue)
1441                .ok_or(SnapshotError::DanglingReference)?
1442                .id
1443                .raw(),
1444        );
1445    }
1446    Ok(ClosureImage {
1447        id: closure.id.raw(),
1448        proto,
1449        upvalues,
1450    })
1451}
1452
1453fn thread_image(
1454    heap: &Heap,
1455    registry: &HostRegistry,
1456    thread: &ThreadObj,
1457) -> Result<ThreadImage, SnapshotError> {
1458    let mut stack = Vec::new();
1459    for value in &thread.stack {
1460        stack.push(enc_value(heap, *value)?);
1461    }
1462    let mut results = Vec::new();
1463    for value in &thread.host_results {
1464        results.push(enc_value(heap, *value)?);
1465    }
1466    let resumed_by = match thread.resumed_by {
1467        Some(parent) => heap
1468            .threads
1469            .get(parent)
1470            .ok_or(SnapshotError::DanglingReference)?
1471            .id
1472            .raw(),
1473        None => 0,
1474    };
1475    let mut frames = Vec::new();
1476    for frame in &thread.frames {
1477        frames.push(frame_image(heap, frame)?);
1478    }
1479    let error = match thread.error {
1480        Some((fault, value)) => Some((fault.tag(), enc_value(heap, value)?)),
1481        None => None,
1482    };
1483    let unwind = thread
1484        .unwind
1485        .as_deref()
1486        .map(|unwind| unwind_image(heap, unwind))
1487        .transpose()?;
1488    Ok(ThreadImage {
1489        id: thread.id.raw(),
1490        status: thread.status.tag(),
1491        resumed_by,
1492        top: thread.top,
1493        stack,
1494        results,
1495        frames,
1496        error,
1497        unwind,
1498        coroutine: thread.coroutine,
1499        closing: thread.closing,
1500        tbc: thread.tbc.clone(),
1501        charged_slots: thread.charged_slots,
1502        charged_held: thread.charged_held,
1503        hook: heap
1504            .hooks
1505            .get(thread.id)
1506            .map(|h| hook_image(heap, registry, h))
1507            .transpose()?,
1508    })
1509}
1510
1511fn unwind_image(heap: &Heap, unwind: &crate::heap::Unwind) -> Result<UnwindImage, SnapshotError> {
1512    Ok(UnwindImage {
1513        error: unwind
1514            .error
1515            .map(|(fault, value)| Ok::<_, SnapshotError>((fault.tag(), enc_value(heap, value)?)))
1516            .transpose()?,
1517        phase: unwind.phase,
1518    })
1519}
1520
1521fn meta_image(heap: &Heap, meta: &crate::heap::MetaCall) -> Result<MetaImage, SnapshotError> {
1522    use crate::heap::{CloseNext, MetaEvent};
1523    let event = match (meta.event, meta.close.as_deref()) {
1524        (MetaEvent::Close, Some(closing)) => EventImage::Close {
1525            from: closing.from,
1526            next: match closing.next {
1527                CloseNext::Advance => NextImage::Advance,
1528                CloseNext::Return { src, produced } => NextImage::Return { src, produced },
1529                CloseNext::Unwind(unwind) => NextImage::Unwind(unwind_image(heap, &unwind)?),
1530            },
1531        },
1532        (MetaEvent::Close, None) | (_, Some(_)) => return Err(SnapshotError::InvalidStructure),
1533        (event, None) => EventImage::Plain(event),
1534    };
1535    Ok(MetaImage {
1536        event,
1537        slot: meta.slot,
1538        nargs: meta.nargs,
1539        phase: meta.phase,
1540    })
1541}
1542
1543fn frame_image(heap: &Heap, frame: &Frame) -> Result<FrameImage, SnapshotError> {
1544    let closure = heap
1545        .closures
1546        .get(frame.closure)
1547        .ok_or(SnapshotError::DanglingReference)?
1548        .id
1549        .raw();
1550    let pending = match frame.pending() {
1551        None => PendingImage::None,
1552        Some(Pending::Deferred) => PendingImage::Deferred,
1553        Some(Pending::Prepared {
1554            sequence,
1555            symbol,
1556            arg,
1557            dest,
1558        }) => PendingImage::Prepared {
1559            sequence: *sequence,
1560            symbol: symbol.clone(),
1561            arg: *arg,
1562            dest: *dest,
1563        },
1564        Some(Pending::Waiting {
1565            sequence,
1566            symbol,
1567            arg,
1568            dest,
1569            wait_key,
1570        }) => PendingImage::Waiting {
1571            sequence: *sequence,
1572            symbol: symbol.clone(),
1573            arg: *arg,
1574            dest: *dest,
1575            wait_key: *wait_key,
1576        },
1577        Some(Pending::Resuming {
1578            child,
1579            dest,
1580            nresults,
1581        }) => PendingImage::Resuming {
1582            child: heap
1583                .threads
1584                .get(*child)
1585                .ok_or(SnapshotError::DanglingReference)?
1586                .id
1587                .raw(),
1588            dest: *dest,
1589            nresults: *nresults,
1590        },
1591        Some(Pending::Assigning { src, nvalues, next }) => PendingImage::Assigning {
1592            src: *src,
1593            nvalues: *nvalues,
1594            next: *next,
1595        },
1596        Some(Pending::Capability {
1597            sequence,
1598            wait_key,
1599            completed,
1600        }) => PendingImage::Capability {
1601            sequence: *sequence,
1602            wait_key: *wait_key,
1603            completed: *completed,
1604        },
1605        Some(Pending::NativePrepared { sequence }) => PendingImage::NativePrepared {
1606            sequence: *sequence,
1607        },
1608        Some(Pending::NativeWaiting { sequence, wait_key }) => PendingImage::NativeWaiting {
1609            sequence: *sequence,
1610            wait_key: *wait_key,
1611        },
1612    };
1613    let mut targets = Vec::new();
1614    {
1615        for target in frame.targets() {
1616            targets.push(match target {
1617                AssignTarget::Register(slot) => TargetImage::Register(*slot),
1618                AssignTarget::Field { table, key } => TargetImage::Field {
1619                    table: enc_value(heap, *table)?,
1620                    key: enc_value(heap, *key)?,
1621                },
1622            });
1623        }
1624    }
1625    Ok(FrameImage {
1626        closure,
1627        pc: frame.pc,
1628        base: frame.base,
1629        limit: frame.limit,
1630        nresults: frame.nresults,
1631        vararg_len: frame.vararg_len,
1632        tail: frame.is_tail(),
1633        return_hook: frame.flags & 2 != 0,
1634        pending,
1635        wait_request: frame
1636            .wait_request()
1637            .map(|wait| {
1638                Ok::<_, SnapshotError>((
1639                    wait.operation.clone(),
1640                    wait.payload
1641                        .iter()
1642                        .map(|value| enc_value(heap, *value))
1643                        .collect::<Result<Vec<_>, _>>()?,
1644                ))
1645            })
1646            .transpose()?,
1647        targets,
1648        meta: frame
1649            .meta()
1650            .map(|meta| meta_image(heap, meta))
1651            .transpose()?,
1652        boundary: match frame.boundary() {
1653            None => None,
1654            Some(crate::heap::Boundary::Protect {
1655                func,
1656                advance_caller,
1657                handler,
1658            }) => Some(BoundaryImage::Protect {
1659                func: *func,
1660                advance_caller: *advance_caller,
1661                handler: handler.map(|value| enc_value(heap, value)).transpose()?,
1662            }),
1663            Some(crate::heap::Boundary::Handler {
1664                slot,
1665                protect,
1666                target,
1667                depth,
1668                fault,
1669            }) => Some(BoundaryImage::Handler {
1670                slot: *slot,
1671                protect: *protect,
1672                target: *target,
1673                depth: *depth,
1674                fault: fault.tag(),
1675            }),
1676            Some(crate::heap::Boundary::Builtin {
1677                func,
1678                passed,
1679                advance_caller,
1680                task,
1681            }) => Some(BoundaryImage::Builtin {
1682                func: *func,
1683                passed: *passed,
1684                advance_caller: *advance_caller,
1685                task: task.clone(),
1686            }),
1687            Some(crate::heap::Boundary::Native {
1688                func,
1689                passed,
1690                advance_caller,
1691                symbol,
1692                tag,
1693                kept,
1694                sequence,
1695                error,
1696                resuming,
1697                no_yield,
1698            }) => Some(BoundaryImage::Native {
1699                func: *func,
1700                passed: *passed,
1701                advance_caller: *advance_caller,
1702                symbol: *symbol,
1703                tag: *tag,
1704                kept: *kept,
1705                sequence: *sequence,
1706                error: error
1707                    .map(|(class, value)| {
1708                        Ok::<_, SnapshotError>((class.tag(), enc_value(heap, value)?))
1709                    })
1710                    .transpose()?,
1711                resuming: *resuming,
1712                no_yield: *no_yield,
1713            }),
1714            Some(crate::heap::Boundary::Hook {
1715                func,
1716                saved_top,
1717                target,
1718                instruction,
1719                after,
1720            }) => Some(BoundaryImage::Hook {
1721                func: *func,
1722                saved_top: *saved_top,
1723                target: *target,
1724                instruction: *instruction,
1725                after: *after,
1726            }),
1727            Some(crate::heap::Boundary::HookNative {
1728                func,
1729                passed,
1730                callee,
1731                advance_caller,
1732                phase,
1733                produced,
1734                result,
1735            }) => Some(BoundaryImage::HookNative {
1736                func: *func,
1737                passed: *passed,
1738                callee: enc_value(heap, *callee)?,
1739                advance_caller: *advance_caller,
1740                phase: *phase,
1741                produced: *produced,
1742                result: *result,
1743            }),
1744            Some(crate::heap::Boundary::Finalizer { func, saved_top }) => {
1745                Some(BoundaryImage::Finalizer {
1746                    func: *func,
1747                    saved_top: *saved_top,
1748                })
1749            }
1750        },
1751    })
1752}
1753
1754fn enc_value(heap: &Heap, value: Value) -> Result<EncValue, SnapshotError> {
1755    Ok(match value {
1756        Value::Nil => EncValue::Nil,
1757        Value::Bool(bit) => EncValue::Bool(bit),
1758        Value::Integer(integer) => EncValue::Integer(integer),
1759        Value::Float(number) => EncValue::Float(number.to_bits()),
1760        Value::String(handle) => EncValue::String(
1761            heap.strings
1762                .get(handle)
1763                .ok_or(SnapshotError::DanglingReference)?
1764                .id
1765                .raw(),
1766        ),
1767        Value::Table(handle) => EncValue::Table(
1768            heap.tables
1769                .get(handle)
1770                .ok_or(SnapshotError::DanglingReference)?
1771                .id
1772                .raw(),
1773        ),
1774        Value::Closure(handle) => EncValue::Closure(
1775            heap.closures
1776                .get(handle)
1777                .ok_or(SnapshotError::DanglingReference)?
1778                .id
1779                .raw(),
1780        ),
1781        Value::Thread(handle) => EncValue::Thread(
1782            heap.threads
1783                .get(handle)
1784                .ok_or(SnapshotError::DanglingReference)?
1785                .id
1786                .raw(),
1787        ),
1788        Value::Native(index) => EncValue::Native(index),
1789        Value::NativeClosure(handle) => EncValue::NativeClosure(
1790            heap.native_closures
1791                .get(handle)
1792                .ok_or(SnapshotError::DanglingReference)?
1793                .id
1794                .raw(),
1795        ),
1796        Value::Userdata(handle) => EncValue::Userdata(
1797            heap.userdata
1798                .get(handle)
1799                .ok_or(SnapshotError::DanglingReference)?
1800                .id
1801                .raw(),
1802        ),
1803        Value::LightUserdata(domain, bits) => EncValue::Light(domain, bits),
1804    })
1805}
1806
1807#[cfg(test)]
1808pub(crate) fn encode(image: &Image) -> Result<Vec<u8>, SnapshotError> {
1809    encode_within(image, MAX_SNAPSHOT_BYTES)
1810}
1811
1812/// The snapshot of `image`, refused once it passes `limit` bytes: checked
1813/// after every object, so the output never grows past the limit by more
1814/// than one object.
1815pub(crate) fn encode_within(image: &Image, limit: u64) -> Result<Vec<u8>, SnapshotError> {
1816    let limit = usize::try_from(limit).unwrap_or(usize::MAX);
1817    let mut out = Vec::new();
1818    write_image(&mut out, image, limit)?;
1819    let crc = crc32(&out);
1820    out.extend(crc.to_le_bytes());
1821    within(&out, limit)?;
1822    Ok(out)
1823}
1824
1825fn within(out: &[u8], limit: usize) -> Result<(), SnapshotError> {
1826    if out.len() > limit {
1827        return Err(SnapshotError::LimitExceeded);
1828    }
1829    Ok(())
1830}
1831
1832fn write_image(out: &mut Vec<u8>, image: &Image, limit: usize) -> Result<(), SnapshotError> {
1833    out.extend(MAGIC);
1834    out.extend(VERSION.to_le_bytes());
1835    out.extend(BYTECODE_REVISION.to_le_bytes());
1836    out.extend(TABLES_REVISION.to_le_bytes());
1837    out.extend(FUEL_REVISION.to_le_bytes());
1838    out.extend(GC_REVISION.to_le_bytes());
1839    out.extend(image.effect_domain.to_le_bytes());
1840    out.extend(image.next_object_id.to_le_bytes());
1841    out.extend(image.next_sequence.to_le_bytes());
1842    out.extend(image.fuel_consumed.to_le_bytes());
1843    match image.fuel_limit {
1844        Some(limit) => {
1845            out.push(1);
1846            out.extend(limit.to_le_bytes());
1847        }
1848        None => {
1849            out.push(0);
1850            out.extend(0u64.to_le_bytes());
1851        }
1852    }
1853    match image.last_completed_wait {
1854        Some(key) => {
1855            out.push(1);
1856            out.extend(key.to_le_bytes());
1857        }
1858        None => {
1859            out.push(0);
1860            out.extend(0u64.to_le_bytes());
1861        }
1862    }
1863    out.push(u8::from(image.host_call));
1864    out.push(u8::from(image.callback_failed));
1865    write_count(out, image.completed_waits.len(), MAX_OBJECTS)?;
1866    for key in &image.completed_waits {
1867        out.extend(key.to_le_bytes());
1868    }
1869    out.push(image.trap);
1870    out.extend(image.max_objects.to_le_bytes());
1871    out.extend(image.max_stack_slots.to_le_bytes());
1872    out.extend(image.max_string.to_le_bytes());
1873    out.push(u8::from(image.gc.auto));
1874    for field in [
1875        image.gc.debt,
1876        image.gc.threshold,
1877        image.gc.min_debt,
1878        image.gc.live,
1879        image.gc.collections,
1880        image.gc.quota,
1881    ] {
1882        out.extend(field.to_le_bytes());
1883    }
1884    for word in image.library.rng {
1885        out.extend(word.to_le_bytes());
1886    }
1887    out.extend(image.library.entropy.to_le_bytes());
1888    for id in image.type_metatables {
1889        out.extend(id.to_le_bytes());
1890    }
1891    out.extend(image.globals.to_le_bytes());
1892    out.extend(image.registry.to_le_bytes());
1893    out.extend(image.active.to_le_bytes());
1894    out.extend(image.entry.to_le_bytes());
1895    write_count(out, image.strings.len(), MAX_OBJECTS)?;
1896    for (id, bytes) in &image.strings {
1897        within(out, limit)?;
1898        out.extend(id.to_le_bytes());
1899        write_count(out, bytes.len(), MAX_STRING_BYTES)?;
1900        out.extend(bytes);
1901    }
1902    write_count(out, image.natives.len(), MAX_OBJECTS)?;
1903    for symbol in &image.natives {
1904        write_str(out, symbol)?;
1905    }
1906    write_count(
1907        out,
1908        image.reserved.len(),
1909        crate::heap::reserved_texts().count() as u32,
1910    )?;
1911    for id in &image.reserved {
1912        out.extend(id.to_le_bytes());
1913    }
1914    write_count(out, image.protos.len(), MAX_OBJECTS)?;
1915    for proto in &image.protos {
1916        within(out, limit)?;
1917        write_proto(out, proto)?;
1918    }
1919    write_count(out, image.tables.len(), MAX_OBJECTS)?;
1920    for table in &image.tables {
1921        within(out, limit)?;
1922        out.extend(table.id.to_le_bytes());
1923        out.extend(table.metatable.to_le_bytes());
1924        let live = table
1925            .slots
1926            .iter()
1927            .filter(|slot| matches!(slot.body, SlotBody::Live { .. }))
1928            .count();
1929        let dead = table.slots.len() - live;
1930        write_count(out, live, MAX_TABLE_ENTRIES)?;
1931        write_count(out, dead, MAX_TABLE_ENTRIES)?;
1932        if table.slots.len() > MAX_TABLE_ENTRIES as usize {
1933            return Err(SnapshotError::LimitExceeded);
1934        }
1935        for slot in &table.slots {
1936            out.extend(slot.ordinal.to_le_bytes());
1937            match &slot.body {
1938                SlotBody::Live { key, value } => {
1939                    out.push(1);
1940                    write_value(out, key);
1941                    write_value(out, value);
1942                }
1943                SlotBody::Dead(key) => {
1944                    out.push(2);
1945                    write_dead_key(out, key)?;
1946                }
1947            }
1948        }
1949    }
1950    write_count(out, image.upvalues.len(), MAX_OBJECTS)?;
1951    for upvalue in &image.upvalues {
1952        within(out, limit)?;
1953        out.extend(upvalue.id.to_le_bytes());
1954        match &upvalue.state {
1955            UpImageState::Closed(value) => {
1956                out.push(1);
1957                write_value(out, value);
1958            }
1959            UpImageState::Open { thread, slot } => {
1960                out.push(2);
1961                out.extend(thread.to_le_bytes());
1962                out.extend(slot.to_le_bytes());
1963            }
1964        }
1965    }
1966    write_count(out, image.closures.len(), MAX_OBJECTS)?;
1967    for closure in &image.closures {
1968        within(out, limit)?;
1969        out.extend(closure.id.to_le_bytes());
1970        out.extend(closure.proto.to_le_bytes());
1971        write_count(out, closure.upvalues.len(), MAX_OBJECTS)?;
1972        for id in &closure.upvalues {
1973            out.extend(id.to_le_bytes());
1974        }
1975    }
1976    write_count(out, image.threads.len(), MAX_OBJECTS)?;
1977    for thread in &image.threads {
1978        within(out, limit)?;
1979        write_thread(out, thread)?;
1980    }
1981    write_count(out, image.native_closures.len(), MAX_OBJECTS)?;
1982    for closure in &image.native_closures {
1983        within(out, limit)?;
1984        out.extend(closure.id.to_le_bytes());
1985        out.extend(closure.native.to_le_bytes());
1986        write_count(out, closure.values.len(), MAX_CLOSURE_VALUES)?;
1987        for value in &closure.values {
1988            write_value(out, value);
1989        }
1990        write_count(out, closure.state.len(), MAX_CLOSURE_VALUES)?;
1991        for word in &closure.state {
1992            out.extend(word.to_le_bytes());
1993        }
1994    }
1995    write_count(out, image.userdata.len(), MAX_OBJECTS)?;
1996    for userdata in &image.userdata {
1997        within(out, limit)?;
1998        out.extend(userdata.id.to_le_bytes());
1999        out.extend(userdata.metatable.to_le_bytes());
2000        write_count(out, userdata.user_values.len(), MAX_USER_VALUES)?;
2001        for value in &userdata.user_values {
2002            write_value(out, value);
2003        }
2004        match &userdata.payload {
2005            PayloadImage::File(file) => {
2006                out.push(4);
2007                file.encode(out);
2008            }
2009            PayloadImage::Bytes(bytes) => {
2010                out.push(1);
2011                write_count(out, bytes.len(), MAX_USERDATA_BYTES)?;
2012                out.extend(bytes);
2013            }
2014            PayloadImage::Host { symbol, bytes } => {
2015                out.push(2);
2016                write_str(out, symbol)?;
2017                write_count(out, bytes.len(), MAX_USERDATA_BYTES)?;
2018                out.extend(bytes);
2019            }
2020            PayloadImage::Rebind { symbol, key } => {
2021                out.push(3);
2022                write_str(out, symbol)?;
2023                write_count(out, key.len(), crate::MAX_REBIND_KEY as u32)?;
2024                out.extend(key);
2025            }
2026        }
2027        out.extend(userdata.charge.to_le_bytes());
2028    }
2029    let fin = &image.finalizers;
2030    for list in [&fin.registered, &fin.pending] {
2031        write_count(out, list.len(), MAX_OBJECTS)?;
2032        for id in list {
2033            out.extend(id.to_le_bytes());
2034        }
2035    }
2036    out.extend(fin.old_until.to_le_bytes());
2037    out.extend(fin.new_from.to_le_bytes());
2038    out.push(u8::from(fin.running));
2039    out.push(u8::from(fin.closing));
2040    out.push(fin.closed);
2041    out.extend(fin.close_closure.to_le_bytes());
2042    match fin.exit {
2043        None => out.push(0),
2044        Some(exit) => {
2045            out.push(exit.phase as u8);
2046            out.push(u8::from(exit.close));
2047            let (tag, code) = match exit.status {
2048                crate::ExitStatus::Success => (0, 0),
2049                crate::ExitStatus::Failure => (1, 0),
2050                crate::ExitStatus::Code(code) => (2, code),
2051            };
2052            out.push(tag);
2053            out.extend(code.to_le_bytes());
2054        }
2055    }
2056    write_collector(out, image)?;
2057    // Optional schema-25 extension. Old readers reject trailing bytes.
2058    if image.iteration_profile == crate::IterationProfile::Sorted {
2059        out.extend(b"ITER\x01");
2060    }
2061    Ok(())
2062}
2063
2064/// Bound on each of the collector's lists in a snapshot.
2065/// Entries of one collector list: an object can be on a list once, or
2066/// twice counting dead slots not yet swept.
2067const MAX_GC_LIST: u32 = 2 * MAX_OBJECTS;
2068
2069fn write_ids(out: &mut Vec<u8>, ids: &[u64]) -> Result<(), SnapshotError> {
2070    write_count(out, ids.len(), MAX_GC_LIST)?;
2071    for id in ids {
2072        out.extend(id.to_le_bytes());
2073    }
2074    Ok(())
2075}
2076
2077fn write_collector(out: &mut Vec<u8>, image: &Image) -> Result<(), SnapshotError> {
2078    let gc = &image.gc;
2079    out.push(gc.pause);
2080    out.push(gc.stepmul);
2081    out.push(gc.stepsize);
2082    out.extend(gc.sched.to_le_bytes());
2083    out.extend(gc.owed.to_le_bytes());
2084    match gc.full {
2085        Some(target) => {
2086            out.push(1);
2087            out.extend(target.to_le_bytes());
2088        }
2089        None => {
2090            out.push(0);
2091            out.extend(0u64.to_le_bytes());
2092        }
2093    }
2094    out.extend(gc.prepaid.to_le_bytes());
2095    out.extend(gc.work.to_le_bytes());
2096    out.extend(gc.cycle_work.to_le_bytes());
2097    out.extend(gc.trace.to_le_bytes());
2098    out.push(u8::from(gc.generational));
2099    out.push(gc.minormul);
2100    out.push(gc.majormul);
2101    for word in [gc.major_base, gc.bad, gc.minors] {
2102        out.extend(word.to_le_bytes());
2103    }
2104    out.extend(gc.major_objects.to_le_bytes());
2105    let c = &image.collector;
2106    out.push(c.phase);
2107    out.push(c.atomic);
2108    out.push(c.white);
2109    write_ids(out, &c.gray)?;
2110    match c.scan {
2111        Some((id, pos, how, keys, values)) => {
2112            out.push(1);
2113            out.extend(id.to_le_bytes());
2114            out.extend(pos.to_le_bytes());
2115            out.push(how);
2116            out.push(u8::from(keys));
2117            out.push(u8::from(values));
2118        }
2119        None => out.push(0),
2120    }
2121    write_count(out, c.weak.len(), MAX_GC_LIST)?;
2122    for (id, keys, values) in &c.weak {
2123        out.extend(id.to_le_bytes());
2124        out.push(u8::from(*keys));
2125        out.push(u8::from(*values));
2126    }
2127    out.extend(c.late.to_le_bytes());
2128    write_ids(out, &c.ephemerons)?;
2129    write_count(out, c.waiting.len(), MAX_GC_LIST)?;
2130    for (key, values) in &c.waiting {
2131        out.extend(key.to_le_bytes());
2132        write_count(out, values.len(), MAX_GC_LIST)?;
2133        for value in values {
2134            write_value(out, value);
2135        }
2136    }
2137    for word in [c.cursor, c.inner] {
2138        out.extend(word.to_le_bytes());
2139    }
2140    for word in [
2141        c.marked_bytes,
2142        c.debt_base,
2143        c.marking_debt,
2144        c.work_base,
2145        c.sweep_left,
2146    ] {
2147        out.extend(word.to_le_bytes());
2148    }
2149    out.push(u8::from(c.reset));
2150    write_count(out, c.marks.len(), MAX_GC_LIST)?;
2151    for (id, mark, age) in &c.marks {
2152        out.extend(id.to_le_bytes());
2153        out.push(*mark);
2154        out.push(*age);
2155    }
2156    write_ids(out, &c.again)?;
2157    for flag in [c.generational, c.minor, c.to_old] {
2158        out.push(u8::from(flag));
2159    }
2160    out.push(c.decide);
2161    out.extend(c.unreleased.to_le_bytes());
2162    out.extend(c.promoted.to_le_bytes());
2163    write_count(out, c.ages.len(), MAX_GC_LIST)?;
2164    for (id, age) in &c.ages {
2165        out.extend(id.to_le_bytes());
2166        out.push(*age);
2167    }
2168    write_ids(out, &c.young)?;
2169    write_ids(out, &c.revisit)?;
2170    write_ids(out, &c.touched)
2171}
2172
2173fn read_ids(input: &mut &[u8]) -> Result<Vec<u64>, SnapshotError> {
2174    let count = checked_count(input, MAX_GC_LIST)?;
2175    let mut ids = Vec::with_capacity((count as usize).min(4096));
2176    for _ in 0..count {
2177        ids.push(opcode::read_u64(input)?);
2178    }
2179    Ok(ids)
2180}
2181
2182/// The collector section: the schedule into `gc`, the rest returned.
2183fn read_collector(
2184    input: &mut &[u8],
2185    gc: &mut crate::heap::GcState,
2186) -> Result<CollectorImage, SnapshotError> {
2187    gc.pause = opcode::read_u8(input)?;
2188    gc.stepmul = opcode::read_u8(input)?;
2189    gc.stepsize = opcode::read_u8(input)?;
2190    gc.sched = opcode::read_u64(input)? as i64;
2191    gc.owed = opcode::read_u64(input)?;
2192    let full = read_flag(input)?;
2193    let target = opcode::read_u64(input)?;
2194    gc.full = full.then_some(target);
2195    gc.prepaid = opcode::read_u32(input)?;
2196    gc.work = opcode::read_u64(input)?;
2197    gc.cycle_work = opcode::read_u64(input)?;
2198    gc.trace = opcode::read_u64(input)?;
2199    gc.generational = read_flag(input)?;
2200    gc.minormul = opcode::read_u8(input)?;
2201    gc.majormul = opcode::read_u8(input)?;
2202    gc.major_base = opcode::read_u64(input)?;
2203    gc.bad = opcode::read_u64(input)?;
2204    gc.minors = opcode::read_u64(input)?;
2205    gc.major_objects = opcode::read_u32(input)?;
2206    let phase = opcode::read_u8(input)?;
2207    let atomic = opcode::read_u8(input)?;
2208    let white = opcode::read_u8(input)?;
2209    let gray = read_ids(input)?;
2210    let scan = if read_flag(input)? {
2211        Some((
2212            opcode::read_u64(input)?,
2213            opcode::read_u32(input)?,
2214            opcode::read_u8(input)?,
2215            read_flag(input)?,
2216            read_flag(input)?,
2217        ))
2218    } else {
2219        None
2220    };
2221    let count = checked_count(input, MAX_GC_LIST)?;
2222    let mut weak = Vec::new();
2223    for _ in 0..count {
2224        weak.push((
2225            opcode::read_u64(input)?,
2226            read_flag(input)?,
2227            read_flag(input)?,
2228        ));
2229    }
2230    let late = opcode::read_u32(input)?;
2231    let ephemerons = read_ids(input)?;
2232    let count = checked_count(input, MAX_GC_LIST)?;
2233    let mut waiting = Vec::new();
2234    for _ in 0..count {
2235        let key = opcode::read_u64(input)?;
2236        let values = checked_count(input, MAX_GC_LIST)?;
2237        let mut list = Vec::new();
2238        for _ in 0..values {
2239            list.push(read_value(input)?);
2240        }
2241        waiting.push((key, list));
2242    }
2243    let cursor = opcode::read_u32(input)?;
2244    let inner = opcode::read_u32(input)?;
2245    let marked_bytes = opcode::read_u64(input)?;
2246    let debt_base = opcode::read_u64(input)?;
2247    let marking_debt = opcode::read_u64(input)?;
2248    let work_base = opcode::read_u64(input)?;
2249    let sweep_left = opcode::read_u64(input)?;
2250    let reset = read_flag(input)?;
2251    let count = checked_count(input, MAX_GC_LIST)?;
2252    let mut marks = Vec::new();
2253    for _ in 0..count {
2254        marks.push((
2255            opcode::read_u64(input)?,
2256            opcode::read_u8(input)?,
2257            opcode::read_u8(input)?,
2258        ));
2259    }
2260    let again = read_ids(input)?;
2261    let generational = read_flag(input)?;
2262    let minor = read_flag(input)?;
2263    let to_old = read_flag(input)?;
2264    let decide = opcode::read_u8(input)?;
2265    let unreleased = opcode::read_u64(input)?;
2266    let promoted = opcode::read_u64(input)?;
2267    let count = checked_count(input, MAX_GC_LIST)?;
2268    let mut ages = Vec::new();
2269    for _ in 0..count {
2270        ages.push((opcode::read_u64(input)?, opcode::read_u8(input)?));
2271    }
2272    let young = read_ids(input)?;
2273    let revisit = read_ids(input)?;
2274    let touched = read_ids(input)?;
2275    Ok(CollectorImage {
2276        phase,
2277        atomic,
2278        white,
2279        gray,
2280        scan,
2281        weak,
2282        late,
2283        ephemerons,
2284        waiting,
2285        cursor,
2286        inner,
2287        marked_bytes,
2288        debt_base,
2289        marking_debt,
2290        work_base,
2291        sweep_left,
2292        reset,
2293        marks,
2294        again,
2295        generational,
2296        minor,
2297        to_old,
2298        decide,
2299        unreleased,
2300        promoted,
2301        ages,
2302        young,
2303        revisit,
2304        touched,
2305    })
2306}
2307
2308fn write_dead_key(out: &mut Vec<u8>, key: &DeadKey) -> Result<(), SnapshotError> {
2309    match key {
2310        DeadKey::Bool(bit) => {
2311            out.push(1);
2312            out.push(u8::from(*bit));
2313        }
2314        DeadKey::Integer(integer) => {
2315            out.push(2);
2316            out.extend(integer.to_le_bytes());
2317        }
2318        DeadKey::Float(bits) => {
2319            out.push(3);
2320            out.extend(bits.to_le_bytes());
2321        }
2322        DeadKey::Bytes(bytes) => {
2323            out.push(4);
2324            write_count(out, bytes.len(), MAX_STRING_BYTES)?;
2325            out.extend(bytes);
2326        }
2327        DeadKey::Object(id) => {
2328            out.push(5);
2329            out.extend(id.to_le_bytes());
2330        }
2331        DeadKey::Native(index) => {
2332            out.push(6);
2333            out.extend(index.to_le_bytes());
2334        }
2335        DeadKey::Light(domain, bits) => {
2336            out.push(7);
2337            out.push(*domain as u8);
2338            out.extend(bits.to_le_bytes());
2339        }
2340    }
2341    Ok(())
2342}
2343
2344/// Writes a count the reader accepts: at most `max`, the bound `checked_count`
2345/// applies to the same field, so a state restore would refuse fails here.
2346fn write_count(out: &mut Vec<u8>, len: usize, max: u32) -> Result<(), SnapshotError> {
2347    let count = u32::try_from(len)
2348        .ok()
2349        .filter(|count| *count <= max)
2350        .ok_or(SnapshotError::LimitExceeded)?;
2351    out.extend(count.to_le_bytes());
2352    Ok(())
2353}
2354
2355fn write_proto(out: &mut Vec<u8>, proto: &ProtoImage) -> Result<(), SnapshotError> {
2356    out.extend(proto.id.to_le_bytes());
2357    out.push(proto.max_reg);
2358    out.push(proto.params);
2359    out.push(u8::from(proto.vararg));
2360    write_count(out, proto.ops.len(), MAX_INSTRUCTIONS)?;
2361    for op in &proto.ops {
2362        op.encode(out);
2363    }
2364    write_count(out, proto.const_ids.len(), MAX_CONSTS)?;
2365    for id in &proto.const_ids {
2366        out.extend(id.to_le_bytes());
2367    }
2368    write_count(out, proto.captures.len(), MAX_UPVALUES)?;
2369    for capture in &proto.captures {
2370        opcode::encode_capture(*capture, out);
2371    }
2372    write_count(out, proto.children.len(), MAX_PROTOS)?;
2373    for id in &proto.children {
2374        out.extend(id.to_le_bytes());
2375    }
2376    out.extend(proto.source.to_le_bytes());
2377    match &proto.debug {
2378        None => out.push(0),
2379        Some(debug) => {
2380            out.push(1);
2381            debug.encode(out);
2382        }
2383    }
2384    Ok(())
2385}
2386
2387/// A thread's stack, and every stack slot it names, its open upvalues'
2388/// slots aside, lie within `bound`, the snapshot's stack bound
2389/// (`Config::max_stack_slots`, ADR 0028). A running thread grows its stack
2390/// lazily, so a slot index can pass the stack's length; the bound keeps a
2391/// restored index from growing it past what the runtime allows.
2392/// [`Runtime::snapshot`] and restore apply the same test.
2393fn thread_slots_fit(thread: &ThreadImage, bound: u32) -> bool {
2394    let fits = |end: u64| end <= u64::from(bound);
2395    fits(thread.stack.len() as u64)
2396        && fits(thread.results.len() as u64)
2397        && fits(u64::from(thread.top))
2398        && thread.tbc.iter().all(|slot| fits(u64::from(*slot) + 1))
2399        && thread.frames.iter().all(|frame| {
2400            fits(u64::from(frame.base))
2401                && fits(u64::from(frame.limit))
2402                && frame.meta.as_ref().is_none_or(|meta| {
2403                    fits(u64::from(meta.slot) + 1 + u64::from(meta.nargs))
2404                        && match &meta.event {
2405                            EventImage::Close {
2406                                from,
2407                                next: NextImage::Return { src, produced },
2408                            } => {
2409                                fits(u64::from(*from))
2410                                    && fits(u64::from(*src) + u64::from(*produced))
2411                            }
2412                            EventImage::Close { from, .. } => fits(u64::from(*from)),
2413                            EventImage::Plain(_) => true,
2414                        }
2415                })
2416                && match frame.pending {
2417                    PendingImage::Assigning { src, nvalues, .. } => {
2418                        fits(u64::from(src) + u64::from(nvalues))
2419                    }
2420                    _ => true,
2421                }
2422                && frame.targets.iter().all(|target| match target {
2423                    TargetImage::Register(slot) => fits(u64::from(*slot) + 1),
2424                    TargetImage::Field { .. } => true,
2425                })
2426        })
2427}
2428
2429/// The slot bounds restore enforces, checked when a snapshot is taken.
2430fn slots_fit(image: &Image, max_stack_slots: u32) -> bool {
2431    image
2432        .threads
2433        .iter()
2434        .all(|thread| thread_slots_fit(thread, max_stack_slots))
2435        && image.upvalues.iter().all(|upvalue| match upvalue.state {
2436            UpImageState::Open { slot, .. } => slot < max_stack_slots,
2437            UpImageState::Closed(_) => true,
2438        })
2439}
2440
2441fn write_thread(out: &mut Vec<u8>, thread: &ThreadImage) -> Result<(), SnapshotError> {
2442    out.extend(thread.id.to_le_bytes());
2443    out.push(thread.status);
2444    out.extend(thread.resumed_by.to_le_bytes());
2445    out.extend(thread.top.to_le_bytes());
2446    write_count(out, thread.stack.len(), MAX_STACK_SLOTS)?;
2447    for value in &thread.stack {
2448        write_value(out, value);
2449    }
2450    write_count(out, thread.results.len(), MAX_STACK_SLOTS)?;
2451    for value in &thread.results {
2452        write_value(out, value);
2453    }
2454    write_count(out, thread.frames.len(), MAX_FRAMES)?;
2455    for frame in &thread.frames {
2456        out.extend(frame.closure.to_le_bytes());
2457        out.extend(frame.pc.to_le_bytes());
2458        out.extend(frame.base.to_le_bytes());
2459        out.extend(frame.limit.to_le_bytes());
2460        out.push(frame.nresults);
2461        out.extend(frame.vararg_len.to_le_bytes());
2462        out.push(u8::from(frame.tail));
2463        out.push(u8::from(frame.return_hook));
2464        match &frame.pending {
2465            PendingImage::None => out.push(0),
2466            PendingImage::Prepared {
2467                sequence,
2468                symbol,
2469                arg,
2470                dest,
2471            } => {
2472                out.push(1);
2473                out.extend(sequence.to_le_bytes());
2474                write_str(out, symbol)?;
2475                out.extend(arg.to_le_bytes());
2476                out.push(*dest);
2477            }
2478            PendingImage::Waiting {
2479                sequence,
2480                symbol,
2481                arg,
2482                dest,
2483                wait_key,
2484            } => {
2485                out.push(2);
2486                out.extend(sequence.to_le_bytes());
2487                write_str(out, symbol)?;
2488                out.extend(arg.to_le_bytes());
2489                out.push(*dest);
2490                out.extend(wait_key.to_le_bytes());
2491            }
2492            PendingImage::Resuming {
2493                child,
2494                dest,
2495                nresults,
2496            } => {
2497                out.push(3);
2498                out.extend(child.to_le_bytes());
2499                out.push(*dest);
2500                out.push(*nresults);
2501            }
2502            PendingImage::Assigning { src, nvalues, next } => {
2503                out.push(4);
2504                out.extend(src.to_le_bytes());
2505                out.extend(nvalues.to_le_bytes());
2506                out.extend(next.to_le_bytes());
2507            }
2508            PendingImage::NativePrepared { sequence } => {
2509                out.push(5);
2510                out.extend(sequence.to_le_bytes());
2511            }
2512            PendingImage::Capability {
2513                sequence,
2514                wait_key,
2515                completed,
2516            } => {
2517                out.push(8);
2518                out.extend(sequence.to_le_bytes());
2519                out.extend(wait_key.to_le_bytes());
2520                out.push(u8::from(*completed));
2521            }
2522            PendingImage::Deferred => out.push(7),
2523            PendingImage::NativeWaiting { sequence, wait_key } => {
2524                out.push(6);
2525                match sequence {
2526                    Some(sequence) => {
2527                        out.push(1);
2528                        out.extend(sequence.to_le_bytes());
2529                    }
2530                    None => {
2531                        out.push(0);
2532                        out.extend(0u64.to_le_bytes());
2533                    }
2534                }
2535                out.extend(wait_key.to_le_bytes());
2536            }
2537        }
2538        match &frame.wait_request {
2539            None => out.push(0),
2540            Some((operation, payload)) => {
2541                out.push(1);
2542                write_str(out, operation)?;
2543                write_count(out, payload.len(), MAX_STACK_SLOTS)?;
2544                for value in payload {
2545                    write_value(out, value);
2546                }
2547            }
2548        }
2549        write_count(out, frame.targets.len(), MAX_STACK_SLOTS)?;
2550        for target in &frame.targets {
2551            match target {
2552                TargetImage::Register(slot) => {
2553                    out.push(1);
2554                    out.extend(slot.to_le_bytes());
2555                }
2556                TargetImage::Field { table, key } => {
2557                    out.push(2);
2558                    write_value(out, table);
2559                    write_value(out, key);
2560                }
2561            }
2562        }
2563        write_meta(out, frame.meta.as_ref());
2564        match &frame.boundary {
2565            None => out.push(0),
2566            Some(BoundaryImage::Protect {
2567                func,
2568                advance_caller,
2569                handler,
2570            }) => {
2571                out.push(1);
2572                out.extend(func.to_le_bytes());
2573                out.push(u8::from(*advance_caller));
2574                match handler {
2575                    Some(value) => {
2576                        out.push(1);
2577                        write_value(out, value);
2578                    }
2579                    None => out.push(0),
2580                }
2581            }
2582            Some(BoundaryImage::Handler {
2583                slot,
2584                protect,
2585                target,
2586                depth,
2587                fault,
2588            }) => {
2589                out.push(2);
2590                out.extend(slot.to_le_bytes());
2591                out.extend(protect.to_le_bytes());
2592                out.extend(target.to_le_bytes());
2593                out.push(*depth);
2594                out.push(*fault);
2595            }
2596            Some(BoundaryImage::Builtin {
2597                func,
2598                passed,
2599                advance_caller,
2600                task,
2601            }) => {
2602                use crate::heap::Task;
2603                out.push(3);
2604                out.extend(func.to_le_bytes());
2605                out.extend(passed.to_le_bytes());
2606                out.push(u8::from(*advance_caller));
2607                match task {
2608                    Task::HostLoad(work) => {
2609                        out.push(8);
2610                        work.encode(out);
2611                    }
2612                    Task::DoFile => out.push(9),
2613                    Task::ToString => out.push(1),
2614                    Task::Print { next } => {
2615                        out.push(2);
2616                        out.extend(next.to_le_bytes());
2617                    }
2618                    Task::Pairs => out.push(3),
2619                    Task::Ipairs { index } => {
2620                        out.push(4);
2621                        out.extend(index.to_le_bytes());
2622                    }
2623                    Task::Load { source } => {
2624                        out.push(5);
2625                        write_count(out, source.len(), MAX_SOURCE_BYTES)?;
2626                        out.extend_from_slice(source);
2627                    }
2628                    Task::Lib(task) => {
2629                        out.push(6);
2630                        write_lib_task(out, task)?;
2631                    }
2632                    Task::Io(work) => {
2633                        out.push(10);
2634                        work.encode(out);
2635                    }
2636                    Task::Collect {
2637                        result,
2638                        wait,
2639                        ended,
2640                        left,
2641                    } => {
2642                        out.push(7);
2643                        out.push(*result);
2644                        out.push(u8::from(*wait));
2645                        out.push(u8::from(*ended));
2646                        out.extend(left.to_le_bytes());
2647                    }
2648                }
2649            }
2650            Some(BoundaryImage::Native {
2651                func,
2652                passed,
2653                advance_caller,
2654                symbol,
2655                tag,
2656                kept,
2657                sequence,
2658                error,
2659                resuming,
2660                no_yield,
2661            }) => {
2662                // Keep ordinary 0.1.0 native frames byte-compatible. Older
2663                // readers reject tag 8 rather than silently allowing yields.
2664                out.push(if *no_yield { 8 } else { 5 });
2665                out.extend(func.to_le_bytes());
2666                out.extend(passed.to_le_bytes());
2667                out.push(u8::from(*advance_caller));
2668                out.extend(symbol.to_le_bytes());
2669                out.extend(tag.to_le_bytes());
2670                out.extend(kept.to_le_bytes());
2671                out.extend(sequence.unwrap_or(0).to_le_bytes());
2672                out.push(u8::from(*resuming));
2673                match error {
2674                    None => out.push(0),
2675                    Some((class, value)) => {
2676                        out.push(1);
2677                        out.push(*class);
2678                        write_value(out, value);
2679                    }
2680                }
2681            }
2682            Some(BoundaryImage::Hook {
2683                func,
2684                saved_top,
2685                target,
2686                instruction,
2687                after,
2688            }) => {
2689                out.push(6);
2690                out.extend(func.to_le_bytes());
2691                out.extend(saved_top.to_le_bytes());
2692                out.extend(target.to_le_bytes());
2693                write_hook_instruction(out, *instruction)?;
2694                write_hook_after(out, *after);
2695            }
2696            Some(BoundaryImage::HookNative {
2697                func,
2698                passed,
2699                callee,
2700                advance_caller,
2701                phase,
2702                produced,
2703                result,
2704            }) => {
2705                out.push(7);
2706                out.extend(func.to_le_bytes());
2707                out.extend(passed.to_le_bytes());
2708                write_value(out, callee);
2709                out.push(u8::from(*advance_caller));
2710                out.push(*phase);
2711                out.extend(produced.to_le_bytes());
2712                out.extend(result.to_le_bytes());
2713            }
2714            Some(BoundaryImage::Finalizer { func, saved_top }) => {
2715                out.push(4);
2716                out.extend(func.to_le_bytes());
2717                out.extend(saved_top.to_le_bytes());
2718            }
2719        }
2720    }
2721    match &thread.error {
2722        Some((fault, value)) => {
2723            out.push(1);
2724            out.push(*fault);
2725            write_value(out, value);
2726        }
2727        None => out.push(0),
2728    }
2729    match &thread.unwind {
2730        Some(unwind) => {
2731            out.push(1);
2732            write_unwind(out, unwind);
2733        }
2734        None => out.push(0),
2735    }
2736    out.push(u8::from(thread.coroutine));
2737    out.push(u8::from(thread.closing));
2738    write_count(out, thread.tbc.len(), MAX_STACK_SLOTS)?;
2739    for slot in &thread.tbc {
2740        out.extend(slot.to_le_bytes());
2741    }
2742    out.extend(thread.charged_slots.to_le_bytes());
2743    out.extend(thread.charged_held.to_le_bytes());
2744    write_hook(out, thread.hook.as_ref())?;
2745    Ok(())
2746}
2747
2748fn write_unwind(out: &mut Vec<u8>, unwind: &UnwindImage) {
2749    match &unwind.error {
2750        Some((fault, value)) => {
2751            out.push(1);
2752            out.push(*fault);
2753            write_value(out, value);
2754        }
2755        None => out.push(0),
2756    }
2757    match unwind.phase {
2758        crate::heap::UnwindPhase::Raised => out.push(0),
2759        crate::heap::UnwindPhase::Popping { target } => {
2760            out.push(1);
2761            match target {
2762                Some(index) => {
2763                    out.push(1);
2764                    out.extend(index.to_le_bytes());
2765                }
2766                None => {
2767                    out.push(0);
2768                    out.extend(0u32.to_le_bytes());
2769                }
2770            }
2771        }
2772    }
2773}
2774
2775fn read_unwind(input: &mut &[u8]) -> Result<UnwindImage, SnapshotError> {
2776    let error = if read_flag(input)? {
2777        Some((read_fault(input)?, read_value(input)?))
2778    } else {
2779        None
2780    };
2781    let phase = match opcode::read_u8(input)? {
2782        0 => crate::heap::UnwindPhase::Raised,
2783        1 => {
2784            let flag = read_flag(input)?;
2785            let index = opcode::read_u32(input)?;
2786            crate::heap::UnwindPhase::Popping {
2787                target: if flag {
2788                    Some(index)
2789                } else if index == 0 {
2790                    None
2791                } else {
2792                    return Err(SnapshotError::InvalidTag);
2793                },
2794            }
2795        }
2796        _ => return Err(SnapshotError::InvalidTag),
2797    };
2798    Ok(UnwindImage { error, phase })
2799}
2800
2801fn write_meta(out: &mut Vec<u8>, meta: Option<&MetaImage>) {
2802    use crate::heap::{MetaEvent, MetaPhase};
2803    let Some(meta) = meta else {
2804        out.push(0);
2805        return;
2806    };
2807    match &meta.event {
2808        EventImage::Plain(event) => {
2809            let (tag, dst) = match event {
2810                MetaEvent::Store { dst } => (1, *dst),
2811                MetaEvent::NewIndex => (2, 0),
2812                MetaEvent::NewIndexAssign => (3, 0),
2813                MetaEvent::Truth { dst, negate: false } => (4, *dst),
2814                MetaEvent::Truth { dst, negate: true } => (5, *dst),
2815                // Closes are `EventImage::Close`.
2816                MetaEvent::Close => (0, 0),
2817            };
2818            out.push(tag);
2819            out.push(dst);
2820        }
2821        EventImage::Close { from, next } => {
2822            out.push(6);
2823            out.push(0);
2824            out.extend(from.to_le_bytes());
2825            match next {
2826                NextImage::Advance => out.push(1),
2827                NextImage::Return { src, produced } => {
2828                    out.push(2);
2829                    out.extend(src.to_le_bytes());
2830                    out.extend(produced.to_le_bytes());
2831                }
2832                NextImage::Unwind(unwind) => {
2833                    out.push(3);
2834                    write_unwind(out, unwind);
2835                }
2836            }
2837        }
2838    }
2839    out.extend(meta.slot.to_le_bytes());
2840    out.push(meta.nargs);
2841    match meta.phase {
2842        MetaPhase::Running => out.push(0),
2843        MetaPhase::NativePrepared { sequence } => {
2844            out.push(1);
2845            out.extend(sequence.to_le_bytes());
2846        }
2847        MetaPhase::NativeWaiting { sequence, wait_key } => {
2848            out.push(2);
2849            out.push(u8::from(sequence.is_some()));
2850            out.extend(sequence.unwrap_or(0).to_le_bytes());
2851            out.extend(wait_key.to_le_bytes());
2852        }
2853        MetaPhase::Idle => out.push(3),
2854    }
2855}
2856
2857fn read_meta(input: &mut &[u8]) -> Result<Option<MetaImage>, SnapshotError> {
2858    use crate::heap::{MetaEvent, MetaPhase};
2859    let tag = opcode::read_u8(input)?;
2860    if tag == 0 {
2861        return Ok(None);
2862    }
2863    let dst = opcode::read_u8(input)?;
2864    let event = match tag {
2865        1 => EventImage::Plain(MetaEvent::Store { dst }),
2866        2 if dst == 0 => EventImage::Plain(MetaEvent::NewIndex),
2867        3 if dst == 0 => EventImage::Plain(MetaEvent::NewIndexAssign),
2868        4 => EventImage::Plain(MetaEvent::Truth { dst, negate: false }),
2869        5 => EventImage::Plain(MetaEvent::Truth { dst, negate: true }),
2870        6 if dst == 0 => {
2871            let from = opcode::read_u32(input)?;
2872            let next = match opcode::read_u8(input)? {
2873                1 => NextImage::Advance,
2874                2 => NextImage::Return {
2875                    src: opcode::read_u32(input)?,
2876                    produced: opcode::read_u32(input)?,
2877                },
2878                3 => NextImage::Unwind(read_unwind(input)?),
2879                _ => return Err(SnapshotError::InvalidTag),
2880            };
2881            EventImage::Close { from, next }
2882        }
2883        _ => return Err(SnapshotError::InvalidTag),
2884    };
2885    let slot = opcode::read_u32(input)?;
2886    let nargs = opcode::read_u8(input)?;
2887    let phase = match opcode::read_u8(input)? {
2888        0 => MetaPhase::Running,
2889        1 => MetaPhase::NativePrepared {
2890            sequence: opcode::read_u64(input)?,
2891        },
2892        2 => {
2893            let flag = opcode::read_u8(input)?;
2894            let raw = opcode::read_u64(input)?;
2895            let sequence = match flag {
2896                0 if raw == 0 => None,
2897                1 => Some(raw),
2898                _ => return Err(SnapshotError::InvalidTag),
2899            };
2900            MetaPhase::NativeWaiting {
2901                sequence,
2902                wait_key: opcode::read_u64(input)?,
2903            }
2904        }
2905        3 => MetaPhase::Idle,
2906        _ => return Err(SnapshotError::InvalidTag),
2907    };
2908    Ok(Some(MetaImage {
2909        event,
2910        slot,
2911        nargs,
2912        phase,
2913    }))
2914}
2915
2916fn write_str(out: &mut Vec<u8>, text: &str) -> Result<(), SnapshotError> {
2917    write_count(out, text.len(), MAX_STRING_BYTES)?;
2918    out.extend(text.as_bytes());
2919    Ok(())
2920}
2921
2922fn write_value(out: &mut Vec<u8>, value: &EncValue) {
2923    match value {
2924        EncValue::Nil => out.push(0),
2925        EncValue::Bool(bit) => {
2926            out.push(1);
2927            out.push(u8::from(*bit));
2928        }
2929        EncValue::Integer(integer) => {
2930            out.push(2);
2931            out.extend(integer.to_le_bytes());
2932        }
2933        EncValue::Float(bits) => {
2934            out.push(3);
2935            out.extend(bits.to_le_bytes());
2936        }
2937        EncValue::String(id) => {
2938            out.push(4);
2939            out.extend(id.to_le_bytes());
2940        }
2941        EncValue::Table(id) => {
2942            out.push(5);
2943            out.extend(id.to_le_bytes());
2944        }
2945        EncValue::Closure(id) => {
2946            out.push(6);
2947            out.extend(id.to_le_bytes());
2948        }
2949        EncValue::Thread(id) => {
2950            out.push(7);
2951            out.extend(id.to_le_bytes());
2952        }
2953        EncValue::Native(index) => {
2954            out.push(8);
2955            out.extend(index.to_le_bytes());
2956        }
2957        EncValue::NativeClosure(id) => {
2958            out.push(9);
2959            out.extend(id.to_le_bytes());
2960        }
2961        EncValue::Userdata(id) => {
2962            out.push(10);
2963            out.extend(id.to_le_bytes());
2964        }
2965        EncValue::Light(domain, bits) => {
2966            out.push(11);
2967            out.push(*domain as u8);
2968            out.extend(bits.to_le_bytes());
2969        }
2970    }
2971}
2972
2973/// The image of `bytes`, decoded within `limits`: no longer than its
2974/// snapshot bound, no more objects than its object limit, and no more
2975/// decoded structure than the budget (see [`budget`]).
2976pub(crate) fn decode_within(bytes: &[u8], limits: &Limits) -> Result<Image, SnapshotError> {
2977    if bytes.len() as u64 > limits.max_snapshot_bytes {
2978        return Err(SnapshotError::LimitExceeded);
2979    }
2980    if bytes.len() < 4 {
2981        return Err(SnapshotError::Truncated);
2982    }
2983    if &bytes[..4] != MAGIC {
2984        return Err(SnapshotError::BadMagic);
2985    }
2986    if bytes.len() < 6 {
2987        return Err(SnapshotError::Truncated);
2988    }
2989    let version = u16::from_le_bytes([bytes[4], bytes[5]]);
2990    if version != VERSION {
2991        return Err(SnapshotError::BadVersion);
2992    }
2993    if bytes.len() < 10 {
2994        return Err(SnapshotError::Truncated);
2995    }
2996    let (body, crc_bytes) = bytes.split_at(bytes.len() - 4);
2997    let crc = u32::from_le_bytes(crc_bytes.try_into().map_err(|_| SnapshotError::Truncated)?);
2998    if crc32(body) != crc {
2999        return Err(SnapshotError::Checksum);
3000    }
3001    // Magic and schema were checked above; the body resumes after them.
3002    let mut cursor = &body[6..];
3003    parse_after_version(&mut cursor, limits)
3004}
3005
3006fn parse_after_version(input: &mut &[u8], limits: &Limits) -> Result<Image, SnapshotError> {
3007    let length = input.len() as u64;
3008    let bytecode = opcode::read_u16(input)?;
3009    let tables = opcode::read_u16(input)?;
3010    let fuel = opcode::read_u16(input)?;
3011    let gc_revision = opcode::read_u16(input)?;
3012    if bytecode != BYTECODE_REVISION
3013        || tables != TABLES_REVISION
3014        || fuel != FUEL_REVISION
3015        || gc_revision != GC_REVISION
3016    {
3017        return Err(SnapshotError::BadVersion);
3018    }
3019    let effect_domain = opcode::read_u64(input)?;
3020    let next_object_id = opcode::read_u64(input)?;
3021    let next_sequence = opcode::read_u64(input)?;
3022    let fuel_consumed = opcode::read_u64(input)?;
3023    let fuel_flag = opcode::read_u8(input)?;
3024    let fuel_raw = opcode::read_u64(input)?;
3025    let fuel_limit = match fuel_flag {
3026        0 => None,
3027        1 => Some(fuel_raw),
3028        _ => return Err(SnapshotError::InvalidTag),
3029    };
3030    let wait_flag = opcode::read_u8(input)?;
3031    let wait_raw = opcode::read_u64(input)?;
3032    let last_completed_wait = match wait_flag {
3033        0 => None,
3034        1 => Some(wait_raw),
3035        _ => return Err(SnapshotError::InvalidTag),
3036    };
3037    let host_call = read_flag(input)?;
3038    let callback_failed = read_flag(input)?;
3039    let n_completed = checked_count(input, MAX_OBJECTS)?;
3040    let mut completed_waits = Vec::with_capacity(prealloc(n_completed));
3041    for _ in 0..n_completed {
3042        completed_waits.push(opcode::read_u64(input)?);
3043    }
3044    if completed_waits.windows(2).any(|pair| pair[0] >= pair[1])
3045        || completed_waits
3046            .iter()
3047            .any(|key| key & (1 << 63) == 0 || key & !(1 << 63) >= next_sequence)
3048    {
3049        return Err(SnapshotError::InvalidStructure);
3050    }
3051    let trap = opcode::read_u8(input)?;
3052    let _ = trap_from(trap)?;
3053    let max_objects = opcode::read_u32(input)?;
3054    if max_objects == 0 || max_objects > MAX_OBJECTS {
3055        return Err(SnapshotError::LimitExceeded);
3056    }
3057    let max_stack_slots = opcode::read_u32(input)?;
3058    if !crate::runtime::STACK_SLOTS_RANGE.contains(&max_stack_slots) {
3059        return Err(SnapshotError::LimitExceeded);
3060    }
3061    let max_string = opcode::read_u32(input)?;
3062    if !crate::heap::STRING_BYTES_RANGE.contains(&(max_string as usize)) {
3063        return Err(SnapshotError::LimitExceeded);
3064    }
3065    let auto = match opcode::read_u8(input)? {
3066        0 => false,
3067        1 => true,
3068        _ => return Err(SnapshotError::InvalidTag),
3069    };
3070    let mut gc = crate::heap::GcState {
3071        auto,
3072        debt: opcode::read_u64(input)?,
3073        threshold: opcode::read_u64(input)?,
3074        min_debt: opcode::read_u64(input)?,
3075        live: opcode::read_u64(input)?,
3076        collections: opcode::read_u64(input)?,
3077        quota: opcode::read_u64(input)?,
3078        pause: crate::heap::GC_PAUSE,
3079        stepmul: crate::heap::GC_STEPMUL,
3080        stepsize: crate::heap::GC_STEPSIZE,
3081        sched: 0,
3082        owed: 0,
3083        full: None,
3084        prepaid: 0,
3085        work: 0,
3086        cycle_work: 0,
3087        trace: 0,
3088        generational: false,
3089        minormul: crate::heap::GC_MINORMUL,
3090        majormul: crate::heap::GC_MAJORMUL,
3091        major_base: 0,
3092        major_objects: 0,
3093        bad: 0,
3094        minors: 0,
3095        used: 0,
3096    };
3097    if gc.threshold == 0 || gc.min_debt == 0 || gc.quota == 0 {
3098        return Err(SnapshotError::InvalidStructure);
3099    }
3100    // Everything past the header is held to the budget, and the objects
3101    // to the object limit the runtime will have.
3102    let quota = gc.quota.min(limits.max_logical_heap);
3103    let _budget = budget::Scope::set(quota.saturating_mul(4).saturating_add(length));
3104    let object_limit = u64::from(max_objects.min(limits.max_objects))
3105        + u64::from(crate::runtime::finalize_close_objects());
3106    let mut objects = 0u64;
3107    let mut count_objects = |n: usize| {
3108        objects += n as u64;
3109        if objects > object_limit {
3110            return Err(SnapshotError::LimitExceeded);
3111        }
3112        Ok(())
3113    };
3114    let mut rng = [0u64; 4];
3115    for word in &mut rng {
3116        *word = opcode::read_u64(input)?;
3117    }
3118    // xoshiro256** never reaches the all-zero state, and seeding avoids it.
3119    if rng == [0; 4] {
3120        return Err(SnapshotError::InvalidStructure);
3121    }
3122    let library = crate::library::LibraryState {
3123        rng,
3124        entropy: opcode::read_u64(input)?,
3125    };
3126    let mut type_metatables = [0; crate::heap::BASIC_TYPES];
3127    for id in &mut type_metatables {
3128        *id = opcode::read_u64(input)?;
3129    }
3130    let globals = opcode::read_u64(input)?;
3131    let registry = opcode::read_u64(input)?;
3132    let active = opcode::read_u64(input)?;
3133    let entry = opcode::read_u64(input)?;
3134    let mut seen = HashSet::new();
3135    let strings = read_strings(input, &mut seen)?;
3136    count_objects(strings.len())?;
3137    let natives = read_natives(input)?;
3138    let expected = crate::heap::reserved_texts().count();
3139    let n_faults = checked_count(input, expected as u32)?;
3140    if n_faults as usize != expected {
3141        return Err(SnapshotError::InvalidStructure);
3142    }
3143    let mut reserved = Vec::with_capacity(prealloc(n_faults));
3144    for _ in 0..n_faults {
3145        reserved.push(opcode::read_u64(input)?);
3146    }
3147    let protos = {
3148        let by_id: std::collections::HashMap<u64, &[u8]> = strings
3149            .iter()
3150            .map(|(id, bytes)| (*id, bytes.as_slice()))
3151            .collect();
3152        read_protos(input, &mut seen, &by_id)?
3153    };
3154    count_objects(protos.len())?;
3155    let tables = read_tables(input, &mut seen)?;
3156    count_objects(tables.len())?;
3157    let upvalues = read_upvalues(input, &mut seen)?;
3158    count_objects(upvalues.len())?;
3159    let closures = read_closures(input, &mut seen)?;
3160    count_objects(closures.len())?;
3161    let threads = read_threads(input, &mut seen)?;
3162    count_objects(threads.len())?;
3163    let native_closures = read_native_closures(input, &mut seen)?;
3164    count_objects(native_closures.len())?;
3165    let userdata = read_userdata(input, &mut seen)?;
3166    count_objects(userdata.len())?;
3167    let mut lists = [Vec::new(), Vec::new()];
3168    for list in &mut lists {
3169        let count = checked_count(input, MAX_OBJECTS)?;
3170        for _ in 0..count {
3171            list.push(opcode::read_u64(input)?);
3172        }
3173    }
3174    let [registered, pending] = lists;
3175    let finalizers = FinalizersImage {
3176        registered,
3177        pending,
3178        old_until: opcode::read_u32(input)?,
3179        new_from: opcode::read_u32(input)?,
3180        running: read_flag(input)?,
3181        closing: read_flag(input)?,
3182        closed: opcode::read_u8(input)?,
3183        close_closure: opcode::read_u64(input)?,
3184        exit: match opcode::read_u8(input)? {
3185            0 => None,
3186            phase => {
3187                use crate::heap::{ExitPhase, ExitState};
3188                let phase = match phase {
3189                    1 => ExitPhase::Scopes,
3190                    2 => ExitPhase::Finalizers,
3191                    3 => ExitPhase::Terminal,
3192                    _ => return Err(SnapshotError::InvalidTag),
3193                };
3194                let close = read_flag(input)?;
3195                let tag = opcode::read_u8(input)?;
3196                let code = opcode::read_u32(input)? as i32;
3197                let status = match (tag, code) {
3198                    (0, 0) => crate::ExitStatus::Success,
3199                    (1, 0) => crate::ExitStatus::Failure,
3200                    (2, code) => crate::ExitStatus::Code(code),
3201                    _ => return Err(SnapshotError::InvalidTag),
3202                };
3203                Some(ExitState {
3204                    status,
3205                    close,
3206                    phase,
3207                })
3208            }
3209        },
3210    };
3211    let collector = read_collector(input, &mut gc)?;
3212    let iteration_profile = match *input {
3213        [] => crate::IterationProfile::InsertionOrder,
3214        b"ITER\x01" => crate::IterationProfile::Sorted,
3215        _ => return Err(SnapshotError::InvalidStructure),
3216    };
3217    *input = &[];
3218    let image = Image {
3219        iteration_profile,
3220        effect_domain,
3221        next_object_id,
3222        next_sequence,
3223        fuel_consumed,
3224        fuel_limit,
3225        last_completed_wait,
3226        completed_waits,
3227        host_call,
3228        callback_failed,
3229        trap,
3230        max_objects,
3231        max_stack_slots,
3232        max_string,
3233        gc,
3234        library,
3235        type_metatables,
3236        globals,
3237        registry,
3238        active,
3239        entry,
3240        strings,
3241        natives,
3242        reserved,
3243        protos,
3244        tables,
3245        upvalues,
3246        closures,
3247        threads,
3248        native_closures,
3249        userdata,
3250        finalizers,
3251        collector,
3252        index: ImageIndex::default(),
3253    };
3254    validate_graph(&image, &seen)?;
3255    validate_code(&image)?;
3256    Ok(image)
3257}
3258
3259fn code_view<'a>(
3260    proto: &'a ProtoImage,
3261    protos: &std::collections::HashMap<u64, &'a ProtoImage>,
3262) -> Result<check::CodeView<'a>, SnapshotError> {
3263    let children = proto
3264        .children
3265        .iter()
3266        .map(|id| {
3267            protos
3268                .get(id)
3269                .map(|child| child.captures.as_slice())
3270                .ok_or(SnapshotError::DanglingReference)
3271        })
3272        .collect::<Result<Vec<_>, _>>()?;
3273    Ok(check::CodeView {
3274        ops: &proto.ops,
3275        consts: proto.byte_consts.len(),
3276        captures: &proto.captures,
3277        children,
3278        max_reg: proto.max_reg,
3279        params: proto.params,
3280        vararg: proto.vararg,
3281    })
3282}
3283
3284/// Run every restored prototype through the compiler's bytecode check, and
3285/// check each child's captures against every parent that lists it. Runs
3286/// after `validate_graph`, so child ids are known to be prototypes.
3287fn validate_code(image: &Image) -> Result<(), SnapshotError> {
3288    let protos: std::collections::HashMap<u64, &ProtoImage> =
3289        image.protos.iter().map(|proto| (proto.id, proto)).collect();
3290    for proto in &image.protos {
3291        let parent = code_view(proto, &protos)?;
3292        check::check_code(&parent).map_err(|_| SnapshotError::InvalidBytecode)?;
3293        for id in &proto.children {
3294            let child = protos.get(id).ok_or(SnapshotError::DanglingReference)?;
3295            check::check_captures(&child.captures, Some(&parent))
3296                .map_err(|_| SnapshotError::InvalidBytecode)?;
3297        }
3298    }
3299    for closure in &image.closures {
3300        let proto = protos
3301            .get(&closure.proto)
3302            .ok_or(SnapshotError::DanglingReference)?;
3303        if closure.upvalues.len() != proto.captures.len() {
3304            return Err(SnapshotError::InvalidBytecode);
3305        }
3306    }
3307    Ok(())
3308}
3309
3310fn note_id(seen: &mut HashSet<u64>, id: u64) -> Result<(), SnapshotError> {
3311    if id == 0 || !seen.insert(id) {
3312        return Err(if id == 0 {
3313            SnapshotError::InvalidStructure
3314        } else {
3315            SnapshotError::DuplicateObjectId
3316        });
3317    }
3318    Ok(())
3319}
3320
3321/// A count of items, each encoded in at least one byte: refused past
3322/// `max`, past what is left of the input (a count no input backs is a
3323/// lie, found before anything is reserved for it), and past the decode
3324/// budget, which it is charged [`ITEM_BYTES`] an item.
3325fn checked_count(input: &mut &[u8], max: u32) -> Result<u32, SnapshotError> {
3326    let count = opcode::read_u32(input)?;
3327    if count > max {
3328        return Err(SnapshotError::LimitExceeded);
3329    }
3330    if count as usize > input.len() {
3331        return Err(SnapshotError::Truncated);
3332    }
3333    budget::spend(u64::from(count).saturating_mul(ITEM_BYTES))?;
3334    Ok(count)
3335}
3336
3337/// A count of items each encoded in at least `least` bytes, refused when
3338/// the input left cannot hold them.
3339fn checked_proto_count(input: &mut &[u8], max: u32, least: usize) -> Result<u32, SnapshotError> {
3340    let count = checked_count(input, max)?;
3341    let bytes = (count as usize)
3342        .checked_mul(least)
3343        .ok_or(SnapshotError::LimitExceeded)?;
3344    if bytes > input.len() {
3345        return Err(SnapshotError::Truncated);
3346    }
3347    Ok(count)
3348}
3349
3350pub(crate) use budget::Scope as BudgetScope;
3351
3352/// Charge `count` decoded items to the decode budget, for readers outside
3353/// this module (debug information).
3354pub(crate) fn spend_items(count: u64) -> Result<(), SnapshotError> {
3355    budget::spend(count.saturating_mul(ITEM_BYTES))
3356}
3357
3358/// A byte length: refused past `max` and past what is left of the input,
3359/// and charged to the decode budget a byte a byte.
3360fn checked_len(input: &mut &[u8], max: u32) -> Result<u32, SnapshotError> {
3361    let len = opcode::read_u32(input)?;
3362    if len > max {
3363        return Err(SnapshotError::LimitExceeded);
3364    }
3365    if len as usize > input.len() {
3366        return Err(SnapshotError::Truncated);
3367    }
3368    budget::spend(u64::from(len))?;
3369    Ok(len)
3370}
3371
3372/// What the decoder charges its budget for each counted item: about the
3373/// smallest decoded item (a value, an id, an instruction), so the budget
3374/// bounds what the counts make, however small their encoding.
3375const ITEM_BYTES: u64 = 16;
3376
3377/// At most this many items are reserved for a count before they are
3378/// read; past it a list grows as its items decode.
3379const PREALLOC: usize = 1024;
3380
3381fn prealloc(count: u32) -> usize {
3382    (count as usize).min(PREALLOC)
3383}
3384
3385/// The decoder's allocation budget (ADR 0052): bytes of decoded
3386/// structure a snapshot may make before it is validated. Set for one
3387/// decode on this thread, to four times the logical heap the snapshot
3388/// may restore into plus its length; outside a decode it is unbounded.
3389mod budget {
3390    use std::cell::Cell;
3391
3392    use crate::id::SnapshotError;
3393
3394    thread_local! {
3395        static LEFT: Cell<u64> = const { Cell::new(u64::MAX) };
3396    }
3397
3398    pub(super) fn spend(bytes: u64) -> Result<(), SnapshotError> {
3399        LEFT.with(|left| {
3400            let rest = left
3401                .get()
3402                .checked_sub(bytes)
3403                .ok_or(SnapshotError::LimitExceeded)?;
3404            left.set(rest);
3405            Ok(())
3406        })
3407    }
3408
3409    /// The budget for one decode, until the scope is dropped.
3410    pub(crate) struct Scope(u64);
3411
3412    impl Scope {
3413        pub(crate) fn set(bytes: u64) -> Self {
3414            Self(LEFT.with(|left| left.replace(bytes)))
3415        }
3416    }
3417
3418    impl Drop for Scope {
3419        fn drop(&mut self) {
3420            LEFT.with(|left| left.set(self.0));
3421        }
3422    }
3423}
3424
3425/// The native symbol section: unique, bounded symbols.
3426fn read_natives(input: &mut &[u8]) -> Result<Vec<String>, SnapshotError> {
3427    let count = checked_count(input, MAX_OBJECTS)?;
3428    let mut natives = Vec::with_capacity(prealloc(count));
3429    let mut unique = HashSet::new();
3430    for _ in 0..count {
3431        let symbol = read_string(input)?;
3432        if !unique.insert(symbol.clone()) {
3433            return Err(SnapshotError::InvalidStructure);
3434        }
3435        natives.push(symbol);
3436    }
3437    Ok(natives)
3438}
3439
3440fn read_strings(
3441    input: &mut &[u8],
3442    seen: &mut HashSet<u64>,
3443) -> Result<Vec<(u64, Vec<u8>)>, SnapshotError> {
3444    let count = checked_count(input, MAX_OBJECTS)?;
3445    let mut out = Vec::with_capacity(prealloc(count));
3446    for _ in 0..count {
3447        let id = opcode::read_u64(input)?;
3448        note_id(seen, id)?;
3449        let len = checked_len(input, MAX_STRING_BYTES)?;
3450        if input.len() < len as usize {
3451            return Err(SnapshotError::Truncated);
3452        }
3453        let bytes = input[..len as usize].to_vec();
3454        *input = &input[len as usize..];
3455        out.push((id, bytes));
3456    }
3457    Ok(out)
3458}
3459
3460fn read_protos(
3461    input: &mut &[u8],
3462    seen: &mut HashSet<u64>,
3463    strings: &std::collections::HashMap<u64, &[u8]>,
3464) -> Result<Vec<ProtoImage>, SnapshotError> {
3465    let count = checked_proto_count(input, MAX_OBJECTS, 36)?;
3466    let mut out = Vec::with_capacity(prealloc(count));
3467    // Each constant is its own string object (ADR 0020). Refusing a second
3468    // reference also bounds the bytes copied below by the string section.
3469    let mut constants = HashSet::new();
3470    for _ in 0..count {
3471        let id = opcode::read_u64(input)?;
3472        note_id(seen, id)?;
3473        let max_reg = opcode::read_u8(input)?;
3474        let params = opcode::read_u8(input)?;
3475        let vararg = match opcode::read_u8(input)? {
3476            0 => false,
3477            1 => true,
3478            _ => return Err(SnapshotError::InvalidTag),
3479        };
3480        let n_ops = checked_proto_count(input, MAX_INSTRUCTIONS, 1)?;
3481        let mut ops = Vec::with_capacity(prealloc(n_ops));
3482        for _ in 0..n_ops {
3483            ops.push(Op::decode(input)?);
3484        }
3485        let n_consts = checked_proto_count(input, MAX_CONSTS, 8)?;
3486        let mut const_ids = Vec::with_capacity(prealloc(n_consts));
3487        let mut byte_consts = Vec::with_capacity(prealloc(n_consts));
3488        for _ in 0..n_consts {
3489            let id = opcode::read_u64(input)?;
3490            let bytes = strings.get(&id).ok_or(SnapshotError::DanglingReference)?;
3491            if !constants.insert(id) {
3492                return Err(SnapshotError::InvalidStructure);
3493            }
3494            const_ids.push(id);
3495            byte_consts.push(bytes.to_vec());
3496        }
3497        let n_caps = checked_proto_count(input, MAX_UPVALUES, 2)?;
3498        let mut captures = Vec::with_capacity(prealloc(n_caps));
3499        for _ in 0..n_caps {
3500            captures.push(opcode::decode_capture(input)?);
3501        }
3502        let n_children = checked_proto_count(input, MAX_PROTOS, 8)?;
3503        let mut children = Vec::with_capacity(prealloc(n_children));
3504        for _ in 0..n_children {
3505            children.push(opcode::read_u64(input)?);
3506        }
3507        let source = opcode::read_u64(input)?;
3508        if source != 0 && !strings.contains_key(&source) {
3509            return Err(SnapshotError::DanglingReference);
3510        }
3511        let debug = match opcode::read_u8(input)? {
3512            0 => None,
3513            1 => Some(Box::new(crate::debuginfo::DebugInfo::decode(
3514                input,
3515                ops.len(),
3516                captures.len(),
3517                max_reg,
3518            )?)),
3519            _ => return Err(SnapshotError::InvalidTag),
3520        };
3521        out.push(ProtoImage {
3522            id,
3523            max_reg,
3524            params,
3525            vararg,
3526            ops,
3527            const_ids,
3528            byte_consts,
3529            captures,
3530            children,
3531            source,
3532            debug,
3533        });
3534    }
3535    Ok(out)
3536}
3537
3538fn read_tables(
3539    input: &mut &[u8],
3540    seen: &mut HashSet<u64>,
3541) -> Result<Vec<TableImage>, SnapshotError> {
3542    let count = checked_count(input, MAX_OBJECTS)?;
3543    let mut out = Vec::with_capacity(prealloc(count));
3544    for _ in 0..count {
3545        let id = opcode::read_u64(input)?;
3546        note_id(seen, id)?;
3547        let metatable = opcode::read_u64(input)?;
3548        let live = checked_count(input, MAX_TABLE_ENTRIES)?;
3549        let dead = checked_count(input, MAX_TABLE_ENTRIES)?;
3550        let total = live
3551            .checked_add(dead)
3552            .filter(|total| *total <= MAX_TABLE_ENTRIES)
3553            .ok_or(SnapshotError::LimitExceeded)?;
3554        let mut slots = Vec::with_capacity(prealloc(total));
3555        let mut seen_live = 0u32;
3556        let mut seen_dead = 0u32;
3557        for index in 0..total {
3558            let ordinal = opcode::read_u32(input)?;
3559            if ordinal != index {
3560                return Err(SnapshotError::InvalidStructure);
3561            }
3562            let body = match opcode::read_u8(input)? {
3563                1 => {
3564                    seen_live += 1;
3565                    SlotBody::Live {
3566                        key: read_value(input)?,
3567                        value: read_value(input)?,
3568                    }
3569                }
3570                2 => {
3571                    seen_dead += 1;
3572                    SlotBody::Dead(read_dead_key(input)?)
3573                }
3574                _ => return Err(SnapshotError::InvalidTag),
3575            };
3576            slots.push(SlotImage { ordinal, body });
3577        }
3578        if seen_live != live || seen_dead != dead {
3579            return Err(SnapshotError::InvalidStructure);
3580        }
3581        out.push(TableImage {
3582            id,
3583            metatable,
3584            slots,
3585        });
3586    }
3587    Ok(out)
3588}
3589
3590fn read_upvalues(
3591    input: &mut &[u8],
3592    seen: &mut HashSet<u64>,
3593) -> Result<Vec<UpImage>, SnapshotError> {
3594    let count = checked_count(input, MAX_OBJECTS)?;
3595    let mut out = Vec::with_capacity(prealloc(count));
3596    for _ in 0..count {
3597        let id = opcode::read_u64(input)?;
3598        note_id(seen, id)?;
3599        let state = match opcode::read_u8(input)? {
3600            1 => UpImageState::Closed(read_value(input)?),
3601            2 => UpImageState::Open {
3602                thread: opcode::read_u64(input)?,
3603                slot: opcode::read_u32(input)?,
3604            },
3605            _ => return Err(SnapshotError::InvalidTag),
3606        };
3607        out.push(UpImage { id, state });
3608    }
3609    Ok(out)
3610}
3611
3612fn read_closures(
3613    input: &mut &[u8],
3614    seen: &mut HashSet<u64>,
3615) -> Result<Vec<ClosureImage>, SnapshotError> {
3616    let count = checked_count(input, MAX_OBJECTS)?;
3617    let mut out = Vec::with_capacity(prealloc(count));
3618    for _ in 0..count {
3619        let id = opcode::read_u64(input)?;
3620        note_id(seen, id)?;
3621        let proto = opcode::read_u64(input)?;
3622        let n = checked_count(input, MAX_OBJECTS)?;
3623        let mut upvalues = Vec::with_capacity(prealloc(n));
3624        for _ in 0..n {
3625            upvalues.push(opcode::read_u64(input)?);
3626        }
3627        out.push(ClosureImage {
3628            id,
3629            proto,
3630            upvalues,
3631        });
3632    }
3633    Ok(out)
3634}
3635
3636fn read_native_closures(
3637    input: &mut &[u8],
3638    seen: &mut HashSet<u64>,
3639) -> Result<Vec<NativeClosureImage>, SnapshotError> {
3640    let count = checked_count(input, MAX_OBJECTS)?;
3641    let mut out = Vec::with_capacity(prealloc(count));
3642    for _ in 0..count {
3643        let id = opcode::read_u64(input)?;
3644        note_id(seen, id)?;
3645        let native = opcode::read_u32(input)?;
3646        let n = checked_count(input, MAX_CLOSURE_VALUES)?;
3647        let mut values = Vec::with_capacity(prealloc(n));
3648        for _ in 0..n {
3649            values.push(read_value(input)?);
3650        }
3651        let n = checked_count(input, MAX_CLOSURE_VALUES)?;
3652        let mut state = Vec::with_capacity(prealloc(n));
3653        for _ in 0..n {
3654            state.push(opcode::read_i64(input)?);
3655        }
3656        out.push(NativeClosureImage {
3657            id,
3658            native,
3659            values,
3660            state,
3661        });
3662    }
3663    Ok(out)
3664}
3665
3666fn read_bytes(input: &mut &[u8], max: u32) -> Result<Vec<u8>, SnapshotError> {
3667    let len = checked_len(input, max)? as usize;
3668    if input.len() < len {
3669        return Err(SnapshotError::Truncated);
3670    }
3671    let bytes = input[..len].to_vec();
3672    *input = &input[len..];
3673    Ok(bytes)
3674}
3675
3676fn read_userdata(
3677    input: &mut &[u8],
3678    seen: &mut HashSet<u64>,
3679) -> Result<Vec<UserdataImage>, SnapshotError> {
3680    let count = checked_count(input, MAX_OBJECTS)?;
3681    let mut out = Vec::with_capacity(prealloc(count));
3682    for _ in 0..count {
3683        let id = opcode::read_u64(input)?;
3684        note_id(seen, id)?;
3685        let metatable = opcode::read_u64(input)?;
3686        let n = checked_count(input, MAX_USER_VALUES)?;
3687        // Each value takes at least a byte: a count past what is left is
3688        // refused before anything is reserved for it.
3689        if n as usize > input.len() {
3690            return Err(SnapshotError::Truncated);
3691        }
3692        let mut user_values = Vec::with_capacity(prealloc(n));
3693        for _ in 0..n {
3694            user_values.push(read_value(input)?);
3695        }
3696        let payload = match opcode::read_u8(input)? {
3697            4 => PayloadImage::File(crate::iolib::FileState::decode(input)?),
3698            1 => PayloadImage::Bytes(read_bytes(input, MAX_USERDATA_BYTES)?),
3699            2 => PayloadImage::Host {
3700                symbol: read_string(input)?,
3701                bytes: read_bytes(input, MAX_USERDATA_BYTES)?,
3702            },
3703            3 => PayloadImage::Rebind {
3704                symbol: read_string(input)?,
3705                key: read_bytes(input, crate::MAX_REBIND_KEY as u32)?,
3706            },
3707            _ => return Err(SnapshotError::InvalidTag),
3708        };
3709        let charge = opcode::read_u64(input)?;
3710        out.push(UserdataImage {
3711            id,
3712            metatable,
3713            user_values,
3714            payload,
3715            charge,
3716        });
3717    }
3718    Ok(out)
3719}
3720
3721fn read_threads(
3722    input: &mut &[u8],
3723    seen: &mut HashSet<u64>,
3724) -> Result<Vec<ThreadImage>, SnapshotError> {
3725    let count = checked_count(input, MAX_OBJECTS)?;
3726    let mut out = Vec::with_capacity(prealloc(count));
3727    for _ in 0..count {
3728        let id = opcode::read_u64(input)?;
3729        note_id(seen, id)?;
3730        let status = opcode::read_u8(input)?;
3731        if Status::from_u8(status).is_none() {
3732            return Err(SnapshotError::InvalidTag);
3733        }
3734        let resumed_by = opcode::read_u64(input)?;
3735        let top = opcode::read_u32(input)?;
3736        let n_stack = checked_count(input, MAX_STACK_SLOTS)?;
3737        let mut stack = Vec::with_capacity(prealloc(n_stack));
3738        for _ in 0..n_stack {
3739            stack.push(read_value(input)?);
3740        }
3741        let n_results = checked_count(input, MAX_STACK_SLOTS)?;
3742        let mut results = Vec::with_capacity(prealloc(n_results));
3743        for _ in 0..n_results {
3744            results.push(read_value(input)?);
3745        }
3746        let n_frames = checked_count(input, MAX_FRAMES)?;
3747        let mut frames = Vec::with_capacity(prealloc(n_frames));
3748        for _ in 0..n_frames {
3749            frames.push(read_frame(input)?);
3750        }
3751        let error = if read_flag(input)? {
3752            Some((read_fault(input)?, read_value(input)?))
3753        } else {
3754            None
3755        };
3756        let unwind = if read_flag(input)? {
3757            Some(read_unwind(input)?)
3758        } else {
3759            None
3760        };
3761        let coroutine = read_flag(input)?;
3762        let closing = read_flag(input)?;
3763        let n_tbc = checked_count(input, MAX_STACK_SLOTS)?;
3764        let mut tbc = Vec::with_capacity(prealloc(n_tbc));
3765        for _ in 0..n_tbc {
3766            tbc.push(opcode::read_u32(input)?);
3767        }
3768        let charged_slots = opcode::read_u32(input)?;
3769        let charged_held = opcode::read_u64(input)?;
3770        let hook = read_hook(input)?;
3771        out.push(ThreadImage {
3772            id,
3773            status,
3774            resumed_by,
3775            top,
3776            stack,
3777            results,
3778            frames,
3779            error,
3780            unwind,
3781            coroutine,
3782            closing,
3783            tbc,
3784            charged_slots,
3785            charged_held,
3786            hook,
3787        });
3788    }
3789    Ok(out)
3790}
3791
3792fn read_frame(input: &mut &[u8]) -> Result<FrameImage, SnapshotError> {
3793    let closure = opcode::read_u64(input)?;
3794    let pc = opcode::read_u32(input)?;
3795    let base = opcode::read_u32(input)?;
3796    let limit = opcode::read_u32(input)?;
3797    let nresults = opcode::read_u8(input)?;
3798    let vararg_len = opcode::read_u32(input)?;
3799    let tail = match opcode::read_u8(input)? {
3800        0 => false,
3801        1 => true,
3802        _ => return Err(SnapshotError::InvalidTag),
3803    };
3804    let return_hook = read_flag(input)?;
3805    let pending = match opcode::read_u8(input)? {
3806        0 => PendingImage::None,
3807        1 => PendingImage::Prepared {
3808            sequence: opcode::read_u64(input)?,
3809            symbol: read_string(input)?,
3810            arg: opcode::read_i64(input)?,
3811            dest: opcode::read_u8(input)?,
3812        },
3813        2 => PendingImage::Waiting {
3814            sequence: opcode::read_u64(input)?,
3815            symbol: read_string(input)?,
3816            arg: opcode::read_i64(input)?,
3817            dest: opcode::read_u8(input)?,
3818            wait_key: opcode::read_u64(input)?,
3819        },
3820        3 => PendingImage::Resuming {
3821            child: opcode::read_u64(input)?,
3822            dest: opcode::read_u8(input)?,
3823            nresults: opcode::read_u8(input)?,
3824        },
3825        4 => PendingImage::Assigning {
3826            src: opcode::read_u32(input)?,
3827            nvalues: opcode::read_u16(input)?,
3828            next: opcode::read_u16(input)?,
3829        },
3830        5 => PendingImage::NativePrepared {
3831            sequence: opcode::read_u64(input)?,
3832        },
3833        8 => PendingImage::Capability {
3834            sequence: opcode::read_u64(input)?,
3835            wait_key: opcode::read_u64(input)?,
3836            completed: read_flag(input)?,
3837        },
3838        7 => PendingImage::Deferred,
3839        6 => {
3840            let flag = opcode::read_u8(input)?;
3841            let raw = opcode::read_u64(input)?;
3842            let sequence = match flag {
3843                0 if raw == 0 => None,
3844                1 => Some(raw),
3845                _ => return Err(SnapshotError::InvalidTag),
3846            };
3847            PendingImage::NativeWaiting {
3848                sequence,
3849                wait_key: opcode::read_u64(input)?,
3850            }
3851        }
3852        _ => return Err(SnapshotError::InvalidTag),
3853    };
3854    let wait_request = if read_flag(input)? {
3855        let operation = read_string(input)?;
3856        if operation.len() > 4096 {
3857            return Err(SnapshotError::LimitExceeded);
3858        }
3859        let count = checked_count(input, MAX_STACK_SLOTS)?;
3860        let mut payload = Vec::with_capacity(prealloc(count));
3861        for _ in 0..count {
3862            payload.push(read_value(input)?);
3863        }
3864        Some((operation, payload))
3865    } else {
3866        None
3867    };
3868    let n_targets = checked_count(input, MAX_STACK_SLOTS)?;
3869    let mut targets = Vec::with_capacity(prealloc(n_targets));
3870    for _ in 0..n_targets {
3871        targets.push(match opcode::read_u8(input)? {
3872            1 => TargetImage::Register(opcode::read_u32(input)?),
3873            2 => TargetImage::Field {
3874                table: read_value(input)?,
3875                key: read_value(input)?,
3876            },
3877            _ => return Err(SnapshotError::InvalidTag),
3878        });
3879    }
3880    let meta = read_meta(input)?;
3881    let boundary = match opcode::read_u8(input)? {
3882        0 => None,
3883        1 => {
3884            let func = opcode::read_u32(input)?;
3885            let advance_caller = read_flag(input)?;
3886            let handler = if read_flag(input)? {
3887                Some(read_value(input)?)
3888            } else {
3889                None
3890            };
3891            Some(BoundaryImage::Protect {
3892                func,
3893                advance_caller,
3894                handler,
3895            })
3896        }
3897        2 => Some(BoundaryImage::Handler {
3898            slot: opcode::read_u32(input)?,
3899            protect: opcode::read_u32(input)?,
3900            target: opcode::read_u32(input)?,
3901            depth: opcode::read_u8(input)?,
3902            fault: read_fault(input)?,
3903        }),
3904        3 => {
3905            use crate::heap::Task;
3906            let func = opcode::read_u32(input)?;
3907            let passed = opcode::read_u32(input)?;
3908            let advance_caller = read_flag(input)?;
3909            let task = match opcode::read_u8(input)? {
3910                8 => Task::HostLoad(Box::new(crate::runtime::hostload::HostLoad::decode(input)?)),
3911                9 => Task::DoFile,
3912                1 => Task::ToString,
3913                2 => Task::Print {
3914                    next: opcode::read_u32(input)?,
3915                },
3916                3 => Task::Pairs,
3917                4 => Task::Ipairs {
3918                    index: opcode::read_i64(input)?,
3919                },
3920                5 => {
3921                    let len = checked_len(input, MAX_SOURCE_BYTES)? as usize;
3922                    if input.len() < len {
3923                        return Err(SnapshotError::Truncated);
3924                    }
3925                    let (source, rest) = input.split_at(len);
3926                    *input = rest;
3927                    Task::Load {
3928                        source: source.to_vec(),
3929                    }
3930                }
3931                6 => Task::Lib(Box::new(read_lib_task(input)?)),
3932                10 => Task::Io(Box::new(crate::iolib::IoWork::decode(input)?)),
3933                7 => Task::Collect {
3934                    result: match opcode::read_u8(input)? {
3935                        result @ 0..=4 => result,
3936                        _ => return Err(SnapshotError::InvalidTag),
3937                    },
3938                    wait: read_flag(input)?,
3939                    ended: read_flag(input)?,
3940                    left: opcode::read_u32(input)?,
3941                },
3942                _ => return Err(SnapshotError::InvalidTag),
3943            };
3944            Some(BoundaryImage::Builtin {
3945                func,
3946                passed,
3947                advance_caller,
3948                task,
3949            })
3950        }
3951        boundary_tag @ (5 | 8) => {
3952            let func = opcode::read_u32(input)?;
3953            let passed = opcode::read_u32(input)?;
3954            let advance_caller = read_flag(input)?;
3955            let symbol = opcode::read_u32(input)?;
3956            let tag = opcode::read_u32(input)?;
3957            let kept = opcode::read_u32(input)?;
3958            let sequence = match opcode::read_u64(input)? {
3959                0 => None,
3960                sequence => Some(sequence),
3961            };
3962            let resuming = read_flag(input)?;
3963            let error = if read_flag(input)? {
3964                Some((read_fault(input)?, read_value(input)?))
3965            } else {
3966                None
3967            };
3968            Some(BoundaryImage::Native {
3969                func,
3970                passed,
3971                advance_caller,
3972                symbol,
3973                tag,
3974                kept,
3975                sequence,
3976                error,
3977                resuming,
3978                no_yield: boundary_tag == 8,
3979            })
3980        }
3981        6 => Some(BoundaryImage::Hook {
3982            func: opcode::read_u32(input)?,
3983            saved_top: opcode::read_u32(input)?,
3984            target: opcode::read_u32(input)?,
3985            instruction: read_hook_instruction(input)?,
3986            after: read_hook_after(input)?,
3987        }),
3988        7 => Some(BoundaryImage::HookNative {
3989            func: opcode::read_u32(input)?,
3990            passed: opcode::read_u32(input)?,
3991            callee: read_value(input)?,
3992            advance_caller: read_flag(input)?,
3993            phase: opcode::read_u8(input)?,
3994            produced: opcode::read_u32(input)?,
3995            result: opcode::read_u32(input)?,
3996        }),
3997        4 => Some(BoundaryImage::Finalizer {
3998            func: opcode::read_u32(input)?,
3999            saved_top: opcode::read_u32(input)?,
4000        }),
4001        _ => return Err(SnapshotError::InvalidTag),
4002    };
4003    Ok(FrameImage {
4004        closure,
4005        pc,
4006        base,
4007        limit,
4008        nresults,
4009        vararg_len,
4010        tail,
4011        return_hook,
4012        pending,
4013        wait_request,
4014        targets,
4015        meta,
4016        boundary,
4017    })
4018}
4019
4020/// A library task (ADR 0033): its wait, then its work.
4021fn write_lib_task(out: &mut Vec<u8>, task: &crate::library::LibTask) -> Result<(), SnapshotError> {
4022    use crate::library::{Wait, Work};
4023    match task.wait {
4024        Wait::Nothing => out.push(0),
4025        Wait::Get { into } => {
4026            out.push(1);
4027            out.extend(into.to_le_bytes());
4028        }
4029        Wait::Set => out.push(2),
4030        Wait::Len => out.push(3),
4031        Wait::Truth => out.push(4),
4032        Wait::Pair { into } => {
4033            out.push(5);
4034            out.extend(into.to_le_bytes());
4035        }
4036    }
4037    let stage = |out: &mut Vec<u8>, stage: crate::library::Stage| out.push(stage as u8);
4038    let ints = |out: &mut Vec<u8>, values: &[i64]| {
4039        for value in values {
4040            out.extend(value.to_le_bytes());
4041        }
4042    };
4043    match &task.work {
4044        Work::Extreme { max, best, next } => {
4045            out.push(1);
4046            out.push(u8::from(*max));
4047            out.extend(best.to_le_bytes());
4048            out.extend(next.to_le_bytes());
4049        }
4050        Work::Insert { stage: at, pos, i } => {
4051            out.push(2);
4052            stage(out, *at);
4053            ints(out, &[*pos, *i]);
4054        }
4055        Work::Remove {
4056            stage: at,
4057            size,
4058            pos,
4059        } => {
4060            out.push(3);
4061            stage(out, *at);
4062            ints(out, &[*size, *pos]);
4063        }
4064        Work::Move {
4065            stage: at,
4066            f,
4067            t,
4068            n,
4069            i,
4070            backward,
4071        } => {
4072            out.push(4);
4073            stage(out, *at);
4074            ints(out, &[*f, *t, *n, *i]);
4075            out.push(u8::from(*backward));
4076        }
4077        Work::Concat {
4078            stage: at,
4079            i,
4080            last,
4081            text,
4082        } => {
4083            out.push(5);
4084            stage(out, *at);
4085            ints(out, &[*i, *last]);
4086            write_count(out, text.len(), MAX_STRING_BYTES)?;
4087            out.extend_from_slice(text);
4088        }
4089        Work::Pack { stage: at, next } => {
4090            out.push(6);
4091            stage(out, *at);
4092            out.extend(next.to_le_bytes());
4093        }
4094        Work::Unpack {
4095            stage: at,
4096            first,
4097            count,
4098            got,
4099        } => {
4100            out.push(7);
4101            stage(out, *at);
4102            ints(out, &[*first]);
4103            out.extend(count.to_le_bytes());
4104            out.extend(got.to_le_bytes());
4105        }
4106        Work::Sort(sort) => {
4107            out.push(8);
4108            out.push(sort.step as u8);
4109            for value in [sort.n, sort.lo, sort.up, sort.p, sort.i, sort.j, sort.rnd] {
4110                out.extend(value.to_le_bytes());
4111            }
4112            write_count(
4113                out,
4114                sort.pending.len(),
4115                crate::library::MAX_SORT_PENDING as u32,
4116            )?;
4117            for range in &sort.pending {
4118                for value in [range.lo, range.up, range.smaller, range.rnd] {
4119                    out.extend(value.to_le_bytes());
4120                }
4121            }
4122        }
4123        Work::Str(work) => {
4124            out.push(9);
4125            work.encode(out);
4126        }
4127        Work::Package(work) => {
4128            out.push(10);
4129            work.encode(out);
4130        }
4131        Work::Debug(work) => {
4132            out.push(11);
4133            work.encode(out);
4134        }
4135        Work::Utf8(work) => {
4136            out.push(12);
4137            work.encode(out);
4138        }
4139        Work::Os(work) => {
4140            out.push(13);
4141            work.encode(out);
4142        }
4143    }
4144    Ok(())
4145}
4146
4147fn read_lib_task(input: &mut &[u8]) -> Result<crate::library::LibTask, SnapshotError> {
4148    use crate::library::{LibTask, SortRange, SortState, Stage, Wait, Work};
4149    let wait = match opcode::read_u8(input)? {
4150        0 => Wait::Nothing,
4151        1 => Wait::Get {
4152            into: opcode::read_u32(input)?,
4153        },
4154        2 => Wait::Set,
4155        3 => Wait::Len,
4156        4 => Wait::Truth,
4157        5 => Wait::Pair {
4158            into: opcode::read_u32(input)?,
4159        },
4160        _ => return Err(SnapshotError::InvalidTag),
4161    };
4162    // Every `Stage`, in tag order.
4163    const STAGES: [Stage; 8] = [
4164        Stage::Start,
4165        Stage::Length,
4166        Stage::First,
4167        Stage::Read,
4168        Stage::Write,
4169        Stage::Last,
4170        Stage::Equal,
4171        Stage::Done,
4172    ];
4173    let stage = |input: &mut &[u8]| -> Result<Stage, SnapshotError> {
4174        let tag = usize::from(opcode::read_u8(input)?);
4175        STAGES
4176            .get(tag)
4177            .copied()
4178            .filter(|stage| *stage as usize == tag)
4179            .ok_or(SnapshotError::InvalidTag)
4180    };
4181    let int = |input: &mut &[u8]| opcode::read_i64(input);
4182    let work = match opcode::read_u8(input)? {
4183        1 => Work::Extreme {
4184            max: read_flag(input)?,
4185            best: opcode::read_u32(input)?,
4186            next: opcode::read_u32(input)?,
4187        },
4188        2 => Work::Insert {
4189            stage: stage(input)?,
4190            pos: int(input)?,
4191            i: int(input)?,
4192        },
4193        3 => Work::Remove {
4194            stage: stage(input)?,
4195            size: int(input)?,
4196            pos: int(input)?,
4197        },
4198        4 => Work::Move {
4199            stage: stage(input)?,
4200            f: int(input)?,
4201            t: int(input)?,
4202            n: int(input)?,
4203            i: int(input)?,
4204            backward: read_flag(input)?,
4205        },
4206        5 => {
4207            let (at, i, last) = (stage(input)?, int(input)?, int(input)?);
4208            let len = checked_len(input, MAX_STRING_BYTES)? as usize;
4209            if input.len() < len {
4210                return Err(SnapshotError::Truncated);
4211            }
4212            let (text, rest) = input.split_at(len);
4213            *input = rest;
4214            Work::Concat {
4215                stage: at,
4216                i,
4217                last,
4218                text: text.to_vec(),
4219            }
4220        }
4221        6 => Work::Pack {
4222            stage: stage(input)?,
4223            next: opcode::read_u32(input)?,
4224        },
4225        7 => Work::Unpack {
4226            stage: stage(input)?,
4227            first: int(input)?,
4228            count: opcode::read_u32(input)?,
4229            got: opcode::read_u32(input)?,
4230        },
4231        8 => {
4232            let step = SORT_STEPS
4233                .get(usize::from(opcode::read_u8(input)?))
4234                .copied()
4235                .ok_or(SnapshotError::InvalidTag)?;
4236            let mut values = [0u32; 7];
4237            for value in &mut values {
4238                *value = opcode::read_u32(input)?;
4239            }
4240            let [n, lo, up, p, i, j, rnd] = values;
4241            let count = checked_count(input, crate::library::MAX_SORT_PENDING as u32)?;
4242            let mut pending = Vec::with_capacity(prealloc(count));
4243            for _ in 0..count {
4244                pending.push(SortRange {
4245                    lo: opcode::read_u32(input)?,
4246                    up: opcode::read_u32(input)?,
4247                    smaller: opcode::read_u32(input)?,
4248                    rnd: opcode::read_u32(input)?,
4249                });
4250            }
4251            Work::Sort(Box::new(SortState {
4252                step,
4253                n,
4254                lo,
4255                up,
4256                p,
4257                i,
4258                j,
4259                rnd,
4260                pending,
4261            }))
4262        }
4263        9 => Work::Str(Box::new(crate::strlib::StrWork::decode(input)?)),
4264        10 => Work::Package(Box::new(crate::package::PackageWork::decode(input)?)),
4265        11 => Work::Debug(Box::new(crate::debuglib::DebugWork::decode(input)?)),
4266        12 => Work::Utf8(Box::new(crate::utf8lib::Utf8Work::decode(input)?)),
4267        13 => Work::Os(Box::new(crate::oslib::OsWork::decode(input)?)),
4268        _ => return Err(SnapshotError::InvalidTag),
4269    };
4270    Ok(LibTask { work, wait })
4271}
4272
4273/// Every `SortStep`, in tag order.
4274const SORT_STEPS: [crate::library::SortStep; 28] = {
4275    use crate::library::SortStep::*;
4276    [
4277        Length,
4278        Range,
4279        GetLo,
4280        GetUp,
4281        UpLessLo,
4282        SetLoUp,
4283        SetUpLo,
4284        GetP,
4285        GetLo2,
4286        PLessLo,
4287        SetPLo,
4288        SetLoP,
4289        GetUp2,
4290        UpLessP,
4291        SetPUp,
4292        SetUpP,
4293        GetPivot,
4294        GetUpMinus1,
4295        SetPToUpMinus1,
4296        SetUpMinus1ToPivot,
4297        GetI,
4298        ILessPivot,
4299        GetJ,
4300        PivotLessJ,
4301        SetIJ,
4302        SetJI,
4303        SetUpMinus1I,
4304        SetIPivot,
4305    ]
4306};
4307
4308/// A library task restore accepts (ADR 0033): its counters within the
4309/// function's arguments and the stack, a wait its scratch can take, and
4310/// never a task that has not started, since a frame exists only after the
4311/// first step.
4312fn lib_task_fits(task: &crate::library::LibTask, passed: u32) -> bool {
4313    use crate::library::{MAX_SORT_PENDING, SortStep, Stage, Wait, Work};
4314    let wait_fits = match task.wait {
4315        Wait::Get { into } => into < task.work.scratch(),
4316        Wait::Pair { into } => into.saturating_add(1) < task.work.scratch(),
4317        _ => true,
4318    };
4319    let started = |stage: Stage| stage != Stage::Start;
4320    let work_fits = match &task.work {
4321        Work::Extreme { best, next, .. } => passed >= 1 && best < next && *next <= passed,
4322        Work::Insert { stage, .. } | Work::Remove { stage, .. } => started(*stage) && passed >= 1,
4323        Work::Move { stage, n, i, .. } => started(*stage) && *n >= 0 && *i >= -1 && *i <= *n,
4324        Work::Concat { stage, text, .. } => {
4325            started(*stage) && text.len() <= crate::heap::STRING_CEILING
4326        }
4327        Work::Pack { stage, next } => started(*stage) && *next <= passed,
4328        Work::Unpack {
4329            stage, count, got, ..
4330        } => started(*stage) && got <= count && *count <= MAX_STACK_SLOTS,
4331        Work::Sort(sort) => {
4332            let bound = sort.n.saturating_add(1);
4333            sort.n < i32::MAX as u32
4334                && sort.pending.len() <= MAX_SORT_PENDING
4335                && [sort.lo, sort.up, sort.p, sort.i, sort.j]
4336                    .iter()
4337                    .all(|index| *index <= bound)
4338                && sort
4339                    .pending
4340                    .iter()
4341                    .all(|range| range.lo <= bound && range.up <= bound)
4342                && (sort.step != SortStep::Length || sort.n == 0)
4343        }
4344        // Checked against its arguments' strings in `string_work_fits`.
4345        Work::Str(_) | Work::Utf8(_) | Work::Os(_) | Work::Package(_) | Work::Debug(_) => true,
4346    };
4347    wait_fits && work_fits
4348}
4349
4350fn read_flag(input: &mut &[u8]) -> Result<bool, SnapshotError> {
4351    match opcode::read_u8(input)? {
4352        0 => Ok(false),
4353        1 => Ok(true),
4354        _ => Err(SnapshotError::InvalidTag),
4355    }
4356}
4357
4358fn read_fault(input: &mut &[u8]) -> Result<u8, SnapshotError> {
4359    let tag = opcode::read_u8(input)?;
4360    crate::id::LuaFault::from_tag(tag).ok_or(SnapshotError::InvalidTag)?;
4361    Ok(tag)
4362}
4363
4364fn read_string(input: &mut &[u8]) -> Result<String, SnapshotError> {
4365    let len = checked_len(input, MAX_STRING_BYTES)?;
4366    if input.len() < len as usize {
4367        return Err(SnapshotError::Truncated);
4368    }
4369    let bytes = input[..len as usize].to_vec();
4370    *input = &input[len as usize..];
4371    String::from_utf8(bytes).map_err(|_| SnapshotError::InvalidStructure)
4372}
4373
4374fn read_dead_key(input: &mut &[u8]) -> Result<DeadKey, SnapshotError> {
4375    Ok(match opcode::read_u8(input)? {
4376        1 => DeadKey::Bool(opcode::read_u8(input)? != 0),
4377        2 => DeadKey::Integer(opcode::read_i64(input)?),
4378        3 => DeadKey::Float(opcode::read_u64(input)?),
4379        4 => {
4380            let len = checked_len(input, MAX_STRING_BYTES)?;
4381            if input.len() < len as usize {
4382                return Err(SnapshotError::Truncated);
4383            }
4384            let bytes = input[..len as usize].to_vec();
4385            *input = &input[len as usize..];
4386            DeadKey::Bytes(bytes)
4387        }
4388        5 => DeadKey::Object(opcode::read_u64(input)?),
4389        6 => DeadKey::Native(opcode::read_u32(input)?),
4390        7 => {
4391            let (domain, bits) = read_light(input)?;
4392            DeadKey::Light(domain, bits)
4393        }
4394        _ => return Err(SnapshotError::InvalidTag),
4395    })
4396}
4397
4398fn read_value(input: &mut &[u8]) -> Result<EncValue, SnapshotError> {
4399    Ok(match opcode::read_u8(input)? {
4400        0 => EncValue::Nil,
4401        1 => EncValue::Bool(opcode::read_u8(input)? != 0),
4402        2 => EncValue::Integer(opcode::read_i64(input)?),
4403        3 => EncValue::Float(opcode::read_u64(input)?),
4404        4 => EncValue::String(opcode::read_u64(input)?),
4405        5 => EncValue::Table(opcode::read_u64(input)?),
4406        6 => EncValue::Closure(opcode::read_u64(input)?),
4407        7 => EncValue::Thread(opcode::read_u64(input)?),
4408        8 => EncValue::Native(opcode::read_u32(input)?),
4409        9 => EncValue::NativeClosure(opcode::read_u64(input)?),
4410        10 => EncValue::Userdata(opcode::read_u64(input)?),
4411        11 => {
4412            let (domain, bits) = read_light(input)?;
4413            EncValue::Light(domain, bits)
4414        }
4415        _ => return Err(SnapshotError::InvalidTag),
4416    })
4417}
4418
4419fn read_light(input: &mut &[u8]) -> Result<(crate::value::LightDomain, u64), SnapshotError> {
4420    let domain = crate::value::LightDomain::from_tag(opcode::read_u8(input)?)
4421        .ok_or(SnapshotError::InvalidTag)?;
4422    Ok((domain, opcode::read_u64(input)?))
4423}
4424
4425/// A light userdata token the VM made names an object that existed: an
4426/// upvalue cell, or a native closure's value (ADR 0043). It need not still
4427/// exist; ids are never reused, so it can never name another.
4428fn light_fits(domain: crate::value::LightDomain, bits: u64, next_object_id: u64) -> bool {
4429    use crate::value::LightDomain;
4430    let id_fits = |id: u64| id != 0 && id < next_object_id;
4431    match domain {
4432        LightDomain::Host => true,
4433        LightDomain::Upvalue => id_fits(bits),
4434        LightDomain::NativeValue => {
4435            id_fits(bits >> 8) && (bits & 0xff) < u64::from(MAX_CLOSURE_VALUES)
4436        }
4437    }
4438}
4439
4440fn validate_graph(image: &Image, seen: &HashSet<u64>) -> Result<(), SnapshotError> {
4441    let mut kinds: std::collections::HashMap<u64, Kind> = std::collections::HashMap::new();
4442    for (id, _) in &image.strings {
4443        kinds.insert(*id, Kind::String);
4444    }
4445    let mut wait_keys = HashSet::new();
4446    for thread in &image.threads {
4447        for (frame_index, frame) in thread.frames.iter().enumerate() {
4448            if let PendingImage::Capability {
4449                sequence,
4450                wait_key,
4451                completed,
4452            } = frame.pending
4453            {
4454                let invalid = || SnapshotError::InvalidStructure;
4455                if frame_index + 1 != thread.frames.len()
4456                    || sequence >= image.next_sequence
4457                    || wait_key != (sequence | (1 << 63))
4458                    || completed != image.completed_waits.binary_search(&wait_key).is_ok()
4459                {
4460                    return Err(invalid());
4461                }
4462                let (operation, payload) = frame.wait_request.as_ref().ok_or_else(invalid)?;
4463                let [EncValue::String(request_id), EncValue::Integer(_), result] =
4464                    payload.as_slice()
4465                else {
4466                    return Err(invalid());
4467                };
4468                let bytes = image
4469                    .strings
4470                    .iter()
4471                    .find(|(id, _)| id == request_id)
4472                    .map(|(_, bytes)| bytes)
4473                    .ok_or_else(invalid)?;
4474                let request = crate::CapabilityRequest::from_bytes(bytes).map_err(|_| invalid())?;
4475                if !request.bounded() || request.operation() != operation {
4476                    return Err(invalid());
4477                }
4478                match (completed, result) {
4479                    (false, EncValue::Nil) => {}
4480                    (true, EncValue::String(id)) => {
4481                        let bytes = image
4482                            .strings
4483                            .iter()
4484                            .find(|(key, _)| key == id)
4485                            .map(|(_, bytes)| bytes)
4486                            .ok_or_else(invalid)?;
4487                        let result =
4488                            crate::hostcaps::protocol::decode(bytes).map_err(|_| invalid())?;
4489                        if !request.valid_result(&result) {
4490                            return Err(invalid());
4491                        }
4492                    }
4493                    _ => return Err(invalid()),
4494                }
4495            }
4496            let key = match frame.meta.as_ref().map(|meta| meta.phase) {
4497                Some(crate::heap::MetaPhase::NativeWaiting { wait_key, .. }) => Some(wait_key),
4498                _ => match frame.pending {
4499                    PendingImage::Waiting { wait_key, .. }
4500                    | PendingImage::NativeWaiting { wait_key, .. }
4501                    | PendingImage::Capability {
4502                        wait_key,
4503                        completed: false,
4504                        ..
4505                    } => Some(wait_key),
4506                    _ => None,
4507                },
4508            };
4509            if let Some(key) = key {
4510                if !wait_keys.insert(key) || image.completed_waits.binary_search(&key).is_ok() {
4511                    return Err(SnapshotError::InvalidStructure);
4512                }
4513                if frame.wait_request.is_some()
4514                    && (key & (1 << 63) == 0 || key & !(1 << 63) >= image.next_sequence)
4515                {
4516                    return Err(SnapshotError::InvalidStructure);
4517                }
4518            }
4519        }
4520    }
4521    if image.host_call && image.entry == 0 {
4522        return Err(SnapshotError::InvalidStructure);
4523    }
4524    for proto in &image.protos {
4525        kinds.insert(proto.id, Kind::Proto);
4526    }
4527    for table in &image.tables {
4528        kinds.insert(table.id, Kind::Table);
4529    }
4530    for upvalue in &image.upvalues {
4531        kinds.insert(upvalue.id, Kind::Upvalue);
4532    }
4533    for closure in &image.native_closures {
4534        kinds.insert(closure.id, Kind::NativeClosure);
4535    }
4536    for closure in &image.closures {
4537        kinds.insert(closure.id, Kind::Closure);
4538    }
4539    for thread in &image.threads {
4540        kinds.insert(thread.id, Kind::Thread);
4541    }
4542    for userdata in &image.userdata {
4543        kinds.insert(userdata.id, Kind::Userdata);
4544    }
4545    let require = |id: u64, kind: Kind| -> Result<(), SnapshotError> {
4546        if id == 0 {
4547            return Err(SnapshotError::DanglingReference);
4548        }
4549        match kinds.get(&id) {
4550            Some(found) if *found == kind => Ok(()),
4551            Some(_) => Err(SnapshotError::InvalidStructure),
4552            None => Err(SnapshotError::DanglingReference),
4553        }
4554    };
4555    if image.globals != 0 {
4556        require(image.globals, Kind::Table)?;
4557    }
4558    if image.registry != 0 {
4559        require(image.registry, Kind::Table)?;
4560    }
4561    for (tag, id) in image.type_metatables.iter().enumerate() {
4562        if *id == 0 {
4563            continue;
4564        }
4565        // Tables and userdata have per-object metatables.
4566        if crate::heap::PER_OBJECT_TYPES.contains(&tag) {
4567            return Err(SnapshotError::InvalidStructure);
4568        }
4569        require(*id, Kind::Table)?;
4570    }
4571    if image.active != 0 {
4572        require(image.active, Kind::Thread)?;
4573    }
4574    if image.entry != 0 {
4575        require(image.entry, Kind::Thread)?;
4576    }
4577    for id in &image.reserved {
4578        require(*id, Kind::String)?;
4579    }
4580    // The reserved strings are the boot-time strings, each with its
4581    // expected text, owned by no prototype.
4582    let reserved: HashSet<u64> = image.reserved.iter().copied().collect();
4583    if reserved.len() != image.reserved.len()
4584        || image
4585            .protos
4586            .iter()
4587            .any(|proto| proto.const_ids.iter().any(|id| reserved.contains(id)))
4588    {
4589        return Err(SnapshotError::InvalidStructure);
4590    }
4591    for (id, text) in image.reserved.iter().zip(crate::heap::reserved_texts()) {
4592        let bytes = image.string(*id);
4593        if bytes != Some(text.as_bytes()) {
4594            return Err(SnapshotError::InvalidStructure);
4595        }
4596    }
4597    for proto in &image.protos {
4598        if proto.ops.len() > MAX_INSTRUCTIONS as usize {
4599            return Err(SnapshotError::LimitExceeded);
4600        }
4601        for child in &proto.children {
4602            require(*child, Kind::Proto)?;
4603        }
4604        for op in &proto.ops {
4605            if let Op::CallHost { symbol, .. } = op {
4606                let bytes = proto
4607                    .byte_consts
4608                    .get(*symbol as usize)
4609                    .ok_or(SnapshotError::InvalidStructure)?;
4610                let _ = std::str::from_utf8(bytes).map_err(|_| SnapshotError::InvalidStructure)?;
4611            }
4612        }
4613    }
4614    for table in &image.tables {
4615        validate_table_slots(image, &require, &kinds, table)?;
4616        if table.metatable != 0 {
4617            require(table.metatable, Kind::Table)?;
4618        }
4619    }
4620    for upvalue in &image.upvalues {
4621        match &upvalue.state {
4622            UpImageState::Closed(value) => require_value(&require, value)?,
4623            UpImageState::Open { thread, slot } => {
4624                require(*thread, Kind::Thread)?;
4625                if *slot >= image.max_stack_slots {
4626                    return Err(SnapshotError::LimitExceeded);
4627                }
4628            }
4629        }
4630    }
4631    for closure in &image.native_closures {
4632        for value in &closure.values {
4633            require_value(&require, value)?;
4634        }
4635    }
4636    validate_userdata(image, &require)?;
4637    validate_finalizers(image, &kinds)?;
4638    validate_collector(image, &kinds, &require)?;
4639    for closure in &image.closures {
4640        require(closure.proto, Kind::Proto)?;
4641        for upvalue in &closure.upvalues {
4642            require(*upvalue, Kind::Upvalue)?;
4643        }
4644    }
4645    validate_resumers(image)?;
4646    for thread in &image.threads {
4647        if thread.resumed_by != 0 {
4648            require(thread.resumed_by, Kind::Thread)?;
4649        }
4650        for value in thread.stack.iter().chain(thread.results.iter()) {
4651            require_value(&require, value)?;
4652        }
4653        if !thread_slots_fit(thread, image.max_stack_slots) {
4654            return Err(SnapshotError::LimitExceeded);
4655        }
4656        let closing_failed = thread.id == image.entry
4657            && image.finalizers.closed == Status::Failed.tag()
4658            && (thread.status == Status::Ready.tag() || thread.status == Status::Waiting.tag());
4659        validate_error_state(thread, closing_failed, exit_scopes(image, thread))?;
4660        validate_waits(thread)?;
4661        validate_closes(image, thread)?;
4662        validate_hooks(image, thread, &require)?;
4663        // The running frame's extra arguments are on the stack: every
4664        // return, commit, and unwind keeps them.
4665        if let Some(frame) = thread.frames.last()
4666            && frame.vararg_len > 0
4667            && u64::from(frame.base) > thread.stack.len() as u64
4668        {
4669            return Err(SnapshotError::InvalidStructure);
4670        }
4671        if let Some((_, value)) = &thread.error {
4672            require_value(&require, value)?;
4673        }
4674        if let Some((_, value)) = thread
4675            .unwind
4676            .as_ref()
4677            .and_then(|unwind| unwind.error.as_ref())
4678        {
4679            require_value(&require, value)?;
4680        }
4681        for (index, frame) in thread.frames.iter().enumerate() {
4682            validate_boundary(thread, index)?;
4683            string_work_fits(image, thread, index)?;
4684            if let Some(MetaImage {
4685                event:
4686                    EventImage::Close {
4687                        next:
4688                            NextImage::Unwind(UnwindImage {
4689                                error: Some((_, value)),
4690                                ..
4691                            }),
4692                        ..
4693                    },
4694                ..
4695            }) = &frame.meta
4696            {
4697                require_value(&require, value)?;
4698            }
4699            if let Some((_, payload)) = &frame.wait_request {
4700                for value in payload {
4701                    require_value(&require, value)?;
4702                }
4703            }
4704            if let Some(BoundaryImage::Native { symbol, error, .. }) = &frame.boundary {
4705                if *symbol as usize >= image.natives.len() {
4706                    return Err(SnapshotError::UnknownHostSymbol);
4707                }
4708                if let Some((class, value)) = error {
4709                    if crate::id::LuaFault::from_tag(*class).is_none() {
4710                        return Err(SnapshotError::InvalidTag);
4711                    }
4712                    require_value(&require, value)?;
4713                }
4714            }
4715            if let Some(BoundaryImage::HookNative { callee, .. }) = &frame.boundary {
4716                require_value(&require, callee)?;
4717            }
4718            if let Some(BoundaryImage::Protect {
4719                handler: Some(handler),
4720                ..
4721            }) = &frame.boundary
4722            {
4723                require_value(&require, handler)?;
4724            }
4725        }
4726        for (index, frame) in thread.frames.iter().enumerate() {
4727            require(frame.closure, Kind::Closure)?;
4728            let proto = frame_proto(image, frame)?;
4729            if frame.pc as usize >= proto.ops.len() {
4730                return Err(SnapshotError::InvalidProgramCounter);
4731            }
4732            validate_frame_slots(thread, index, proto)?;
4733            validate_called(image, thread, index)?;
4734            // Source makes a tail call only outside every `<close>` scope,
4735            // and the runtime refuses one that would skip a close.
4736            if matches!(proto.ops[frame.pc as usize], Op::TailCall { .. })
4737                && thread
4738                    .tbc
4739                    .iter()
4740                    .any(|slot| (frame.base..frame.limit).contains(slot))
4741            {
4742                return Err(SnapshotError::InvalidStructure);
4743            }
4744            if let Some(meta) = &frame.meta {
4745                validate_meta(meta, proto.ops[frame.pc as usize], frame)?;
4746            }
4747            match &frame.pending {
4748                PendingImage::None => {}
4749                PendingImage::Resuming {
4750                    child,
4751                    dest,
4752                    nresults,
4753                } => {
4754                    require(*child, Kind::Thread)?;
4755                    // `Resume` waits on a coroutine it runs; `CloseThread`
4756                    // on one it closes.
4757                    let closing = image.thread(*child).is_some_and(|thread| thread.closing);
4758                    let fits = match proto.ops[frame.pc as usize] {
4759                        Op::Resume {
4760                            dest: op_dest,
4761                            nresults: op_nresults,
4762                            ..
4763                        } => !closing && op_dest == *dest && op_nresults == *nresults,
4764                        Op::CloseThread { dst, .. } => closing && dst == *dest && *nresults == 2,
4765                        _ => false,
4766                    };
4767                    if !fits {
4768                        return Err(SnapshotError::InvalidStructure);
4769                    }
4770                }
4771                // Only a boundary frame defers a call.
4772                PendingImage::Deferred if frame.boundary.is_none() => {
4773                    return Err(SnapshotError::InvalidStructure);
4774                }
4775                PendingImage::Prepared { .. }
4776                | PendingImage::Waiting { .. }
4777                | PendingImage::Assigning { .. }
4778                | PendingImage::NativePrepared { .. }
4779                | PendingImage::NativeWaiting { .. }
4780                | PendingImage::Capability { .. }
4781                | PendingImage::Deferred => {}
4782            }
4783            for target in &frame.targets {
4784                if let TargetImage::Field { table, key } = target {
4785                    require_value(&require, table)?;
4786                    require_value(&require, key)?;
4787                }
4788            }
4789        }
4790    }
4791    let _ = seen;
4792    Ok(())
4793}
4794
4795/// The finalization lists name tables and full userdata, each at most
4796/// once over both; a finalizer runs only with its frame on some thread,
4797/// at most one at a time; a runtime closes only once closing began
4798/// (ADR 0047, ADR 0048).
4799/// The collector's state is one the collector reaches (ADR 0050): every
4800/// list names objects that exist, of the right kind, with marks that fit
4801/// the list; lists exist only in the phases that have them; positions lie
4802/// inside what they point into; the sweep has at least the objects not
4803/// yet passed left to pass.
4804fn validate_collector(
4805    image: &Image,
4806    kinds: &std::collections::HashMap<u64, Kind>,
4807    require: &dyn Fn(u64, Kind) -> Result<(), SnapshotError>,
4808) -> Result<(), SnapshotError> {
4809    use crate::heap::{age, mark};
4810    let c = &image.collector;
4811    let gc = &image.gc;
4812    let bad = || Err(SnapshotError::InvalidStructure);
4813    if c.white > 1 || c.phase > 5 {
4814        return bad();
4815    }
4816    let step_known = crate::gc::Atomic::from_tag(c.atomic).is_some();
4817    if (c.phase == 3 && !step_known) || (c.phase != 3 && c.atomic != 0) {
4818        return bad();
4819    }
4820    if gc.prepaid >= crate::gc::WORK_PER_FUEL {
4821        return bad();
4822    }
4823    let marking = matches!(c.phase, 2 | 3) || (c.minor && c.phase == 1);
4824    let sweeping = c.phase == 4;
4825    // The generational states (ADR 0051): a young collection runs only in
4826    // generational form, from its first units to its last, and a sweep
4827    // making survivors old is the one sweep in that form; nothing else
4828    // is, between collections, but generational mode chosen.
4829    let decide = crate::gc::Decide::from_tag(c.decide).ok_or(SnapshotError::InvalidStructure)?;
4830    let idle = c.generational && !c.minor && !c.to_old;
4831    if (c.minor && (!c.generational || !matches!(c.phase, 1 | 3 | 4 | 5) || !gc.generational))
4832        || (c.phase == 5 && !c.minor)
4833        || (c.to_old && (!c.generational || c.phase != 4 || c.minor))
4834        || (idle && (c.phase != 0 || !gc.generational))
4835        || (c.reset && (c.generational || !sweeping))
4836        || (c.generational && gc.bad != 0)
4837        || (gc.bad != 0 && !gc.generational)
4838        || (decide != crate::gc::Decide::None && (c.minor || (c.generational && !c.to_old)))
4839        || (decide == crate::gc::Decide::Fallback && matches!(c.phase, 1..=3) && gc.bad == 0)
4840        || (!c.minor && (c.promoted != 0 || !c.touched.is_empty()))
4841        || ((!sweeping || c.reset) && c.unreleased != 0)
4842        || c.unreleased > gc.quota
4843        || gc.major_base > gc.quota
4844        || gc.major_objects > 2 * crate::heap::MAX_OBJECTS
4845    {
4846        return bad();
4847    }
4848    // Lua does not run during an atomic phase or a young collection, so no
4849    // finalizer can be running then.
4850    if (c.phase == 3 || c.minor) && image.finalizers.running {
4851        return bad();
4852    }
4853    let mut marks = std::collections::HashMap::new();
4854    for (id, found, object_age) in &c.marks {
4855        if !kinds.contains_key(id)
4856            || !matches!(*found, mark::GRAY | mark::BLACK)
4857            || !age::valid(*object_age)
4858        {
4859            return bad();
4860        }
4861        if marks.insert(*id, (*found, *object_age)).is_some() {
4862            return bad();
4863        }
4864    }
4865    let mut ages = std::collections::HashMap::new();
4866    for (id, object_age) in &c.ages {
4867        if !kinds.contains_key(id)
4868            || marks.contains_key(id)
4869            || !age::valid(*object_age)
4870            || *object_age == age::NEW
4871            || ages.insert(*id, *object_age).is_some()
4872        {
4873            return bad();
4874        }
4875    }
4876    // In generational form an object off the young lists, and written in
4877    // neither list, is black and old.
4878    if c.generational {
4879        let listed: HashSet<u64> = c.young.iter().copied().collect();
4880        for id in kinds.keys() {
4881            if !listed.contains(id) && !marks.contains_key(id) && !ages.contains_key(id) {
4882                marks.insert(*id, (mark::BLACK, age::OLD));
4883            }
4884        }
4885    }
4886    // Ages: all new in incremental form (but a sweep leaving generational
4887    // form, which makes them so); young objects white and old ones marked
4888    // between collections in generational form, a touched one gray.
4889    for (id, (found, object_age)) in &marks {
4890        let fits = if c.reset {
4891            true
4892        } else if !c.generational {
4893            *object_age == age::NEW
4894        } else if c.to_old {
4895            matches!(
4896                (*found, *object_age),
4897                (_, age::NEW) | (mark::BLACK, age::OLD) | (mark::GRAY, age::TOUCHED1)
4898            )
4899        } else if c.minor {
4900            true
4901        } else {
4902            age::is_old(*object_age) && ((*found == mark::GRAY) == (*object_age == age::TOUCHED1))
4903        };
4904        if !fits || !kinds.contains_key(id) {
4905            return bad();
4906        }
4907    }
4908    for object_age in ages.values() {
4909        if !c.reset && (!c.generational || c.to_old || *object_age != age::SURVIVAL) {
4910            return bad();
4911        }
4912    }
4913    if !marking && !sweeping && !c.generational && !marks.is_empty() {
4914        return bad();
4915    }
4916    let marked = |id: &u64, want: u8| marks.get(id).is_some_and(|(found, _)| *found == want);
4917    let age_of = |id: &u64| {
4918        marks
4919            .get(id)
4920            .map(|(_, object_age)| *object_age)
4921            .or_else(|| ages.get(id).copied())
4922            .unwrap_or(age::NEW)
4923    };
4924    if !marking
4925        && (!c.gray.is_empty()
4926            || c.scan.is_some()
4927            || !c.weak.is_empty()
4928            || !c.ephemerons.is_empty()
4929            || !c.waiting.is_empty()
4930            || (!c.again.is_empty() && !c.generational))
4931    {
4932        return bad();
4933    }
4934    let mut seen = HashSet::new();
4935    for id in c.gray.iter().chain(&c.again) {
4936        if !marked(id, mark::GRAY) || !seen.insert(*id) {
4937            return bad();
4938        }
4939    }
4940    // While marking, every gray object waits to be traced, in one list or
4941    // the other; in generational form, every touched object waits in
4942    // `again`. (An incremental sweep makes gray objects white like black
4943    // ones.)
4944    if (marking || c.generational)
4945        && marks
4946            .iter()
4947            .any(|(id, (found, _))| *found == mark::GRAY && !seen.contains(id))
4948    {
4949        return bad();
4950    }
4951    // The young lists hold the young objects, each once, and every white
4952    // object in generational form; none outside it.
4953    let mut young = HashSet::new();
4954    for id in &c.young {
4955        if !kinds.contains_key(id)
4956            || !young.insert(*id)
4957            || age_of(id) > age::SURVIVAL
4958            || (idle && marks.contains_key(id))
4959        {
4960            return bad();
4961        }
4962    }
4963    if !c.generational && !c.young.is_empty() {
4964        return bad();
4965    }
4966    // Young objects are all listed, but the survivors a sweep making them
4967    // old has not reached yet.
4968    if c.generational
4969        && !c.to_old
4970        && marks
4971            .iter()
4972            .any(|(id, (_, object_age))| *object_age <= age::SURVIVAL && !young.contains(id))
4973    {
4974        return bad();
4975    }
4976    if c.generational
4977        && kinds
4978            .keys()
4979            .any(|id| !marks.contains_key(id) && !young.contains(id))
4980    {
4981        return bad();
4982    }
4983    // The objects the next young collection traces again: each once, old,
4984    // and every `OLD1` and `TOUCHED2` object between collections.
4985    let mut revisit = HashSet::new();
4986    for id in &c.revisit {
4987        let object_age = age_of(id);
4988        if !revisit.insert(*id)
4989            || !matches!(object_age, age::OLD1 | age::TOUCHED2 | age::TOUCHED1)
4990            || (object_age == age::TOUCHED1) != marked(id, mark::GRAY)
4991            || !marks.contains_key(id)
4992        {
4993            return bad();
4994        }
4995    }
4996    if (!c.revisit.is_empty() && (!c.generational || c.to_old || (c.minor && c.phase == 3)))
4997        || (idle
4998            && marks.iter().any(|(id, (_, object_age))| {
4999                matches!(*object_age, age::OLD1 | age::TOUCHED2) && !revisit.contains(id)
5000            }))
5001    {
5002        return bad();
5003    }
5004    for id in &c.touched {
5005        if !marks.contains_key(id) || !age::is_old(age_of(id)) || c.phase == 1 {
5006            return bad();
5007        }
5008    }
5009    // A full collection asks for at most the cycle running and one more.
5010    if gc
5011        .full
5012        .is_some_and(|target| target > gc.collections.saturating_add(2))
5013    {
5014        return bad();
5015    }
5016    // An object being scanned, or an ephemeron table waiting, was black
5017    // when reached, and gray again if written to since.
5018    if let Some((id, pos, how, keys, values)) = c.scan {
5019        if !marks.contains_key(&id) {
5020            return bad();
5021        }
5022        let total = match (how, kinds.get(&id)) {
5023            (1 | 2, Some(Kind::Table)) => image
5024                .tables
5025                .iter()
5026                .find(|table| table.id == id)
5027                .map(|table| table.slots.len()),
5028            (0, Some(Kind::Thread)) => {
5029                image
5030                    .threads
5031                    .iter()
5032                    .find(|thread| thread.id == id)
5033                    .map(|thread| {
5034                        thread.stack.len() + 1 + thread.frames.len() + thread.results.len() + 1
5035                    })
5036            }
5037            (0, Some(Kind::Proto)) => image
5038                .protos
5039                .iter()
5040                .find(|proto| proto.id == id)
5041                .map(|proto| 1 + proto.const_ids.len() + proto.children.len()),
5042            _ => None,
5043        };
5044        // Written to since it was reached, it may have shrunk below the
5045        // position; it is traced again in the atomic phase. An ephemeron
5046        // table is reached before its first slot is looked at, so may
5047        // have none.
5048        let written = marked(&id, mark::GRAY);
5049        let past = |total: usize| pos as usize > total || (pos as usize == total && how != 2);
5050        if total.is_none_or(|total| past(total) && !written)
5051            || (how != 1 && (keys || values))
5052            || (how == 1 && keys && !values)
5053        {
5054            return bad();
5055        }
5056    }
5057    for (id, _, _) in &c.weak {
5058        require(*id, Kind::Table)?;
5059        if !marks.contains_key(id) {
5060            return bad();
5061        }
5062    }
5063    for id in &c.ephemerons {
5064        require(*id, Kind::Table)?;
5065        if !marks.contains_key(id) {
5066            return bad();
5067        }
5068    }
5069    let mut last = 0;
5070    for (key, values) in &c.waiting {
5071        if *key <= last
5072            || values.is_empty()
5073            || matches!(
5074                kinds.get(key),
5075                None | Some(Kind::String | Kind::Proto | Kind::Upvalue)
5076            )
5077        {
5078            return bad();
5079        }
5080        last = *key;
5081        for value in values {
5082            require_value(require, value)?;
5083        }
5084    }
5085    let atomic = c.phase == 3;
5086    if !atomic && (c.cursor != 0 || c.inner != 0 || c.late != 0) {
5087        return bad();
5088    }
5089    if c.cursor as usize > c.weak.len() || c.late as usize > c.weak.len() {
5090        return bad();
5091    }
5092    if c.inner != 0 {
5093        let Some((id, _, _)) = c.weak.get(c.cursor as usize) else {
5094            return bad();
5095        };
5096        let slots = image
5097            .tables
5098            .iter()
5099            .find(|table| table.id == *id)
5100            .map_or(0, |table| table.slots.len());
5101        if c.inner as usize >= slots {
5102            return bad();
5103        }
5104    }
5105    if !sweeping && (c.sweep_left != 0 || c.reset) {
5106        return bad();
5107    }
5108    // The sweep has still to pass every object it has not: marked ones
5109    // (in a sweep making survivors old, those still new; in a young
5110    // collection, the marked young ones).
5111    let unswept = if c.minor {
5112        c.young.iter().filter(|id| marks.contains_key(id)).count()
5113    } else if c.to_old {
5114        marks
5115            .values()
5116            .filter(|(_, object_age)| *object_age == age::NEW)
5117            .count()
5118    } else {
5119        marks.len()
5120    };
5121    if sweeping && c.sweep_left < unswept as u64 {
5122        return bad();
5123    }
5124    let counting = marking || sweeping || (c.minor && c.phase == 5);
5125    if !counting
5126        && (c.marked_bytes != 0
5127            || c.debt_base != 0
5128            || c.marking_debt != 0
5129            || (c.work_base != 0 && !c.minor))
5130    {
5131        return bad();
5132    }
5133    Ok(())
5134}
5135
5136fn validate_finalizers(
5137    image: &Image,
5138    kinds: &std::collections::HashMap<u64, Kind>,
5139) -> Result<(), SnapshotError> {
5140    let fin = &image.finalizers;
5141    if let Some(exit) = fin.exit {
5142        use crate::heap::ExitPhase;
5143        let main = image
5144            .thread(image.entry)
5145            .ok_or(SnapshotError::InvalidStructure)?;
5146        let fits = match exit.phase {
5147            ExitPhase::Scopes => {
5148                exit.close
5149                    && matches!(
5150                        Status::from_u8(main.status),
5151                        Some(Status::Ready | Status::Waiting)
5152                    )
5153                    && (main.unwind.is_some()
5154                        || main.frames.iter().any(|frame| {
5155                            matches!(
5156                                frame.meta.as_ref().map(|meta| &meta.event),
5157                                Some(EventImage::Close {
5158                                    next: NextImage::Unwind(_),
5159                                    ..
5160                                })
5161                            )
5162                        }))
5163            }
5164            ExitPhase::Finalizers => exit.close && fin.closing && fin.closed != 0,
5165            ExitPhase::Terminal => {
5166                !exit.close
5167                    || (fin.closing
5168                        && fin.closed == 0
5169                        && fin.pending.is_empty()
5170                        && !fin.running
5171                        && main.frames.is_empty()
5172                        && main.status == Status::Completed.tag()
5173                        && image.active == image.entry)
5174            }
5175        };
5176        if !fits {
5177            return Err(SnapshotError::InvalidStructure);
5178        }
5179    }
5180    let mut seen = HashSet::new();
5181    for id in fin.registered.iter().chain(fin.pending.iter()) {
5182        match kinds.get(id) {
5183            Some(Kind::Table | Kind::Userdata) => {}
5184            Some(_) => return Err(SnapshotError::InvalidStructure),
5185            None => return Err(SnapshotError::DanglingReference),
5186        }
5187        if !seen.insert(*id) {
5188            return Err(SnapshotError::InvalidStructure);
5189        }
5190    }
5191    let frames = image
5192        .threads
5193        .iter()
5194        .flat_map(|thread| thread.frames.iter())
5195        .filter(|frame| matches!(frame.boundary, Some(BoundaryImage::Finalizer { .. })))
5196        .count();
5197    if frames != usize::from(fin.running) {
5198        return Err(SnapshotError::InvalidStructure);
5199    }
5200    // Closing moved every registered object to the queue; one with no
5201    // frames of its own was the entry thread's, whose run had ended.
5202    if fin.closing && !fin.registered.is_empty() {
5203        return Err(SnapshotError::InvalidStructure);
5204    }
5205    // While the entry thread closes with no frames of its own, it is
5206    // ready, has finalizers left to run or running, and their frames name
5207    // the close's closure; no other thread starts with a finalizer frame.
5208    let entry = image.threads.iter().find(|thread| thread.id == image.entry);
5209    let bottom_finalizer = |thread: &ThreadImage| {
5210        matches!(
5211            thread
5212                .frames
5213                .first()
5214                .and_then(|frame| frame.boundary.as_ref()),
5215            Some(BoundaryImage::Finalizer { .. })
5216        )
5217    };
5218    match fin.closed {
5219        0 => {
5220            if fin.close_closure != 0 || image.threads.iter().any(bottom_finalizer) {
5221                return Err(SnapshotError::InvalidStructure);
5222            }
5223        }
5224        tag => {
5225            let fits = fin.closing
5226                && matches!(
5227                    Status::from_u8(tag),
5228                    Some(Status::Completed | Status::Failed)
5229                )
5230                && matches!(kinds.get(&fin.close_closure), Some(Kind::Closure))
5231                && entry.is_some_and(|entry| {
5232                    (entry.status == Status::Ready.tag() || entry.status == Status::Waiting.tag())
5233                        && (!fin.pending.is_empty() || !entry.frames.is_empty())
5234                        && entry.frames.first().is_none_or(|frame| {
5235                            frame.closure == fin.close_closure
5236                                && matches!(frame.boundary, Some(BoundaryImage::Finalizer { .. }))
5237                        })
5238                })
5239                && !image
5240                    .threads
5241                    .iter()
5242                    .any(|thread| thread.id != image.entry && bottom_finalizer(thread));
5243            if !fits {
5244                return Err(SnapshotError::InvalidStructure);
5245            }
5246        }
5247    }
5248    Ok(())
5249}
5250
5251/// A full userdata's metatable is a table, its user values exist, a byte
5252/// payload counts its length, and every payload together fits the quota
5253/// it was charged against (ADR 0042, ADR 0045).
5254fn validate_userdata(
5255    image: &Image,
5256    require: &dyn Fn(u64, Kind) -> Result<(), SnapshotError>,
5257) -> Result<(), SnapshotError> {
5258    let mut total = 0u64;
5259    let mut file_resources = HashSet::new();
5260    for userdata in &image.userdata {
5261        if userdata.metatable != 0 {
5262            require(userdata.metatable, Kind::Table)?;
5263        }
5264        for value in &userdata.user_values {
5265            require_value(require, value)?;
5266        }
5267        match &userdata.payload {
5268            PayloadImage::File(file) => {
5269                if !file.closed && file.kind < 2 && !file_resources.insert(file.id.0) {
5270                    return Err(SnapshotError::InvalidStructure);
5271                }
5272                if userdata.charge != file.charge() {
5273                    return Err(SnapshotError::UserdataCharge);
5274                }
5275            }
5276            PayloadImage::Bytes(bytes) => {
5277                if userdata.charge != bytes.len() as u64 {
5278                    return Err(SnapshotError::InvalidStructure);
5279                }
5280            }
5281            PayloadImage::Host { symbol, .. } | PayloadImage::Rebind { symbol, .. } => {
5282                if symbol.is_empty() {
5283                    return Err(SnapshotError::InvalidStructure);
5284                }
5285            }
5286        }
5287        total = total.saturating_add(crate::heap::userdata_cost(
5288            userdata.user_values.len(),
5289            userdata.charge,
5290        ));
5291    }
5292    if total > image.gc.quota {
5293        return Err(SnapshotError::LimitExceeded);
5294    }
5295    Ok(())
5296}
5297
5298fn validate_table_slots(
5299    image: &Image,
5300    require: &dyn Fn(u64, Kind) -> Result<(), SnapshotError>,
5301    kinds: &std::collections::HashMap<u64, Kind>,
5302    table: &TableImage,
5303) -> Result<(), SnapshotError> {
5304    // A key's slots: dead anchors, then at most one live slot, the last
5305    // (ADR 0010): a deleted key reinserted before the anchors went.
5306    let mut live = std::collections::HashMap::new();
5307    for slot in &table.slots {
5308        let (key, is_live) = match &slot.body {
5309            SlotBody::Live { key, value } => {
5310                if matches!(value, EncValue::Nil) {
5311                    return Err(SnapshotError::InvalidStructure);
5312                }
5313                require_value(require, key)?;
5314                require_value(require, value)?;
5315                (canonical_live_key(image, key)?, true)
5316            }
5317            SlotBody::Dead(key) => (canonical_dead_key(image, kinds, key)?, false),
5318        };
5319        if live.insert(key, is_live) == Some(true) {
5320            return Err(SnapshotError::InvalidStructure);
5321        }
5322    }
5323    Ok(())
5324}
5325
5326fn canonical_live_key(image: &Image, value: &EncValue) -> Result<TableKey, SnapshotError> {
5327    Ok(match value {
5328        EncValue::Nil => return Err(SnapshotError::InvalidStructure),
5329        EncValue::Bool(bit) => TableKey::Bool(*bit),
5330        EncValue::Integer(integer) => TableKey::Integer(*integer),
5331        EncValue::Float(bits) => canonical_float_key(*bits)?,
5332        EncValue::String(id) => {
5333            let bytes = image.string(*id).ok_or(SnapshotError::DanglingReference)?;
5334            TableKey::string(bytes.to_vec())
5335        }
5336        EncValue::Table(id)
5337        | EncValue::Closure(id)
5338        | EncValue::Thread(id)
5339        | EncValue::NativeClosure(id)
5340        | EncValue::Userdata(id) => TableKey::Object(ObjectId(*id)),
5341        EncValue::Native(index) => native_key(image, *index)?,
5342        EncValue::Light(domain, bits) => light_key(image, *domain, *bits)?,
5343    })
5344}
5345
5346fn light_key(
5347    image: &Image,
5348    domain: crate::value::LightDomain,
5349    bits: u64,
5350) -> Result<TableKey, SnapshotError> {
5351    if light_fits(domain, bits, image.next_object_id) {
5352        Ok(TableKey::Light(domain, bits))
5353    } else {
5354        Err(SnapshotError::InvalidStructure)
5355    }
5356}
5357
5358fn native_key(image: &Image, index: u32) -> Result<TableKey, SnapshotError> {
5359    if (index as usize) < image.natives.len() {
5360        Ok(TableKey::Native(index))
5361    } else {
5362        Err(SnapshotError::DanglingReference)
5363    }
5364}
5365
5366fn canonical_dead_key(
5367    image: &Image,
5368    kinds: &std::collections::HashMap<u64, Kind>,
5369    key: &DeadKey,
5370) -> Result<TableKey, SnapshotError> {
5371    Ok(match key {
5372        DeadKey::Bool(bit) => TableKey::Bool(*bit),
5373        DeadKey::Integer(integer) => TableKey::Integer(*integer),
5374        DeadKey::Float(bits) => canonical_float_key(*bits)?,
5375        DeadKey::Bytes(bytes) => TableKey::string(bytes.clone()),
5376        DeadKey::Object(id) => {
5377            if *id == 0 || *id >= image.next_object_id {
5378                return Err(SnapshotError::InvalidStructure);
5379            }
5380            if let Some(kind) = kinds.get(id) {
5381                match kind {
5382                    Kind::Table
5383                    | Kind::Closure
5384                    | Kind::Thread
5385                    | Kind::NativeClosure
5386                    | Kind::Userdata => {}
5387                    Kind::String | Kind::Proto | Kind::Upvalue => {
5388                        return Err(SnapshotError::InvalidStructure);
5389                    }
5390                }
5391            }
5392            TableKey::Object(ObjectId(*id))
5393        }
5394        DeadKey::Native(index) => native_key(image, *index)?,
5395        DeadKey::Light(domain, bits) => light_key(image, *domain, *bits)?,
5396    })
5397}
5398
5399/// A float key is canonical when the table itself would store it as that
5400/// float: not NaN, and not a float that normalizes to an integer key.
5401fn canonical_float_key(bits: u64) -> Result<TableKey, SnapshotError> {
5402    match crate::table::normalize_key(Value::Float(f64::from_bits(bits)), None, None) {
5403        Ok(TableKey::Float(canonical)) if canonical == bits => Ok(TableKey::Float(bits)),
5404        _ => Err(SnapshotError::InvalidStructure),
5405    }
5406}
5407
5408fn realized_dead_key(key: &DeadKey) -> Result<TableKey, SnapshotError> {
5409    Ok(match key {
5410        DeadKey::Bool(bit) => TableKey::Bool(*bit),
5411        DeadKey::Integer(integer) => TableKey::Integer(*integer),
5412        DeadKey::Float(bits) => canonical_float_key(*bits)?,
5413        DeadKey::Bytes(bytes) => TableKey::string(bytes.clone()),
5414        DeadKey::Object(id) => {
5415            if *id == 0 {
5416                return Err(SnapshotError::InvalidStructure);
5417            }
5418            TableKey::Object(ObjectId(*id))
5419        }
5420        // Range-checked by `canonical_dead_key` during validation.
5421        DeadKey::Native(index) => TableKey::Native(*index),
5422        DeadKey::Light(domain, bits) => TableKey::Light(*domain, *bits),
5423    })
5424}
5425
5426fn require_value(
5427    require: &dyn Fn(u64, Kind) -> Result<(), SnapshotError>,
5428    value: &EncValue,
5429) -> Result<(), SnapshotError> {
5430    match value {
5431        EncValue::Nil | EncValue::Bool(_) | EncValue::Integer(_) | EncValue::Float(_) => Ok(()),
5432        EncValue::String(id) => require(*id, Kind::String),
5433        EncValue::Table(id) => require(*id, Kind::Table),
5434        EncValue::Closure(id) => require(*id, Kind::Closure),
5435        EncValue::Thread(id) => require(*id, Kind::Thread),
5436        EncValue::NativeClosure(id) => require(*id, Kind::NativeClosure),
5437        EncValue::Userdata(id) => require(*id, Kind::Userdata),
5438        // The index, and a token's range, are checked when the value is
5439        // decoded.
5440        EncValue::Native(_) | EncValue::Light(..) => Ok(()),
5441    }
5442}
5443
5444/// The limits a restored runtime runs under (ADR 0052): for each, the
5445/// smaller of the snapshot's and the host's.
5446fn effective(image: &Image, limits: &Limits) -> Limits {
5447    Limits {
5448        max_logical_heap: image.gc.quota.min(limits.max_logical_heap),
5449        max_objects: image.max_objects.min(limits.max_objects),
5450        max_stack_slots: image.max_stack_slots.min(limits.max_stack_slots),
5451        max_string_bytes: u64::from(image.max_string).min(limits.max_string_bytes),
5452        max_snapshot_bytes: limits.max_snapshot_bytes,
5453    }
5454}
5455
5456fn realize(
5457    image: &Image,
5458    registry: &HostRegistry,
5459    limits: &Limits,
5460    capabilities: &crate::HostCapabilities,
5461) -> Result<Runtime, SnapshotError> {
5462    check_symbols(image, registry)?;
5463    check_userdata_policies(image, registry)?;
5464    let within = effective(image, limits);
5465    // A smaller host bound the state does not fit refuses the snapshot.
5466    if !slots_fit(image, within.max_stack_slots)
5467        || image
5468            .strings
5469            .iter()
5470            .any(|(_, bytes)| bytes.len() as u64 > within.max_string_bytes)
5471    {
5472        return Err(SnapshotError::LimitExceeded);
5473    }
5474    let mut heap = Heap::new();
5475    heap.gc = image.gc.clone();
5476    heap.max_string = within.max_string_bytes as usize;
5477    heap.library = image.library.clone();
5478    // Objects come back with the current white; the marks that differ
5479    // are set once every object is made.
5480    heap.collector.white = image.collector.white;
5481    crate::gc::restore_policy(&mut heap);
5482    let mut strings = std::collections::HashMap::<u64, Handle<StringObj>>::new();
5483    let mut tables = std::collections::HashMap::<u64, Handle<TableObj>>::new();
5484    let mut protos = std::collections::HashMap::<u64, Handle<Proto>>::new();
5485    let mut upvalues = std::collections::HashMap::<u64, Handle<UpvalueObj>>::new();
5486    let mut closures = std::collections::HashMap::<u64, Handle<ClosureObj>>::new();
5487    let mut threads = std::collections::HashMap::<u64, Handle<ThreadObj>>::new();
5488    let mut native_closures = std::collections::HashMap::<u64, Handle<NativeClosureObj>>::new();
5489
5490    for (id, bytes) in &image.strings {
5491        let handle = heap
5492            .strings
5493            .alloc(StringObj {
5494                id: ObjectId(*id),
5495                bytes: crate::table::KeyString::new(bytes.clone()),
5496            })
5497            .map_err(|_| SnapshotError::LimitExceeded)?;
5498        strings.insert(*id, handle);
5499    }
5500    for table in &image.tables {
5501        let handle = heap
5502            .tables
5503            .alloc(TableObj {
5504                id: ObjectId(table.id),
5505                table: Table::new(),
5506                metatable: None,
5507                finalize: false,
5508            })
5509            .map_err(|_| SnapshotError::LimitExceeded)?;
5510        tables.insert(table.id, handle);
5511    }
5512    for proto in &image.protos {
5513        let handle = heap
5514            .protos
5515            .alloc(Proto {
5516                id: ObjectId(proto.id),
5517                ops: proto.ops.clone(),
5518                field_hints: Proto::empty_field_hints(&proto.ops),
5519                byte_consts: proto.byte_consts.clone(),
5520                byte_hashes: proto
5521                    .const_ids
5522                    .iter()
5523                    .map(|id| {
5524                        heap.strings
5525                            .get(strings[id])
5526                            .expect("restored string")
5527                            .hash()
5528                    })
5529                    .collect(),
5530                const_strings: proto
5531                    .const_ids
5532                    .iter()
5533                    .map(|id| {
5534                        strings
5535                            .get(id)
5536                            .copied()
5537                            .ok_or(SnapshotError::DanglingReference)
5538                    })
5539                    .collect::<Result<_, _>>()?,
5540                captures: proto.captures.clone(),
5541                children: Vec::new(),
5542                max_reg: proto.max_reg,
5543                params: proto.params,
5544                vararg: proto.vararg,
5545                debug: proto.debug.clone(),
5546                source: if proto.source == 0 {
5547                    None
5548                } else {
5549                    Some(
5550                        *strings
5551                            .get(&proto.source)
5552                            .ok_or(SnapshotError::DanglingReference)?,
5553                    )
5554                },
5555            })
5556            .map_err(|_| SnapshotError::LimitExceeded)?;
5557        protos.insert(proto.id, handle);
5558    }
5559    for upvalue in &image.upvalues {
5560        let handle = heap
5561            .upvalues
5562            .alloc(UpvalueObj {
5563                id: ObjectId(upvalue.id),
5564                state: UpvalueState::Closed(Value::Nil),
5565            })
5566            .map_err(|_| SnapshotError::LimitExceeded)?;
5567        upvalues.insert(upvalue.id, handle);
5568    }
5569    for closure in &image.closures {
5570        let proto = *protos
5571            .get(&closure.proto)
5572            .ok_or(SnapshotError::DanglingReference)?;
5573        let handle = heap
5574            .closures
5575            .alloc(ClosureObj {
5576                id: ObjectId(closure.id),
5577                proto,
5578                upvalues: Vec::new(),
5579            })
5580            .map_err(|_| SnapshotError::LimitExceeded)?;
5581        closures.insert(closure.id, handle);
5582    }
5583    for thread in &image.threads {
5584        let handle = heap
5585            .threads
5586            .alloc(ThreadObj {
5587                id: ObjectId(thread.id),
5588                status: Status::from_u8(thread.status).ok_or(SnapshotError::InvalidTag)?,
5589                stack: Default::default(),
5590                top: 0,
5591                frames: Default::default(),
5592                open_upvalues: Vec::new(),
5593                open_above: 0,
5594                resumed_by: None,
5595                host_results: Vec::new(),
5596                unwind: None,
5597                error: None,
5598                coroutine: false,
5599                closing: false,
5600                tbc: Vec::new(),
5601                charged_slots: thread.charged_slots,
5602                charged_held: thread.charged_held,
5603            })
5604            .map_err(|_| SnapshotError::LimitExceeded)?;
5605        threads.insert(thread.id, handle);
5606    }
5607    for closure in &image.native_closures {
5608        if closure.native as usize >= image.natives.len() {
5609            return Err(SnapshotError::DanglingReference);
5610        }
5611        let handle = heap
5612            .native_closures
5613            .alloc(NativeClosureObj {
5614                id: ObjectId(closure.id),
5615                native: closure.native,
5616                values: Vec::new(),
5617                state: closure.state.clone(),
5618            })
5619            .map_err(|_| SnapshotError::LimitExceeded)?;
5620        native_closures.insert(closure.id, handle);
5621    }
5622    // Host values are decoded into this heap only: a refusal anywhere
5623    // drops the heap and every value decoded so far (ADR 0045).
5624    let mut userdata = std::collections::HashMap::<u64, Handle<crate::heap::UserdataObj>>::new();
5625    for image_userdata in &image.userdata {
5626        let payload = realize_payload(
5627            &image_userdata.payload,
5628            image_userdata.charge,
5629            registry,
5630            capabilities,
5631            image_userdata.id,
5632            completed_file_close(image, image_userdata.id),
5633        )?;
5634        let handle = heap
5635            .userdata
5636            .alloc(crate::heap::UserdataObj {
5637                id: ObjectId(image_userdata.id),
5638                metatable: None,
5639                user_values: vec![Value::Nil; image_userdata.user_values.len()].into_boxed_slice(),
5640                payload,
5641                charge: image_userdata.charge,
5642                finalize: false,
5643            })
5644            .map_err(|_| SnapshotError::LimitExceeded)?;
5645        userdata.insert(image_userdata.id, handle);
5646    }
5647    let handles = Handles {
5648        strings: &strings,
5649        tables: &tables,
5650        closures: &closures,
5651        threads: &threads,
5652        native_closures: &native_closures,
5653        userdata: &userdata,
5654        natives: image.natives.len(),
5655        next_object_id: image.next_object_id,
5656    };
5657    for image_userdata in &image.userdata {
5658        let values = image_userdata
5659            .user_values
5660            .iter()
5661            .map(|value| dec_value(&handles, value))
5662            .collect::<Result<Vec<_>, _>>()?;
5663        let metatable = if image_userdata.metatable == 0 {
5664            None
5665        } else {
5666            Some(
5667                *tables
5668                    .get(&image_userdata.metatable)
5669                    .ok_or(SnapshotError::DanglingReference)?,
5670            )
5671        };
5672        let object = heap
5673            .userdata
5674            .get_mut(userdata[&image_userdata.id])
5675            .ok_or(SnapshotError::DanglingReference)?;
5676        object.user_values = values.into_boxed_slice();
5677        object.metatable = metatable;
5678    }
5679    for closure in &image.native_closures {
5680        let values = closure
5681            .values
5682            .iter()
5683            .map(|value| dec_value(&handles, value))
5684            .collect::<Result<Vec<_>, _>>()?;
5685        let entry = registry
5686            .native_slot(&image.natives[closure.native as usize])
5687            .and_then(|slot| registry.native(slot))
5688            .ok_or(SnapshotError::UnknownHostSymbol)?;
5689        let fits = match entry.builtin {
5690            Some(builtin) => crate::library::closure_fits(&heap, builtin, &values, &closure.state),
5691            None => values.len() <= 255 && closure.state.is_empty(),
5692        };
5693        if !fits {
5694            return Err(SnapshotError::InvalidStructure);
5695        }
5696        let handle = native_closures[&closure.id];
5697        heap.native_closures
5698            .get_mut(handle)
5699            .ok_or(SnapshotError::DanglingReference)?
5700            .values = values;
5701    }
5702
5703    for proto in &image.protos {
5704        let handle = *protos
5705            .get(&proto.id)
5706            .ok_or(SnapshotError::DanglingReference)?;
5707        let children = proto
5708            .children
5709            .iter()
5710            .map(|id| {
5711                protos
5712                    .get(id)
5713                    .copied()
5714                    .ok_or(SnapshotError::DanglingReference)
5715            })
5716            .collect::<Result<Vec<_>, _>>()?;
5717        heap.protos
5718            .get_mut(handle)
5719            .ok_or(SnapshotError::DanglingReference)?
5720            .children = children;
5721    }
5722    for closure in &image.closures {
5723        let handle = *closures
5724            .get(&closure.id)
5725            .ok_or(SnapshotError::DanglingReference)?;
5726        let ups = closure
5727            .upvalues
5728            .iter()
5729            .map(|id| {
5730                upvalues
5731                    .get(id)
5732                    .copied()
5733                    .ok_or(SnapshotError::DanglingReference)
5734            })
5735            .collect::<Result<Vec<_>, _>>()?;
5736        heap.closures
5737            .get_mut(handle)
5738            .ok_or(SnapshotError::DanglingReference)?
5739            .upvalues = ups;
5740    }
5741    for upvalue in &image.upvalues {
5742        let handle = *upvalues
5743            .get(&upvalue.id)
5744            .ok_or(SnapshotError::DanglingReference)?;
5745        let state = match &upvalue.state {
5746            UpImageState::Closed(value) => UpvalueState::Closed(dec_value(&handles, value)?),
5747            UpImageState::Open { thread, slot } => {
5748                let thread = *threads
5749                    .get(thread)
5750                    .ok_or(SnapshotError::DanglingReference)?;
5751                UpvalueState::Open {
5752                    thread,
5753                    slot: *slot,
5754                }
5755            }
5756        };
5757        heap.upvalues
5758            .get_mut(handle)
5759            .ok_or(SnapshotError::DanglingReference)?
5760            .state = state;
5761    }
5762    for table in &image.tables {
5763        let handle = *tables
5764            .get(&table.id)
5765            .ok_or(SnapshotError::DanglingReference)?;
5766        if table.metatable != 0 {
5767            let metatable = *tables
5768                .get(&table.metatable)
5769                .ok_or(SnapshotError::DanglingReference)?;
5770            heap.tables
5771                .get_mut(handle)
5772                .ok_or(SnapshotError::DanglingReference)?
5773                .metatable = Some(metatable);
5774        }
5775        let mut slots = Vec::with_capacity(table.slots.len());
5776        for slot in &table.slots {
5777            match &slot.body {
5778                SlotBody::Live { key, value } => {
5779                    let key_value = dec_value(&handles, key)?;
5780                    let stored = dec_value(&handles, value)?;
5781                    if matches!(stored, Value::Nil) {
5782                        return Err(SnapshotError::InvalidStructure);
5783                    }
5784                    let normalized = heap
5785                        .normalize_value(key_value)
5786                        .map_err(|_| SnapshotError::InvalidStructure)?;
5787                    slots.push(Slot::live(normalized, key_value, stored));
5788                }
5789                SlotBody::Dead(key) => slots.push(Slot::dead(realized_dead_key(key)?)),
5790            }
5791        }
5792        heap.tables
5793            .get_mut(handle)
5794            .ok_or(SnapshotError::DanglingReference)?
5795            .table
5796            .restore(slots);
5797    }
5798    for thread in &image.threads {
5799        let handle = *threads
5800            .get(&thread.id)
5801            .ok_or(SnapshotError::DanglingReference)?;
5802        let stack = thread
5803            .stack
5804            .iter()
5805            .map(|value| dec_value(&handles, value))
5806            .collect::<Result<Vec<_>, _>>()?;
5807        let results = thread
5808            .results
5809            .iter()
5810            .map(|value| dec_value(&handles, value))
5811            .collect::<Result<Vec<_>, _>>()?;
5812        let resumed_by = if thread.resumed_by == 0 {
5813            None
5814        } else {
5815            Some(
5816                *threads
5817                    .get(&thread.resumed_by)
5818                    .ok_or(SnapshotError::DanglingReference)?,
5819            )
5820        };
5821        let mut frames = Vec::new();
5822        for frame in &thread.frames {
5823            let closure = *closures
5824                .get(&frame.closure)
5825                .ok_or(SnapshotError::DanglingReference)?;
5826            let pending = match &frame.pending {
5827                PendingImage::None => None,
5828                PendingImage::Prepared {
5829                    sequence,
5830                    symbol,
5831                    arg,
5832                    dest,
5833                } => Some(Pending::Prepared {
5834                    sequence: *sequence,
5835                    symbol: symbol.clone(),
5836                    arg: *arg,
5837                    dest: *dest,
5838                }),
5839                PendingImage::Waiting {
5840                    sequence,
5841                    symbol,
5842                    arg,
5843                    dest,
5844                    wait_key,
5845                } => Some(Pending::Waiting {
5846                    sequence: *sequence,
5847                    symbol: symbol.clone(),
5848                    arg: *arg,
5849                    dest: *dest,
5850                    wait_key: *wait_key,
5851                }),
5852                PendingImage::Resuming {
5853                    child,
5854                    dest,
5855                    nresults,
5856                } => Some(Pending::Resuming {
5857                    child: *threads.get(child).ok_or(SnapshotError::DanglingReference)?,
5858                    dest: *dest,
5859                    nresults: *nresults,
5860                }),
5861                PendingImage::Assigning { src, nvalues, next } => Some(Pending::Assigning {
5862                    src: *src,
5863                    nvalues: *nvalues,
5864                    next: *next,
5865                }),
5866                PendingImage::NativePrepared { sequence } => Some(Pending::NativePrepared {
5867                    sequence: *sequence,
5868                }),
5869                PendingImage::Deferred => Some(Pending::Deferred),
5870                PendingImage::Capability {
5871                    sequence,
5872                    wait_key,
5873                    completed,
5874                } => Some(Pending::Capability {
5875                    sequence: *sequence,
5876                    wait_key: *wait_key,
5877                    completed: *completed,
5878                }),
5879                PendingImage::NativeWaiting { sequence, wait_key } => {
5880                    Some(Pending::NativeWaiting {
5881                        sequence: *sequence,
5882                        wait_key: *wait_key,
5883                    })
5884                }
5885            };
5886            let mut targets = Vec::new();
5887            for target in &frame.targets {
5888                targets.push(match target {
5889                    TargetImage::Register(slot) => AssignTarget::Register(*slot),
5890                    TargetImage::Field { table, key } => AssignTarget::Field {
5891                        table: dec_value(&handles, table)?,
5892                        key: dec_value(&handles, key)?,
5893                    },
5894                });
5895            }
5896            frames.push(Frame {
5897                closure,
5898                pc: frame.pc,
5899                base: frame.base,
5900                limit: frame.limit,
5901                nresults: frame.nresults,
5902                vararg_len: frame.vararg_len,
5903                flags: u8::from(frame.tail) | (u8::from(frame.return_hook) * 2),
5904                cold: crate::heap::FrameCold {
5905                    pending,
5906                    wait_request: frame
5907                        .wait_request
5908                        .as_ref()
5909                        .map(|(operation, payload)| {
5910                            Ok::<_, SnapshotError>(crate::heap::HostWait {
5911                                operation: operation.clone(),
5912                                payload: payload
5913                                    .iter()
5914                                    .map(|v| dec_value(&handles, v))
5915                                    .collect::<Result<Vec<_>, _>>()?,
5916                            })
5917                        })
5918                        .transpose()?,
5919                    targets,
5920                    meta: frame
5921                        .meta
5922                        .as_ref()
5923                        .map(|meta| realize_meta(meta, &|value| dec_value(&handles, value)))
5924                        .transpose()?,
5925                    boundary: match &frame.boundary {
5926                        None => None,
5927                        Some(BoundaryImage::Protect {
5928                            func,
5929                            advance_caller,
5930                            handler,
5931                        }) => Some(crate::heap::Boundary::Protect {
5932                            func: *func,
5933                            advance_caller: *advance_caller,
5934                            handler: handler
5935                                .as_ref()
5936                                .map(|value| dec_value(&handles, value))
5937                                .transpose()?,
5938                        }),
5939                        Some(BoundaryImage::Handler {
5940                            slot,
5941                            protect,
5942                            target,
5943                            depth,
5944                            fault,
5945                        }) => Some(crate::heap::Boundary::Handler {
5946                            slot: *slot,
5947                            protect: *protect,
5948                            target: *target,
5949                            depth: *depth,
5950                            fault: crate::id::LuaFault::from_tag(*fault)
5951                                .ok_or(SnapshotError::InvalidTag)?,
5952                        }),
5953                        Some(BoundaryImage::Builtin {
5954                            func,
5955                            passed,
5956                            advance_caller,
5957                            task,
5958                        }) => Some(crate::heap::Boundary::Builtin {
5959                            func: *func,
5960                            passed: *passed,
5961                            advance_caller: *advance_caller,
5962                            task: task.clone(),
5963                        }),
5964                        Some(BoundaryImage::Native {
5965                            func,
5966                            passed,
5967                            advance_caller,
5968                            symbol,
5969                            tag,
5970                            kept,
5971                            sequence,
5972                            error,
5973                            resuming,
5974                            no_yield,
5975                        }) => Some(crate::heap::Boundary::Native {
5976                            func: *func,
5977                            passed: *passed,
5978                            advance_caller: *advance_caller,
5979                            symbol: *symbol,
5980                            tag: *tag,
5981                            kept: *kept,
5982                            sequence: *sequence,
5983                            resuming: *resuming,
5984                            no_yield: *no_yield,
5985                            error: error
5986                                .as_ref()
5987                                .map(|(class, value)| {
5988                                    Ok::<_, SnapshotError>((
5989                                        crate::id::LuaFault::from_tag(*class)
5990                                            .ok_or(SnapshotError::InvalidTag)?,
5991                                        dec_value(&handles, value)?,
5992                                    ))
5993                                })
5994                                .transpose()?,
5995                        }),
5996                        Some(BoundaryImage::Hook {
5997                            func,
5998                            saved_top,
5999                            target,
6000                            instruction,
6001                            after,
6002                        }) => Some(crate::heap::Boundary::Hook {
6003                            func: *func,
6004                            saved_top: *saved_top,
6005                            target: *target,
6006                            instruction: *instruction,
6007                            after: *after,
6008                        }),
6009                        Some(BoundaryImage::HookNative {
6010                            func,
6011                            passed,
6012                            callee,
6013                            advance_caller,
6014                            phase,
6015                            produced,
6016                            result,
6017                        }) => Some(crate::heap::Boundary::HookNative {
6018                            func: *func,
6019                            passed: *passed,
6020                            callee: dec_value(&handles, callee)?,
6021                            advance_caller: *advance_caller,
6022                            phase: *phase,
6023                            produced: *produced,
6024                            result: *result,
6025                        }),
6026                        Some(BoundaryImage::Finalizer { func, saved_top }) => {
6027                            Some(crate::heap::Boundary::Finalizer {
6028                                func: *func,
6029                                saved_top: *saved_top,
6030                            })
6031                        }
6032                    },
6033                }
6034                .into_box(),
6035            });
6036        }
6037        let decode = |value: &EncValue| dec_value(&handles, value);
6038        let error = match &thread.error {
6039            Some((fault, value)) => Some((
6040                crate::id::LuaFault::from_tag(*fault).ok_or(SnapshotError::InvalidTag)?,
6041                decode(value)?,
6042            )),
6043            None => None,
6044        };
6045        let unwind = thread
6046            .unwind
6047            .as_ref()
6048            .map(|unwind| realize_unwind(unwind, &decode).map(Box::new))
6049            .transpose()?;
6050        let object = heap
6051            .threads
6052            .get_mut(handle)
6053            .ok_or(SnapshotError::DanglingReference)?;
6054        object.stack = stack.into();
6055        object.top = thread.top;
6056        object.host_results = results;
6057        object.resumed_by = resumed_by;
6058        object.frames = frames.into();
6059        object.error = error;
6060        object.unwind = unwind;
6061        object.coroutine = thread.coroutine;
6062        object.closing = thread.closing;
6063        object.tbc = thread.tbc.clone();
6064        // A thread is charged at least what it holds (ADR 0051).
6065        if object.extent() > object.charged_slots
6066            || object.charged_slots > image.max_stack_slots
6067            || object.held_bytes() > object.charged_held
6068            || object.charged_held > image.gc.quota
6069        {
6070            return Err(SnapshotError::InvalidStructure);
6071        }
6072    }
6073    for thread in &image.threads {
6074        if let Some(hook) = &thread.hook {
6075            let owner = *handles
6076                .threads
6077                .get(&thread.id)
6078                .ok_or(SnapshotError::DanglingReference)?;
6079            heap.hooks.insert(
6080                ObjectId(thread.id),
6081                realize_hook(hook, owner, registry, &|v| dec_value(&handles, v))?,
6082            );
6083        }
6084    }
6085    heap.reserved = image
6086        .reserved
6087        .iter()
6088        .map(|id| {
6089            strings
6090                .get(id)
6091                .copied()
6092                .ok_or(SnapshotError::DanglingReference)
6093        })
6094        .collect::<Result<_, _>>()?;
6095    // Rebuild open-upvalue lists from upvalue objects. Do it with copied triples
6096    // so we can mutate threads afterward.
6097    let opens: Vec<(u32, u32, Handle<ThreadObj>, u32)> = heap
6098        .upvalues
6099        .iter()
6100        .filter_map(|(index, generation, upvalue)| match upvalue.state {
6101            UpvalueState::Open { thread, slot } => Some((index, generation, thread, slot)),
6102            UpvalueState::Closed(_) => None,
6103        })
6104        .collect();
6105    for (index, generation, thread, slot) in opens {
6106        let up_handle = Handle::new(index, generation);
6107        heap.threads
6108            .get_mut(thread)
6109            .ok_or(SnapshotError::DanglingReference)?
6110            .push_open(slot, up_handle);
6111    }
6112
6113    for (slot, id) in heap.type_metatables.iter_mut().zip(image.type_metatables) {
6114        *slot = if id == 0 {
6115            None
6116        } else {
6117            Some(*tables.get(&id).ok_or(SnapshotError::DanglingReference)?)
6118        };
6119    }
6120    heap.registry = if image.registry == 0 {
6121        None
6122    } else {
6123        Some(
6124            *tables
6125                .get(&image.registry)
6126                .ok_or(SnapshotError::DanglingReference)?,
6127        )
6128    };
6129    heap.globals = if image.globals == 0 {
6130        None
6131    } else {
6132        Some(
6133            *tables
6134                .get(&image.globals)
6135                .ok_or(SnapshotError::DanglingReference)?,
6136        )
6137    };
6138    heap.active = if image.active == 0 {
6139        None
6140    } else {
6141        Some(
6142            *threads
6143                .get(&image.active)
6144                .ok_or(SnapshotError::DanglingReference)?,
6145        )
6146    };
6147    heap.entry = if image.entry == 0 {
6148        None
6149    } else {
6150        Some(
6151            *threads
6152                .get(&image.entry)
6153                .ok_or(SnapshotError::DanglingReference)?,
6154        )
6155    };
6156    heap.next_object_id = image.next_object_id;
6157    heap.natives = image.natives.clone();
6158    let fin_ref = |heap: &mut Heap, id: &u64| -> Result<crate::heap::FinRef, SnapshotError> {
6159        let fin = if let Some(handle) = tables.get(id) {
6160            heap.tables
6161                .get_mut(*handle)
6162                .ok_or(SnapshotError::DanglingReference)?
6163                .finalize = true;
6164            crate::heap::FinRef::Table(*handle)
6165        } else {
6166            let handle = *userdata.get(id).ok_or(SnapshotError::DanglingReference)?;
6167            heap.userdata
6168                .get_mut(handle)
6169                .ok_or(SnapshotError::DanglingReference)?
6170                .finalize = true;
6171            crate::heap::FinRef::Userdata(handle)
6172        };
6173        Ok(fin)
6174    };
6175    for id in &image.finalizers.registered {
6176        let fin = fin_ref(&mut heap, id)?;
6177        heap.finalizers.registered.push(fin);
6178    }
6179    heap.finalizers.old_until = image.finalizers.old_until;
6180    heap.finalizers.new_from = image.finalizers.new_from;
6181    for id in &image.finalizers.pending {
6182        let fin = fin_ref(&mut heap, id)?;
6183        heap.finalizers.pending.push_back(fin);
6184    }
6185    heap.finalizers.running = image.finalizers.running;
6186    heap.finalizers.closing = image.finalizers.closing;
6187    heap.finalizers.exit = image.finalizers.exit;
6188    heap.finalizers.closed = Status::from_u8(image.finalizers.closed);
6189    heap.finalizers.close_closure = if image.finalizers.close_closure == 0 {
6190        None
6191    } else {
6192        Some(
6193            *closures
6194                .get(&image.finalizers.close_closure)
6195                .ok_or(SnapshotError::DanglingReference)?,
6196        )
6197    };
6198    // The runtime never holds more objects than its limit, but for the
6199    // closure closing makes (ADR 0048).
6200    let close_room = if image.finalizers.close_closure != 0 {
6201        crate::runtime::finalize_close_objects()
6202    } else {
6203        0
6204    };
6205    if heap.live_objects() > within.max_objects.saturating_add(close_room) {
6206        return Err(SnapshotError::LimitExceeded);
6207    }
6208    realize_collector(image, &mut heap, &handles, &protos, &upvalues)?;
6209    // A host may have grown its userdata past the quota (ADR 0042): that
6210    // heap restores under a quota as large, never under a smaller one.
6211    if within.max_logical_heap < image.gc.quota && heap.gc.used > within.max_logical_heap {
6212        return Err(SnapshotError::LimitExceeded);
6213    }
6214    heap.gc.quota = within.max_logical_heap;
6215
6216    Ok(Runtime::from_restored(crate::runtime::RestoredParts {
6217        registry: registry.clone(),
6218        heap,
6219        effect_domain: image.effect_domain,
6220        next_sequence: image.next_sequence,
6221        fuel_consumed: image.fuel_consumed,
6222        fuel_limit: image.fuel_limit,
6223        max_objects: within.max_objects,
6224        max_snapshot: within.max_snapshot_bytes,
6225        max_stack_slots: within.max_stack_slots,
6226        last_completed_wait: image.last_completed_wait,
6227        completed_waits: image.completed_waits.iter().copied().collect(),
6228        host_call: image.host_call,
6229        callback_failed: image.callback_failed,
6230        trap: trap_from(image.trap)?,
6231    }))
6232}
6233
6234/// The collector as it was (ADR 0050): marks, lists, and phase. Run once
6235/// every object is made, before the arenas take the phase's policy.
6236fn realize_collector(
6237    image: &Image,
6238    heap: &mut Heap,
6239    handles: &Handles<'_>,
6240    protos: &std::collections::HashMap<u64, Handle<Proto>>,
6241    upvalues: &std::collections::HashMap<u64, Handle<UpvalueObj>>,
6242) -> Result<(), SnapshotError> {
6243    use crate::gc::{Atomic, How, Phase, Scan, WeakTable};
6244    use crate::heap::TraceRef;
6245    let c = &image.collector;
6246    let object = |id: u64| -> Result<TraceRef, SnapshotError> {
6247        let found = |kind, index| Some(TraceRef { kind, index });
6248        handles
6249            .strings
6250            .get(&id)
6251            .and_then(|handle| found(Kind::String, handle.index))
6252            .or_else(|| {
6253                handles
6254                    .tables
6255                    .get(&id)
6256                    .and_then(|handle| found(Kind::Table, handle.index))
6257            })
6258            .or_else(|| {
6259                protos
6260                    .get(&id)
6261                    .and_then(|handle| found(Kind::Proto, handle.index))
6262            })
6263            .or_else(|| {
6264                upvalues
6265                    .get(&id)
6266                    .and_then(|handle| found(Kind::Upvalue, handle.index))
6267            })
6268            .or_else(|| {
6269                handles
6270                    .closures
6271                    .get(&id)
6272                    .and_then(|handle| found(Kind::Closure, handle.index))
6273            })
6274            .or_else(|| {
6275                handles
6276                    .threads
6277                    .get(&id)
6278                    .and_then(|handle| found(Kind::Thread, handle.index))
6279            })
6280            .or_else(|| {
6281                handles
6282                    .native_closures
6283                    .get(&id)
6284                    .and_then(|handle| found(Kind::NativeClosure, handle.index))
6285            })
6286            .or_else(|| {
6287                handles
6288                    .userdata
6289                    .get(&id)
6290                    .and_then(|handle| found(Kind::Userdata, handle.index))
6291            })
6292            .ok_or(SnapshotError::DanglingReference)
6293    };
6294    let table = |id: u64| -> Result<u32, SnapshotError> {
6295        handles
6296            .tables
6297            .get(&id)
6298            .map(|handle| handle.index)
6299            .ok_or(SnapshotError::DanglingReference)
6300    };
6301    let mut young = HashSet::new();
6302    for id in &c.young {
6303        let found = object(*id)?;
6304        young.insert(found);
6305        crate::heap::on_arena!(mut heap, found.kind, arena => arena.young_mut().push(found.index));
6306    }
6307    // In generational form, black and old off the young lists unless
6308    // written otherwise.
6309    if c.generational {
6310        for kind in crate::gc::KINDS {
6311            let indices: Vec<u32> = crate::heap::on_arena!(heap, kind, arena => {
6312                arena.iter().map(|(index, _, _)| index).collect()
6313            });
6314            for index in indices {
6315                let found = TraceRef { kind, index };
6316                if !young.contains(&found) {
6317                    heap.set_mark(found, crate::heap::mark::BLACK);
6318                    heap.set_age(found, crate::heap::age::OLD);
6319                }
6320            }
6321        }
6322    }
6323    for (id, mark, age) in &c.marks {
6324        let found = object(*id)?;
6325        heap.set_mark(found, *mark);
6326        heap.set_age(found, *age);
6327    }
6328    for (id, age) in &c.ages {
6329        let found = object(*id)?;
6330        heap.set_mark(found, c.white);
6331        heap.set_age(found, *age);
6332    }
6333    let revisit = c
6334        .revisit
6335        .iter()
6336        .map(|id| object(*id))
6337        .collect::<Result<Vec<_>, _>>()?;
6338    let touched = c
6339        .touched
6340        .iter()
6341        .map(|id| object(*id))
6342        .collect::<Result<Vec<_>, _>>()?;
6343    let collector = &mut heap.collector;
6344    collector.generational = c.generational;
6345    collector.minor = c.minor;
6346    collector.to_old = c.to_old;
6347    collector.decide =
6348        crate::gc::Decide::from_tag(c.decide).ok_or(SnapshotError::InvalidStructure)?;
6349    collector.unreleased = c.unreleased;
6350    collector.promoted = c.promoted;
6351    collector.revisit = revisit;
6352    collector.touched = touched;
6353    collector.phase = match (c.phase, Atomic::from_tag(c.atomic)) {
6354        (0, _) => Phase::Pause,
6355        (1, _) => Phase::Begin,
6356        (2, _) => Phase::Propagate,
6357        (3, Some(step)) => Phase::Atomic(step),
6358        (4, _) => Phase::Sweep,
6359        (5, _) => Phase::Touched,
6360        _ => return Err(SnapshotError::InvalidStructure),
6361    };
6362    collector.gray = c
6363        .gray
6364        .iter()
6365        .map(|id| object(*id))
6366        .collect::<Result<_, _>>()?;
6367    collector.scan = match c.scan {
6368        Some((id, pos, how, keys, values)) => Some(Scan {
6369            object: object(id)?,
6370            pos,
6371            how: match how {
6372                0 => How::Object,
6373                1 => How::Entries { keys, values },
6374                2 => How::Ephemeron,
6375                _ => return Err(SnapshotError::InvalidTag),
6376            },
6377        }),
6378        None => None,
6379    };
6380    collector.weak = c
6381        .weak
6382        .iter()
6383        .map(|(id, keys, values)| {
6384            Ok(WeakTable {
6385                table: table(*id)?,
6386                keys: *keys,
6387                values: *values,
6388            })
6389        })
6390        .collect::<Result<_, SnapshotError>>()?;
6391    collector.late = c.late;
6392    collector.ephemerons = c
6393        .ephemerons
6394        .iter()
6395        .map(|id| table(*id))
6396        .collect::<Result<_, _>>()?;
6397    collector.waiting = c
6398        .waiting
6399        .iter()
6400        .map(|(key, values)| {
6401            let key = object(*key)?;
6402            Ok((
6403                (key.kind, key.index),
6404                values
6405                    .iter()
6406                    .map(|value| dec_value(handles, value))
6407                    .collect::<Result<Vec<_>, _>>()?,
6408            ))
6409        })
6410        .collect::<Result<_, SnapshotError>>()?;
6411    collector.cursor = c.cursor;
6412    collector.inner = c.inner;
6413    collector.marked_bytes = c.marked_bytes;
6414    collector.debt_base = c.debt_base;
6415    collector.marking_debt = c.marking_debt;
6416    collector.work_base = c.work_base;
6417    collector.sweep_left = c.sweep_left;
6418    collector.reset = c.reset;
6419    for id in &c.again {
6420        let found = object(*id)?;
6421        match found.kind {
6422            Kind::String => heap.strings.push_again(found.index),
6423            Kind::Table => heap.tables.push_again(found.index),
6424            Kind::Proto => heap.protos.push_again(found.index),
6425            Kind::Upvalue => heap.upvalues.push_again(found.index),
6426            Kind::Closure => heap.closures.push_again(found.index),
6427            Kind::Thread => heap.threads.push_again(found.index),
6428            Kind::NativeClosure => heap.native_closures.push_again(found.index),
6429            Kind::Userdata => heap.userdata.push_again(found.index),
6430        }
6431    }
6432    // The logical heap is counted, never read: what the objects written
6433    // count, and what the sweep running frees of those not written. (A
6434    // host's userdata may have grown past the quota; the next allocation
6435    // sees it.)
6436    heap.gc.used = crate::gc::counted_bytes(heap);
6437    crate::gc::restore_policy(heap);
6438    // No black object refers to a white one: a sweep would free what it
6439    // still reaches. In generational form, no old object refers to a
6440    // young one but those the next young collection traces.
6441    crate::gc::check_invariant(heap).map_err(|_| SnapshotError::InvalidStructure)?;
6442    crate::gc::check_gen_invariant(heap).map_err(|_| SnapshotError::InvalidStructure)
6443}
6444
6445// An acquisition can already own a host resource while its Lua userdata still
6446// says closed. Pending work must obey the same policy as installed live handles.
6447fn check_pending_resources(
6448    image: &Image,
6449    capabilities: Option<&crate::HostCapabilities>,
6450) -> Result<(), SnapshotError> {
6451    use crate::hostcaps::{CapabilityRequest as Request, CapabilityValue as Answer, HandlePolicy};
6452    for thread in &image.threads {
6453        for frame in &thread.frames {
6454            let PendingImage::Capability { completed, .. } = frame.pending else {
6455                continue;
6456            };
6457            let Some(BoundaryImage::Builtin {
6458                func,
6459                passed,
6460                task: crate::heap::Task::Io(work),
6461                ..
6462            }) = &frame.boundary
6463            else {
6464                continue;
6465            };
6466            if !matches!(work.as_ref(), crate::iolib::IoWork::Open { .. }) {
6467                continue;
6468            }
6469            let slot = u64::from(*func) + 1 + u64::from(*passed);
6470            let Some(EncValue::Userdata(file)) =
6471                usize::try_from(slot).ok().and_then(|i| thread.stack.get(i))
6472            else {
6473                return Err(SnapshotError::InvalidStructure);
6474            };
6475            let (_, payload) = frame
6476                .wait_request
6477                .as_ref()
6478                .ok_or(SnapshotError::InvalidStructure)?;
6479            let Some(EncValue::String(request)) = payload.first() else {
6480                return Err(SnapshotError::InvalidStructure);
6481            };
6482            let request = Request::from_bytes(
6483                image
6484                    .string(*request)
6485                    .ok_or(SnapshotError::DanglingReference)?,
6486            )
6487            .map_err(|_| SnapshotError::InvalidStructure)?;
6488            if !matches!(
6489                request,
6490                Request::FilesystemOpen { .. }
6491                    | Request::FilesystemTempFile
6492                    | Request::ProcessPopen { .. }
6493            ) {
6494                return Err(SnapshotError::InvalidStructure);
6495            }
6496            let resource = if completed {
6497                let Some(EncValue::String(result)) = payload.get(2) else {
6498                    return Err(SnapshotError::InvalidStructure);
6499                };
6500                match crate::hostcaps::protocol::decode(
6501                    image
6502                        .string(*result)
6503                        .ok_or(SnapshotError::DanglingReference)?,
6504                )
6505                .map_err(|_| SnapshotError::InvalidStructure)?
6506                {
6507                    Ok(Answer::Resource(id)) => Some(id),
6508                    Err(_) => continue,
6509                    _ => return Err(SnapshotError::InvalidStructure),
6510                }
6511            } else {
6512                None
6513            };
6514            let object = ObjectId(*file);
6515            let state = image
6516                .userdata
6517                .iter()
6518                .find(|u| u.id == *file)
6519                .and_then(|u| match &u.payload {
6520                    PayloadImage::File(f) => Some(f),
6521                    _ => None,
6522                })
6523                .ok_or(SnapshotError::InvalidStructure)?;
6524            let crate::iolib::IoWork::Open { path, action } = work.as_ref() else {
6525                unreachable!()
6526            };
6527            let expected = if *action == 4 {
6528                Request::ProcessPopen {
6529                    cmd: path.clone(),
6530                    mode: if state.mode.read {
6531                        crate::PipeMode::Read
6532                    } else {
6533                        crate::PipeMode::Write
6534                    },
6535                }
6536            } else if state.kind == 1 {
6537                Request::FilesystemTempFile
6538            } else {
6539                Request::FilesystemOpen {
6540                    path: path.clone(),
6541                    mode: state.mode,
6542                }
6543            };
6544            if request != expected {
6545                return Err(SnapshotError::InvalidStructure);
6546            }
6547            if let Some(id) = resource && image.userdata.iter().any(|u| matches!(&u.payload, PayloadImage::File(f) if !f.closed && f.kind < 2 && f.id == id)) {
6548                return Err(SnapshotError::InvalidStructure);
6549            }
6550            if state.policy == HandlePolicy::Refuse
6551                || matches!(request, Request::ProcessPopen { .. })
6552            {
6553                return Err(SnapshotError::NonPortableResource { object });
6554            }
6555            let failed = |error| SnapshotError::Rebind {
6556                symbol: "FILE*",
6557                object,
6558                error: crate::RebindError(error),
6559            };
6560            let Some(capabilities) = capabilities else {
6561                continue;
6562            };
6563            let fs = capabilities
6564                .filesystem
6565                .as_ref()
6566                .ok_or_else(|| failed("filesystem unavailable"))?;
6567            let policy = crate::hostcaps::filesystem_policy(fs.as_ref())
6568                .map_err(|_| failed("filesystem policy panicked"))?;
6569            if policy != HandlePolicy::Rebind {
6570                return Err(SnapshotError::NonPortableResource { object });
6571            }
6572            if let Some(id) = resource {
6573                std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| fs.rebind(id)))
6574                    .map_err(|_| failed("filesystem rebind panicked"))?
6575                    .map_err(|_| failed("file resource unavailable"))?;
6576            }
6577        }
6578    }
6579    Ok(())
6580}
6581
6582// Completion may already have released a host resource while the builtin has
6583// not yet consumed its journaled answer and marked the Lua handle closed.
6584// Rebinding that completed close would incorrectly reject a valid checkpoint.
6585fn completed_file_close(image: &Image, object: u64) -> bool {
6586    image.threads.iter().any(|thread| thread.frames.iter().any(|frame| {
6587        let PendingImage::Capability { completed: true, .. } = frame.pending else { return false; };
6588        let Some(BoundaryImage::Builtin { func, passed, task: crate::heap::Task::Io(task), .. }) = &frame.boundary else { return false; };
6589        if !matches!(task.as_ref(), crate::iolib::IoWork::Close { .. }) { return false; }
6590        let slot = u64::from(*func) + 1 + u64::from(*passed);
6591        if !matches!(usize::try_from(slot).ok().and_then(|i| thread.stack.get(i)), Some(EncValue::Userdata(id)) if *id == object) { return false; }
6592        let Some(wait) = &frame.wait_request else { return false; };
6593        let Some(EncValue::String(request)) = wait.1.first() else { return false; };
6594        let Some(bytes) = image.string(*request) else { return false; };
6595        matches!(crate::CapabilityRequest::from_bytes(bytes), Ok(crate::CapabilityRequest::FilesystemClose { id })
6596            if image.userdata.iter().any(|u| u.id == object && matches!(&u.payload, PayloadImage::File(f) if f.id == id && f.kind < 2)))
6597    }))
6598}
6599
6600/// A userdata's payload from its image. A host value's type must be
6601/// registered as portable under the same symbol; its codec must accept
6602/// the bytes and give a value that counts no more than was recorded.
6603fn realize_payload(
6604    payload: &PayloadImage,
6605    charge: u64,
6606    registry: &HostRegistry,
6607    capabilities: &crate::HostCapabilities,
6608    id: u64,
6609    released: bool,
6610) -> Result<crate::userdata::Payload, SnapshotError> {
6611    Ok(match payload {
6612        PayloadImage::File(file) => {
6613            if !file.closed && !released {
6614                if file.kind < 2 {
6615                    let fs = capabilities
6616                        .filesystem
6617                        .as_ref()
6618                        .ok_or(SnapshotError::Rebind {
6619                            symbol: "FILE*",
6620                            object: ObjectId(id),
6621                            error: crate::RebindError("filesystem unavailable"),
6622                        })?;
6623                    let policy = crate::hostcaps::filesystem_policy(fs.as_ref()).map_err(|_| {
6624                        SnapshotError::Rebind {
6625                            symbol: "FILE*",
6626                            object: ObjectId(id),
6627                            error: crate::RebindError("filesystem policy panicked"),
6628                        }
6629                    })?;
6630                    if policy != crate::hostcaps::HandlePolicy::Rebind {
6631                        return Err(SnapshotError::NonPortableResource {
6632                            object: ObjectId(id),
6633                        });
6634                    }
6635                    // Rebind is a validation/reacquisition boundary, never an IO effect.
6636                    std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| fs.rebind(file.id)))
6637                        .map_err(|_| SnapshotError::Rebind {
6638                            symbol: "FILE*",
6639                            object: ObjectId(id),
6640                            error: crate::RebindError("filesystem rebind panicked"),
6641                        })?
6642                        .map_err(|_| SnapshotError::Rebind {
6643                            symbol: "FILE*",
6644                            object: ObjectId(id),
6645                            error: crate::RebindError("file resource unavailable"),
6646                        })?;
6647                } else if capabilities.stdio.is_none() {
6648                    return Err(SnapshotError::Rebind {
6649                        symbol: "FILE*",
6650                        object: ObjectId(id),
6651                        error: crate::RebindError("standard streams unavailable"),
6652                    });
6653                }
6654            }
6655            crate::userdata::Payload::File(Box::new(file.clone()))
6656        }
6657        PayloadImage::Bytes(bytes) => {
6658            crate::userdata::Payload::Bytes(bytes.clone().into_boxed_slice())
6659        }
6660        PayloadImage::Host { symbol, bytes } => {
6661            let host = registry
6662                .userdata_type(symbol)
6663                .ok_or(SnapshotError::UnknownUserdataType)?;
6664            let crate::userdata::Policy::Portable(codec) = host.policy else {
6665                return Err(SnapshotError::UserdataPolicyMismatch);
6666            };
6667            let (value, size) = (codec.decode)(bytes).ok_or(SnapshotError::UserdataDecode)?;
6668            if size > charge {
6669                return Err(SnapshotError::UserdataCharge);
6670            }
6671            crate::userdata::Payload::Host {
6672                symbol: host.symbol,
6673                value,
6674            }
6675        }
6676        PayloadImage::Rebind { symbol, key } => {
6677            if key.len() > crate::MAX_REBIND_KEY {
6678                return Err(SnapshotError::LimitExceeded);
6679            }
6680            let host = registry
6681                .userdata_type(symbol)
6682                .ok_or(SnapshotError::UnknownUserdataType)?;
6683            let crate::userdata::Policy::Rebind { rebind, .. } = host.policy else {
6684                return Err(SnapshotError::UserdataPolicyMismatch);
6685            };
6686            let (value, size) =
6687                rebind(key, capabilities.env()).map_err(|error| SnapshotError::Rebind {
6688                    symbol: host.symbol,
6689                    object: ObjectId(id),
6690                    error,
6691                })?;
6692            if size > charge {
6693                return Err(SnapshotError::UserdataCharge);
6694            }
6695            crate::userdata::Payload::Host {
6696                symbol: host.symbol,
6697                value,
6698            }
6699        }
6700    })
6701}
6702
6703fn check_userdata_policies(image: &Image, registry: &HostRegistry) -> Result<(), SnapshotError> {
6704    for userdata in &image.userdata {
6705        let (symbol, policy) = match &userdata.payload {
6706            PayloadImage::Bytes(_) | PayloadImage::File(_) => continue,
6707            PayloadImage::Host { symbol, .. } => (symbol, crate::UserdataPolicy::Portable),
6708            PayloadImage::Rebind { symbol, key } => {
6709                if key.len() > crate::MAX_REBIND_KEY {
6710                    return Err(SnapshotError::LimitExceeded);
6711                }
6712                (symbol, crate::UserdataPolicy::Rebind)
6713            }
6714        };
6715        let registered = registry
6716            .userdata_policy(symbol)
6717            .ok_or(SnapshotError::UnknownUserdataType)?;
6718        if registered != policy {
6719            return Err(SnapshotError::UserdataPolicyMismatch);
6720        }
6721    }
6722    Ok(())
6723}
6724
6725type Decode<'a> = dyn Fn(&EncValue) -> Result<Value, SnapshotError> + 'a;
6726
6727fn realize_unwind(
6728    unwind: &UnwindImage,
6729    decode: &Decode<'_>,
6730) -> Result<crate::heap::Unwind, SnapshotError> {
6731    Ok(crate::heap::Unwind {
6732        error: unwind
6733            .error
6734            .as_ref()
6735            .map(|(fault, value)| {
6736                Ok::<_, SnapshotError>((
6737                    crate::id::LuaFault::from_tag(*fault).ok_or(SnapshotError::InvalidTag)?,
6738                    decode(value)?,
6739                ))
6740            })
6741            .transpose()?,
6742        phase: unwind.phase,
6743    })
6744}
6745
6746fn realize_meta(
6747    meta: &MetaImage,
6748    decode: &Decode<'_>,
6749) -> Result<crate::heap::MetaCall, SnapshotError> {
6750    use crate::heap::{CloseNext, Closing, MetaEvent};
6751    let (event, close) = match &meta.event {
6752        // A plain `Close` event has no close state; the reader never makes
6753        // one, and restore refuses it.
6754        EventImage::Plain(MetaEvent::Close) => return Err(SnapshotError::InvalidStructure),
6755        EventImage::Plain(event) => (*event, None),
6756        EventImage::Close { from, next } => (
6757            MetaEvent::Close,
6758            Some(Box::new(Closing {
6759                from: *from,
6760                next: match next {
6761                    NextImage::Advance => CloseNext::Advance,
6762                    NextImage::Return { src, produced } => CloseNext::Return {
6763                        src: *src,
6764                        produced: *produced,
6765                    },
6766                    NextImage::Unwind(unwind) => CloseNext::Unwind(realize_unwind(unwind, decode)?),
6767                },
6768            })),
6769        ),
6770    };
6771    Ok(crate::heap::MetaCall {
6772        event,
6773        slot: meta.slot,
6774        nargs: meta.nargs,
6775        phase: meta.phase,
6776        close,
6777    })
6778}
6779
6780fn check_symbols(image: &Image, registry: &HostRegistry) -> Result<(), SnapshotError> {
6781    for symbol in &image.natives {
6782        if registry.native_slot(symbol).is_none() {
6783            return Err(SnapshotError::UnknownHostSymbol);
6784        }
6785    }
6786    for thread in &image.threads {
6787        if let Some(HookImage {
6788            target: HookTargetImage::Host(symbol),
6789            ..
6790        }) = &thread.hook
6791            && registry.hook_slot(symbol).is_none()
6792        {
6793            return Err(SnapshotError::UnknownHostSymbol);
6794        }
6795        for (index, frame) in thread.frames.iter().enumerate() {
6796            if let Some(BoundaryImage::Native {
6797                symbol,
6798                resuming,
6799                func,
6800                sequence,
6801                ..
6802            }) = &frame.boundary
6803            {
6804                let name = image
6805                    .natives
6806                    .get(*symbol as usize)
6807                    .ok_or(SnapshotError::UnknownHostSymbol)?;
6808                let entry = registry
6809                    .native_slot(name)
6810                    .and_then(|slot| registry.native(slot))
6811                    .ok_or(SnapshotError::UnknownHostSymbol)?;
6812                if entry.callback.is_none()
6813                    || entry.typed.is_some()
6814                    || slot_native(image, thread.stack.get(*func as usize)) != Some(*symbol)
6815                    || sequence.is_some() != (entry.policy == crate::NativePolicy::External)
6816                    || sequence
6817                        .is_some_and(|sequence| sequence == 0 || sequence >= image.next_sequence)
6818                {
6819                    return Err(SnapshotError::InvalidStructure);
6820                }
6821                if *resuming {
6822                    if entry.policy != crate::NativePolicy::External {
6823                        return Err(SnapshotError::InvalidStructure);
6824                    }
6825                    if !matches!(frame.pending, PendingImage::NativePrepared { sequence: pending } if Some(pending) == *sequence)
6826                    {
6827                        return Err(SnapshotError::InvalidStructure);
6828                    }
6829                    continue;
6830                }
6831            }
6832            if let Some(meta) = &frame.meta {
6833                use crate::heap::MetaPhase;
6834                let external = match meta.phase {
6835                    MetaPhase::Running | MetaPhase::Idle => continue,
6836                    MetaPhase::NativePrepared { .. } => true,
6837                    MetaPhase::NativeWaiting { sequence, .. } => sequence.is_some(),
6838                };
6839                let Some(index) = slot_native(image, thread.stack.get(meta.slot as usize)) else {
6840                    return Err(SnapshotError::InvalidStructure);
6841                };
6842                let policy = native_policy(image, registry, index)?;
6843                if external != (policy == crate::host::NativePolicy::External) {
6844                    return Err(SnapshotError::InvalidStructure);
6845                }
6846                continue;
6847            }
6848            let external = match &frame.pending {
6849                PendingImage::NativePrepared { .. } => true,
6850                PendingImage::NativeWaiting { sequence, .. } => sequence.is_some(),
6851                // A deferred call is of a function the VM implements.
6852                PendingImage::Deferred => {
6853                    let slot = frame
6854                        .boundary
6855                        .as_ref()
6856                        .map(BoundaryImage::call_slot)
6857                        .ok_or(SnapshotError::InvalidStructure)?;
6858                    let Some(native) = slot_native(image, thread.stack.get(slot as usize)) else {
6859                        return Err(SnapshotError::InvalidStructure);
6860                    };
6861                    let symbol = image
6862                        .natives
6863                        .get(native as usize)
6864                        .ok_or(SnapshotError::DanglingReference)?;
6865                    let builtin = registry
6866                        .native_slot(symbol)
6867                        .and_then(|slot| registry.native(slot))
6868                        .is_some_and(|entry| entry.builtin.is_some());
6869                    if (!builtin && !matches!(frame.boundary, Some(BoundaryImage::Native { .. })))
6870                        || thread.top <= slot
6871                    {
6872                        return Err(SnapshotError::InvalidStructure);
6873                    }
6874                    continue;
6875                }
6876                _ => continue,
6877            };
6878            let policy = native_call_policy(image, registry, thread, index)?;
6879            if external != (policy == crate::host::NativePolicy::External) {
6880                return Err(SnapshotError::InvalidStructure);
6881            }
6882        }
6883    }
6884    for proto in &image.protos {
6885        for op in &proto.ops {
6886            if let Op::CallHost { symbol, .. } = op {
6887                let bytes = proto
6888                    .byte_consts
6889                    .get(*symbol as usize)
6890                    .ok_or(SnapshotError::InvalidStructure)?;
6891                let name =
6892                    std::str::from_utf8(bytes).map_err(|_| SnapshotError::InvalidStructure)?;
6893                if !registry.contains(name) {
6894                    return Err(SnapshotError::UnknownHostSymbol);
6895                }
6896            }
6897        }
6898    }
6899    for thread in &image.threads {
6900        for frame in &thread.frames {
6901            if let PendingImage::Prepared { symbol, .. } | PendingImage::Waiting { symbol, .. } =
6902                &frame.pending
6903                && !registry.contains(symbol)
6904            {
6905                return Err(SnapshotError::UnknownHostSymbol);
6906            }
6907        }
6908    }
6909    Ok(())
6910}
6911
6912/// The policy of the native a pending native call is stopped on: the frame's
6913/// instruction must be a `Call` whose callee register holds a native value.
6914/// A metamethod continuation must belong to the instruction at `pc`, carry
6915/// that event's argument count, and use scratch above the frame's registers.
6916/// A thread's error record and unwind state fit its status and frames:
6917/// a failed thread has an error, no frames, and nothing unwinding; an
6918/// unwind runs in a ready thread and pops toward a `Protect` frame.
6919/// A thread waits exactly when its top frame holds a wait, and only its top
6920/// frame may hold a prepared or waiting call. A frame that kept a wait on a
6921/// ready thread would run its instruction, or a boundary frame's borrowed
6922/// code, a second time.
6923fn validate_waits(thread: &ThreadImage) -> Result<(), SnapshotError> {
6924    use crate::heap::MetaPhase;
6925    let waiting = thread.status == crate::heap::Status::Waiting.tag();
6926    let top = thread.frames.len().checked_sub(1);
6927    let mut top_waits = false;
6928    for (index, frame) in thread.frames.iter().enumerate() {
6929        let phase = frame.meta.as_ref().map(|meta| meta.phase);
6930        let waits = matches!(
6931            frame.pending,
6932            PendingImage::Waiting { .. }
6933                | PendingImage::NativeWaiting { .. }
6934                | PendingImage::Capability {
6935                    completed: false,
6936                    ..
6937                }
6938        ) || matches!(phase, Some(MetaPhase::NativeWaiting { .. }));
6939        let prepared = matches!(
6940            frame.pending,
6941            PendingImage::Prepared { .. } | PendingImage::NativePrepared { .. }
6942        ) || matches!(phase, Some(MetaPhase::NativePrepared { .. }));
6943        let capability_ready = matches!(
6944            frame.pending,
6945            PendingImage::Capability {
6946                completed: true,
6947                ..
6948            }
6949        );
6950        if frame.wait_request.is_some() && !waits && !capability_ready {
6951            return Err(SnapshotError::InvalidStructure);
6952        }
6953        let on_top = Some(index) == top;
6954        let deferred = matches!(frame.pending, PendingImage::Deferred);
6955        if (waits && !(on_top && waiting)) || ((prepared || deferred) && (!on_top || waiting)) {
6956            return Err(SnapshotError::InvalidStructure);
6957        }
6958        top_waits |= waits && on_top;
6959    }
6960    if waiting != top_waits {
6961        return Err(SnapshotError::InvalidStructure);
6962    }
6963    Ok(())
6964}
6965
6966/// The to-be-closed list names registers of Lua frames, in declaration
6967/// order. A frame's closes that wait on an unwind wait on one popping
6968/// toward the nearest protected call below the frame, or, only while
6969/// `CloseThread` closes the thread, past every boundary. A closing thread
6970/// is a coroutine whose resumer waits for it in `CloseThread`, and its
6971/// unwind is running or waiting in a frame.
6972fn exit_scopes(image: &Image, thread: &ThreadImage) -> bool {
6973    thread.id == image.entry
6974        && image
6975            .finalizers
6976            .exit
6977            .is_some_and(|exit| exit.phase == crate::heap::ExitPhase::Scopes)
6978}
6979
6980fn validate_closes(image: &Image, thread: &ThreadImage) -> Result<(), SnapshotError> {
6981    let exit = exit_scopes(image, thread);
6982    if thread.tbc.windows(2).any(|pair| pair[0] >= pair[1]) {
6983        return Err(SnapshotError::InvalidStructure);
6984    }
6985    for slot in &thread.tbc {
6986        let owner = thread
6987            .frames
6988            .iter()
6989            .rev()
6990            .find(|frame| frame.boundary.is_none() && frame.base <= *slot);
6991        if !owner.is_some_and(|frame| *slot < frame.limit) {
6992            return Err(SnapshotError::InvalidStructure);
6993        }
6994    }
6995    let is_protect =
6996        |frame: &FrameImage| frame.boundary.as_ref().is_some_and(BoundaryImage::catches);
6997    let mut paused = false;
6998    for (index, frame) in thread.frames.iter().enumerate() {
6999        let Some(MetaImage {
7000            event:
7001                EventImage::Close {
7002                    next: NextImage::Unwind(unwind),
7003                    ..
7004                },
7005            ..
7006        }) = &frame.meta
7007        else {
7008            continue;
7009        };
7010        let below = &thread.frames[..index];
7011        let fits = match unwind.phase {
7012            crate::heap::UnwindPhase::Popping {
7013                target: Some(target),
7014            } => {
7015                below.get(target as usize).is_some_and(is_protect)
7016                    && !below[target as usize + 1..].iter().any(is_protect)
7017            }
7018            crate::heap::UnwindPhase::Popping { target: None } => {
7019                paused |= thread.closing;
7020                thread.closing || exit || below.iter().all(passes)
7021            }
7022            crate::heap::UnwindPhase::Raised => false,
7023        };
7024        if !fits || (unwind.error.is_none() && !thread.closing && !exit) {
7025            return Err(SnapshotError::InvalidStructure);
7026        }
7027    }
7028    if thread.closing {
7029        let waits = image.thread(thread.resumed_by).is_some_and(|parent| {
7030            parent.frames.last().is_some_and(|frame| {
7031                matches!(frame.pending, PendingImage::Resuming { child, nresults: 2, .. }
7032                        if child == thread.id)
7033            }) || matches!(
7034                library_wait(image, parent),
7035                Some(crate::corolib::CoFn::Close | crate::corolib::CoFn::WrapCall)
7036            )
7037        });
7038        let unwinds = paused || thread.unwind.is_some();
7039        // A close may wait on the host while it runs.
7040        let running = thread.status == crate::heap::Status::Ready.tag()
7041            || thread.status == crate::heap::Status::Waiting.tag();
7042        // A new error in a close method stops at the frame being closed:
7043        // it may target a `pcall` only above that frame.
7044        let marker = thread.frames.iter().position(|frame| {
7045            matches!(
7046                &frame.meta,
7047                Some(MetaImage {
7048                    event: EventImage::Close {
7049                        next: NextImage::Unwind(UnwindImage {
7050                            phase: crate::heap::UnwindPhase::Popping { target: None },
7051                            ..
7052                        }),
7053                        ..
7054                    },
7055                    ..
7056                })
7057            )
7058        });
7059        let aimed = match thread.unwind.as_ref().map(|unwind| unwind.phase) {
7060            Some(crate::heap::UnwindPhase::Popping {
7061                target: Some(target),
7062            }) => marker.is_some_and(|marker| marker < target as usize),
7063            _ => true,
7064        };
7065        if !thread.coroutine || !running || !waits || !unwinds || !aimed {
7066            return Err(SnapshotError::InvalidStructure);
7067        }
7068    }
7069    // Between two closes nothing runs above a frame, unless the close
7070    // raised: an unwind, or a message handler it called, is then on top.
7071    let top = thread.frames.len().saturating_sub(1);
7072    for (index, frame) in thread.frames.iter().enumerate().take(top) {
7073        let idle = matches!(
7074            &frame.meta,
7075            Some(MetaImage {
7076                event: EventImage::Close { .. },
7077                phase: crate::heap::MetaPhase::Idle,
7078                ..
7079            })
7080        );
7081        let handled = thread.frames[index + 1..]
7082            .iter()
7083            .any(|frame| matches!(frame.boundary, Some(BoundaryImage::Handler { .. })));
7084        if idle && thread.unwind.is_none() && !handled {
7085            return Err(SnapshotError::InvalidStructure);
7086        }
7087    }
7088    // The entry thread is not a coroutine: its errors unwind it.
7089    if thread.coroutine && thread.id == image.entry {
7090        return Err(SnapshotError::InvalidStructure);
7091    }
7092    Ok(())
7093}
7094
7095/// The coroutine function a thread waits in: the builtin at its top
7096/// frame's call site, when that frame has nothing else pending
7097/// (ADR 0041).
7098fn library_wait(image: &Image, thread: &ThreadImage) -> Option<crate::corolib::CoFn> {
7099    let frame = thread.frames.last()?;
7100    if !matches!(frame.pending, PendingImage::None) {
7101        return None;
7102    }
7103    let slot = match (&frame.boundary, &frame.meta) {
7104        (Some(boundary), _) => boundary.call_slot(),
7105        (None, Some(meta)) => meta.slot,
7106        (None, None) => {
7107            let proto = frame_proto(image, frame).ok()?;
7108            match proto.ops.get(frame.pc as usize)? {
7109                Op::Call { func, .. } | Op::TailCall { func, .. } => {
7110                    frame.base.checked_add(u32::from(*func))?
7111                }
7112                _ => return None,
7113            }
7114        }
7115    };
7116    let native = match thread.stack.get(slot as usize)? {
7117        EncValue::Native(index) => *index,
7118        EncValue::NativeClosure(id) => {
7119            image
7120                .native_closures
7121                .iter()
7122                .find(|closure| closure.id == *id)?
7123                .native
7124        }
7125        _ => return None,
7126    };
7127    let symbol = image.natives.get(native as usize)?;
7128    crate::corolib::COROUTINE_FUNCTIONS
7129        .iter()
7130        .find(|(_, name, _)| name == symbol)
7131        .map(|(_, _, function)| *function)
7132        .or((symbol == crate::corolib::WRAP_CALL).then_some(crate::corolib::CoFn::WrapCall))
7133}
7134
7135/// The threads that run form one chain of resumes (ADR 0041): the active
7136/// thread, the thread that resumed it, and so on down to the entry
7137/// thread, each waiting on the one above in a `Resume` or `CloseThread`
7138/// instruction, `coroutine.resume`, `coroutine.close`, or a
7139/// `coroutine.wrap` function. No other thread runs, and a coroutine never
7140/// started has a function to start in.
7141fn validate_resumers(image: &Image) -> Result<(), SnapshotError> {
7142    use crate::corolib::CoFn;
7143    use crate::heap::Status;
7144    let invalid = || SnapshotError::InvalidStructure;
7145    let find = |id: u64| image.thread(id);
7146    let runs = |thread: &ThreadImage| {
7147        thread.status == Status::Ready.tag() || thread.status == Status::Waiting.tag()
7148    };
7149    let mut chain = Vec::new();
7150    let mut on_chain = HashSet::new();
7151    let mut at = (image.active != 0).then_some(image.active);
7152    while let Some(id) = at {
7153        if !on_chain.insert(id) || chain.len() > image.threads.len() {
7154            return Err(invalid());
7155        }
7156        let thread = find(id).ok_or_else(invalid)?;
7157        chain.push(id);
7158        at = (thread.resumed_by != 0).then_some(thread.resumed_by);
7159    }
7160    if chain.last().is_some_and(|root| *root != image.entry) {
7161        return Err(invalid());
7162    }
7163    for thread in &image.threads {
7164        let in_chain = on_chain.contains(&thread.id);
7165        // A resumer runs until its child answers; nothing outside the
7166        // chain runs. The active thread itself may have finished, failed,
7167        // or yielded to the host.
7168        let waits = in_chain && thread.id != image.active;
7169        let abandoned = image.finalizers.exit.is_some_and(|exit| exit.close)
7170            && thread.id != image.entry
7171            && !in_chain;
7172        if abandoned && runs(thread) {
7173            // The interrupted coroutine chain remains frozen. Every link
7174            // still reaches main, is acyclic and names a running resumer.
7175            let mut frozen = HashSet::new();
7176            let mut cursor = thread;
7177            while cursor.id != image.entry {
7178                if !runs(cursor) || !frozen.insert(cursor.id) || cursor.resumed_by == 0 {
7179                    return Err(invalid());
7180                }
7181                cursor = find(cursor.resumed_by).ok_or_else(invalid)?;
7182            }
7183        }
7184        if !abandoned && ((runs(thread) && !in_chain) || (waits && !runs(thread))) {
7185            return Err(invalid());
7186        }
7187        // A thread linked to a resumer is running: the link goes when it
7188        // yields, returns, or fails.
7189        if thread.resumed_by != 0 && ((!in_chain && !abandoned) || !runs(thread)) {
7190            return Err(invalid());
7191        }
7192        if thread.resumed_by != 0 {
7193            let parent = find(thread.resumed_by).ok_or_else(invalid)?;
7194            let op = parent.frames.last().is_some_and(|frame| {
7195                matches!(frame.pending, PendingImage::Resuming { child, .. } if child == thread.id)
7196            });
7197            // A `wrap` function closes its coroutine only after it failed,
7198            // so that close carries the error it will raise.
7199            let carries_error = thread
7200                .unwind
7201                .as_ref()
7202                .is_none_or(|unwind| unwind.error.is_some())
7203                && thread.frames.iter().all(|frame| match &frame.meta {
7204                    Some(MetaImage {
7205                        event:
7206                            EventImage::Close {
7207                                next: NextImage::Unwind(unwind),
7208                                ..
7209                            },
7210                        ..
7211                    }) => unwind.error.is_some(),
7212                    _ => true,
7213                });
7214            let library = match library_wait(image, parent) {
7215                Some(CoFn::Resume) => !thread.closing,
7216                Some(CoFn::Close) => thread.closing,
7217                Some(CoFn::WrapCall) => !thread.closing || carries_error,
7218                _ => false,
7219            };
7220            let interrupted_main = abandoned && parent.id == image.entry;
7221            if !op && !library && !interrupted_main {
7222                return Err(invalid());
7223            }
7224        }
7225        // A suspended coroutine with frames waits in `coroutine.yield`, or
7226        // after the `Yield` instruction.
7227        if !thread.frames.is_empty() && thread.status == Status::LuaSuspended.tag() {
7228            let top = thread.frames.last().ok_or_else(invalid)?;
7229            // Or it has not run at all: a thread `NewThread` made, or an
7230            // entry thread booted suspended.
7231            let unstarted = thread.frames.len() == 1 && top.pc == 0;
7232            let after_yield = top.boundary.is_none()
7233                && top.meta.is_none()
7234                && (unstarted
7235                    || frame_proto(image, top).is_ok_and(|proto| {
7236                        top.pc
7237                            .checked_sub(1)
7238                            .and_then(|pc| proto.ops.get(pc as usize))
7239                            .is_some_and(|op| matches!(op, Op::Yield { .. }))
7240                    }));
7241            if library_wait(image, thread) != Some(CoFn::Yield)
7242                && !after_yield
7243                && !thread.hook.as_ref().is_some_and(|h| h.hook_yield)
7244            {
7245                return Err(invalid());
7246            }
7247        }
7248        // A coroutine never resumed holds its body in slot 0.
7249        if thread.frames.is_empty() && thread.status == Status::LuaSuspended.tag() {
7250            let body = matches!(
7251                thread.stack.first(),
7252                Some(EncValue::Closure(_) | EncValue::Native(_) | EncValue::NativeClosure(_))
7253            );
7254            if !thread.coroutine || !body || thread.stack.len() != 1 || thread.top != 1 {
7255                return Err(invalid());
7256            }
7257        }
7258    }
7259    Ok(())
7260}
7261
7262fn validate_error_state(
7263    thread: &ThreadImage,
7264    closing_failed: bool,
7265    exit: bool,
7266) -> Result<(), SnapshotError> {
7267    let failed = thread.status == crate::heap::Status::Failed.tag();
7268    // A failed entry thread keeps its error while the runtime closes,
7269    // ready to run the finalizers (ADR 0048).
7270    if (failed || closing_failed) != thread.error.is_some() {
7271        return Err(SnapshotError::InvalidStructure);
7272    }
7273    // A failed coroutine keeps its frames until `CloseThread` closes it;
7274    // any other failed thread was unwound.
7275    if failed
7276        && (thread.unwind.is_some()
7277            || thread.closing
7278            || (!thread.coroutine && !thread.frames.is_empty()))
7279    {
7280        return Err(SnapshotError::InvalidStructure);
7281    }
7282    if let Some(unwind) = &thread.unwind {
7283        // Only a thread close runs with no error, and never while raising.
7284        let no_error = unwind.error.is_none()
7285            && ((!thread.closing && !exit) || unwind.phase == crate::heap::UnwindPhase::Raised);
7286        if thread.status != crate::heap::Status::Ready.tag() || no_error {
7287            return Err(SnapshotError::InvalidStructure);
7288        }
7289        // The unwind pops to the nearest protected call; with none, the
7290        // thread holds no boundary at all.
7291        if let crate::heap::UnwindPhase::Popping { target } = unwind.phase {
7292            let catches =
7293                |frame: &FrameImage| frame.boundary.as_ref().is_some_and(BoundaryImage::catches);
7294            let fits = match target {
7295                Some(target) => thread.frames.get(target as usize).is_some_and(|protect| {
7296                    catches(protect) && !thread.frames[target as usize + 1..].iter().any(catches)
7297                }),
7298                None => thread.closing || exit || thread.frames.iter().all(passes),
7299            };
7300            if !fits {
7301                return Err(SnapshotError::InvalidStructure);
7302            }
7303        }
7304    }
7305    Ok(())
7306}
7307
7308/// A boundary frame sits on a frame that made the call it stands for, owns
7309/// no registers, and carries no Lua continuation of its own.
7310/// A string function's frame (ADR 0034): its work fits the strings its
7311/// arguments hold.
7312fn string_work_fits(
7313    image: &Image,
7314    thread: &ThreadImage,
7315    index: usize,
7316) -> Result<(), SnapshotError> {
7317    let Some(BoundaryImage::Builtin {
7318        func, passed, task, ..
7319    }) = &thread.frames[index].boundary
7320    else {
7321        return Ok(());
7322    };
7323    if let crate::heap::Task::Io(work) = task {
7324        let scratch = u64::from(*func) + 1 + u64::from(*passed);
7325        let file = usize::try_from(scratch)
7326            .ok()
7327            .and_then(|i| thread.stack.get(i));
7328        let state =
7329            match file {
7330                Some(EncValue::Userdata(id)) => image
7331                    .userdata
7332                    .iter()
7333                    .find(|u| u.id == *id)
7334                    .and_then(|u| match &u.payload {
7335                        PayloadImage::File(f) => Some(f),
7336                        _ => None,
7337                    }),
7338                _ => None,
7339            };
7340        let is_file = state.is_some_and(|f| match work.as_ref() {
7341            crate::iolib::IoWork::Open { .. } => {
7342                f.closed
7343                    || (thread.unwind.is_some()
7344                        && matches!(thread.frames[index].pending, PendingImage::None))
7345            }
7346            crate::iolib::IoWork::Close { .. } => {
7347                !f.closed || matches!(thread.frames[index].pending, PendingImage::None)
7348            }
7349            _ => !f.closed,
7350        });
7351        let counters = match work.as_ref() {
7352            crate::iolib::IoWork::Read {
7353                start,
7354                count,
7355                got,
7356                iterator,
7357                ..
7358            } => {
7359                *start <= 1
7360                    && *got <= (*count).max(1)
7361                    && work.held_bytes() <= image.max_string as usize
7362                    && if *iterator {
7363                        let closure = thread.stack.get(*func as usize);
7364                        matches!(closure, Some(EncValue::NativeClosure(id)) if image.native_closures.iter().any(|c| c.id == *id && c.values.len() == 1 + *count as usize && c.state.len() == 1))
7365                    } else {
7366                        *count == passed.saturating_sub(*start)
7367                    }
7368            }
7369            crate::iolib::IoWork::Write {
7370                start,
7371                next,
7372                offset,
7373                failed,
7374            } => {
7375                let slot = u64::from(*func) + 1 + u64::from(*next);
7376                let argument = usize::try_from(slot).ok().and_then(|i| thread.stack.get(i));
7377                let length = match argument {
7378                    Some(EncValue::String(id)) => image.string(*id).map(|s| s.len()),
7379                    Some(EncValue::Integer(n)) => Some(n.to_string().len()),
7380                    Some(EncValue::Float(_)) => Some(32),
7381                    _ => None,
7382                };
7383                *start <= 1
7384                    && *next >= *start
7385                    && *next <= *passed
7386                    && (*offset == 0
7387                        || (!*failed
7388                            && *next < *passed
7389                            && length.is_some_and(|n| *offset <= n as u64)))
7390            }
7391            _ => true,
7392        };
7393        return if is_file
7394            && counters
7395            && scratch + u64::from(work.scratch()) <= thread.stack.len() as u64
7396        {
7397            Ok(())
7398        } else {
7399            Err(SnapshotError::InvalidStructure)
7400        };
7401    }
7402    let crate::heap::Task::Lib(task) = task else {
7403        return Ok(());
7404    };
7405    let work = match &task.work {
7406        crate::library::Work::Str(work) => work,
7407        crate::library::Work::Package(work) => {
7408            let name = |arg: u32| -> Option<usize> {
7409                if arg >= *passed {
7410                    return None;
7411                }
7412                let slot = usize::try_from(u64::from(*func) + 1 + u64::from(arg)).ok()?;
7413                let Some(EncValue::String(id)) = thread.stack.get(slot) else {
7414                    return None;
7415                };
7416                image
7417                    .strings
7418                    .iter()
7419                    .find(|(string_id, _)| string_id == id)
7420                    .map(|(_, bytes)| bytes.len())
7421            };
7422            return if work.fits(&name) {
7423                Ok(())
7424            } else {
7425                Err(SnapshotError::InvalidStructure)
7426            };
7427        }
7428        crate::library::Work::Utf8(work) => {
7429            let len = match thread.stack.get((*func as usize).saturating_add(1)) {
7430                Some(EncValue::String(id)) => image.string(*id).map(|bytes| bytes.len()),
7431                _ => None,
7432            };
7433            let scratch = u64::from(*func) + 1 + u64::from(*passed);
7434            // Unlike a table callback's reserved scratch, every UTF-8
7435            // result counted here has already been written to the stack.
7436            let results_fit = scratch + u64::from(work.scratch()) <= thread.stack.len() as u64;
7437            return if work.fits(*passed, len)
7438                && results_fit
7439                && matches!(task.wait, crate::library::Wait::Nothing)
7440            {
7441                Ok(())
7442            } else {
7443                Err(SnapshotError::InvalidStructure)
7444            };
7445        }
7446        crate::library::Work::Os(work) => {
7447            use crate::oslib::OsFn;
7448            let arg = |n: usize| {
7449                if n < *passed as usize {
7450                    thread.stack.get(*func as usize + 1 + n)
7451                } else {
7452                    None
7453                }
7454            };
7455            let scratch = *func as usize + 1 + *passed as usize;
7456            let slot = |n: usize| thread.stack.get(scratch + n);
7457            let empty_wait = matches!(task.wait, crate::library::Wait::Nothing);
7458            let valid = match work.function {
7459                OsFn::Date => {
7460                    let format = match arg(0) {
7461                        None | Some(EncValue::Nil) => Some(b"%c".as_slice()),
7462                        Some(EncValue::String(id)) => image.string(*id),
7463                        _ if work.stage == 0 => Some(b"".as_slice()),
7464                        _ => None,
7465                    };
7466                    format.is_some_and(|format| {
7467                        let format = format.strip_prefix(b"!").unwrap_or(format);
7468                        let table = format.split(|b| *b == 0).next() == Some(b"*t");
7469                        work.pos as usize <= format.len()
7470                            && (work.stage < 4 || table)
7471                            && (work.stage < 2 || matches!(slot(7), Some(EncValue::Integer(n)) if i32::try_from(*n).is_ok()))
7472                            && (work.stage < 2 || work.stage >= 4 || matches!(slot(8), Some(EncValue::Bool(_))))
7473                            && (work.stage < 3 || matches!(slot(9), Some(EncValue::String(_)) | Some(EncValue::Table(_))))
7474                    }) && (empty_wait || work.stage >= 4 && matches!(task.wait, crate::library::Wait::Set))
7475                }
7476                OsFn::Time if work.stage > 0 => {
7477                    matches!(arg(0), Some(EncValue::Table(_)))
7478                        && (empty_wait
7479                            || match task.wait {
7480                                crate::library::Wait::Get { into } => {
7481                                    work.stage <= 7 && into == u32::from(work.stage - 1)
7482                                }
7483                                crate::library::Wait::Set => work.stage >= 12,
7484                                _ => false,
7485                            })
7486                }
7487                _ => empty_wait,
7488            };
7489            return if work.fits() && valid {
7490                Ok(())
7491            } else {
7492                Err(SnapshotError::InvalidStructure)
7493            };
7494        }
7495        crate::library::Work::Debug(work) => {
7496            let first_is_thread = *passed > 0
7497                && matches!(
7498                    usize::try_from(u64::from(*func) + 1)
7499                        .ok()
7500                        .and_then(|slot| thread.stack.get(slot)),
7501                    Some(EncValue::Thread(_))
7502                );
7503            return if work.fits(first_is_thread) {
7504                Ok(())
7505            } else {
7506                Err(SnapshotError::InvalidStructure)
7507            };
7508        }
7509        _ => return Ok(()),
7510    };
7511    let length = |value: Option<&EncValue>| -> Option<usize> {
7512        let Some(EncValue::String(id)) = value else {
7513            return None;
7514        };
7515        image
7516            .strings
7517            .iter()
7518            .find(|(string_id, _)| string_id == id)
7519            .map(|(_, bytes)| bytes.len())
7520    };
7521    let source = |source: crate::strlib::Source| -> Option<usize> {
7522        match source {
7523            crate::strlib::Source::Arg(arg) => {
7524                if arg >= *passed {
7525                    return None;
7526                }
7527                let slot = u64::from(*func) + 1 + u64::from(arg);
7528                length(thread.stack.get(usize::try_from(slot).ok()?))
7529            }
7530            // A value of the native closure being called.
7531            crate::strlib::Source::Closure(index) => {
7532                let Some(EncValue::NativeClosure(id)) = thread.stack.get(*func as usize) else {
7533                    return None;
7534                };
7535                let closure = image.native_closures.iter().find(|c| c.id == *id)?;
7536                length(closure.values.get(index as usize))
7537            }
7538        }
7539    };
7540    if work.fits(*passed, &source) {
7541        Ok(())
7542    } else {
7543        Err(SnapshotError::InvalidStructure)
7544    }
7545}
7546
7547fn validate_boundary(thread: &ThreadImage, index: usize) -> Result<(), SnapshotError> {
7548    let frame = &thread.frames[index];
7549    let Some(boundary) = &frame.boundary else {
7550        return Ok(());
7551    };
7552    // A finalizer's frame (ADR 0048) sits above a frame between two
7553    // instructions, or `collectgarbage`'s waiting for it, or nothing while
7554    // the runtime closes; its call is above everything the frame below
7555    // holds.
7556    if let BoundaryImage::Finalizer { func, saved_top } = boundary {
7557        let clean_below = match index
7558            .checked_sub(1)
7559            .and_then(|below| thread.frames.get(below))
7560        {
7561            None => true,
7562            Some(below) => {
7563                below.meta.is_none()
7564                    && below.targets.is_empty()
7565                    && matches!(below.pending, PendingImage::None)
7566                    && *func >= below.limit
7567                    && match &below.boundary {
7568                        None => true,
7569                        Some(BoundaryImage::Builtin { task, .. }) => {
7570                            matches!(task, crate::heap::Task::Collect { .. })
7571                        }
7572                        Some(_) => false,
7573                    }
7574            }
7575        };
7576        let fits = clean_below
7577            && frame.meta.is_none()
7578            && frame.targets.is_empty()
7579            && matches!(
7580                frame.pending,
7581                PendingImage::None
7582                    | PendingImage::NativePrepared { .. }
7583                    | PendingImage::NativeWaiting { .. }
7584                    | PendingImage::Capability { .. }
7585                    | PendingImage::Deferred
7586            )
7587            && frame.base == *func
7588            && frame.limit == frame.base
7589            && frame.nresults == 0
7590            && saved_top <= func
7591            && u64::from(*func) <= thread.stack.len() as u64;
7592        return if fits {
7593            Ok(())
7594        } else {
7595            Err(SnapshotError::InvalidStructure)
7596        };
7597    }
7598    if let BoundaryImage::Hook {
7599        func,
7600        saved_top,
7601        target,
7602        instruction,
7603        after,
7604    } = boundary
7605    {
7606        let fits = *target as usize + 1 == index
7607            && frame.base == *func
7608            && frame.limit == *func
7609            && frame.nresults == 0
7610            && frame.meta.is_none()
7611            && frame.targets.is_empty()
7612            && matches!(
7613                frame.pending,
7614                PendingImage::None
7615                    | PendingImage::Deferred
7616                    | PendingImage::NativePrepared { .. }
7617                    | PendingImage::NativeWaiting { .. }
7618                    | PendingImage::Capability { .. }
7619            )
7620            && saved_top <= func
7621            && (*func as usize) <= thread.stack.len()
7622            && thread.frames.get(*target as usize).is_some_and(|f| {
7623                *func >= f.limit
7624                    && match after {
7625                        crate::runtime::hooks::AfterHook::Continue => true,
7626                        crate::runtime::hooks::AfterHook::Return { src, .. } => {
7627                            f.return_hook && f.boundary.is_none() && *src >= f.base
7628                        }
7629                    }
7630            })
7631            && instruction.is_none_or(|(depth, pc, stage)| {
7632                depth < MAX_FRAMES as usize && pc < MAX_INSTRUCTIONS && (1..=2).contains(&stage)
7633            })
7634            && hook_after_fits(thread, *after);
7635        return if fits {
7636            Ok(())
7637        } else {
7638            Err(SnapshotError::InvalidStructure)
7639        };
7640    }
7641    if let BoundaryImage::HookNative {
7642        func,
7643        passed,
7644        callee,
7645        advance_caller,
7646        phase,
7647        produced,
7648        result,
7649    } = boundary
7650    {
7651        let below = index.checked_sub(1).and_then(|i| thread.frames.get(i));
7652        let fits = frame.base == func.saturating_add(1)
7653            && u64::from(frame.limit) == u64::from(*func) + 1 + u64::from(*passed)
7654            && matches!(callee, EncValue::Native(_) | EncValue::NativeClosure(_))
7655            && (*phase != 1
7656                || match (callee, thread.stack.get(*func as usize)) {
7657                    (EncValue::Native(a), Some(EncValue::Native(b))) => a == b,
7658                    (EncValue::NativeClosure(a), Some(EncValue::NativeClosure(b))) => a == b,
7659                    _ => false,
7660                })
7661            && (1..=4).contains(phase)
7662            && frame.meta.is_none()
7663            && frame.targets.is_empty()
7664            && matches!(
7665                frame.pending,
7666                PendingImage::None
7667                    | PendingImage::Deferred
7668                    | PendingImage::NativePrepared { .. }
7669                    | PendingImage::NativeWaiting { .. }
7670                    | PendingImage::Capability { .. }
7671            )
7672            && u64::from(*func) + 1 + u64::from(*passed) <= thread.stack.len() as u64
7673            && (*phase >= 3 || (*produced == 0 && *result == 0))
7674            && (*phase < 3
7675                || u64::from(*result) + u64::from(*produced) <= thread.stack.len() as u64)
7676            && below.is_some_and(|f| {
7677                if *advance_caller {
7678                    f.boundary.is_none() && f.meta.is_none() && (f.base..f.limit).contains(func)
7679                } else {
7680                    f.boundary
7681                        .as_ref()
7682                        .map(BoundaryImage::call_slot)
7683                        .or_else(|| f.meta.as_ref().map(|m| m.slot))
7684                        == Some(*func)
7685                }
7686            });
7687        return if fits {
7688            Ok(())
7689        } else {
7690            Err(SnapshotError::InvalidStructure)
7691        };
7692    }
7693    let below = index
7694        .checked_sub(1)
7695        .and_then(|below| thread.frames.get(below))
7696        .ok_or(SnapshotError::InvalidStructure)?;
7697    if frame.meta.is_some()
7698        || !frame.targets.is_empty()
7699        || !matches!(
7700            frame.pending,
7701            PendingImage::None
7702                | PendingImage::NativePrepared { .. }
7703                | PendingImage::NativeWaiting { .. }
7704                | PendingImage::Capability { .. }
7705                | PendingImage::Deferred
7706        )
7707        || frame.limit != frame.base
7708    {
7709        return Err(SnapshotError::InvalidStructure);
7710    }
7711    // The call the frame below is making, when it is not its own `Call`.
7712    let called_at = match (&below.boundary, &below.meta) {
7713        (Some(boundary), _) => Some(boundary.call_slot()),
7714        (None, Some(meta)) => Some(meta.slot),
7715        (None, None) => None,
7716    };
7717    match boundary {
7718        BoundaryImage::Protect {
7719            func,
7720            advance_caller,
7721            handler,
7722        } => {
7723            let fits = frame.base == func.saturating_add(1)
7724                && handler.as_ref().is_none_or(|value| {
7725                    matches!(
7726                        value,
7727                        EncValue::Closure(_) | EncValue::Native(_) | EncValue::NativeClosure(_)
7728                    )
7729                })
7730                && match called_at {
7731                    Some(slot) => !advance_caller && slot == *func,
7732                    None => *advance_caller && (below.base..below.limit).contains(func),
7733                };
7734            if !fits {
7735                return Err(SnapshotError::InvalidStructure);
7736            }
7737        }
7738        BoundaryImage::Handler {
7739            slot,
7740            protect,
7741            target,
7742            depth,
7743            fault,
7744        } => {
7745            // Memory errors and "error in error handling" never reach a
7746            // handler.
7747            if matches!(
7748                crate::id::LuaFault::from_tag(*fault),
7749                Some(crate::id::LuaFault::Memory | crate::id::LuaFault::ErrorHandling) | None
7750            ) {
7751                return Err(SnapshotError::InvalidStructure);
7752            }
7753            let owner = thread
7754                .frames
7755                .get(*protect as usize)
7756                .filter(|_| (*protect as usize) < index)
7757                .ok_or(SnapshotError::InvalidStructure)?;
7758            let has_handler = matches!(
7759                owner.boundary,
7760                Some(BoundaryImage::Protect {
7761                    handler: Some(_),
7762                    ..
7763                })
7764            );
7765            // The unwind goes on to the `xpcall`, or to a `load` above it
7766            // with no protected call between them (ADR 0031).
7767            let catches =
7768                |frame: &FrameImage| frame.boundary.as_ref().is_some_and(BoundaryImage::catches);
7769            let target_fits = *target == *protect
7770                || ((*protect..index as u32).contains(target)
7771                    && matches!(
7772                        thread.frames[*target as usize].boundary,
7773                        Some(BoundaryImage::Builtin { .. })
7774                    )
7775                    && thread.frames[*target as usize]
7776                        .boundary
7777                        .as_ref()
7778                        .is_some_and(BoundaryImage::catches)
7779                    && !thread.frames[*protect as usize + 1..*target as usize]
7780                        .iter()
7781                        .any(catches));
7782            if !has_handler
7783                || !target_fits
7784                || *depth == 0
7785                || u32::from(*depth) > crate::runtime::MAX_HANDLER_DEPTH
7786                || frame.base != slot.saturating_add(1)
7787            {
7788                return Err(SnapshotError::InvalidStructure);
7789            }
7790        }
7791        // A base function's arguments are on the stack below the call it
7792        // makes; its task's cursor stays within them.
7793        BoundaryImage::Builtin {
7794            func,
7795            passed,
7796            advance_caller,
7797            task,
7798        } => {
7799            // The arguments are on the stack; scratch slots need not all
7800            // be yet, as a paused `table.unpack` has filled only some.
7801            let call = u64::from(*func) + 1 + u64::from(*passed);
7802            let task_fits = match task {
7803                crate::heap::Task::HostLoad(work) => work.fits(),
7804                crate::heap::Task::DoFile => true,
7805                crate::heap::Task::Print { next } => next < passed,
7806                crate::heap::Task::ToString => *passed >= 1,
7807                crate::heap::Task::Pairs => *passed >= 1,
7808                crate::heap::Task::Ipairs { .. } => *passed >= 2,
7809                crate::heap::Task::Load { source } => {
7810                    *passed >= 1 && source.len() <= crate::limits::DEFAULT_SOURCE_BYTES
7811                }
7812                crate::heap::Task::Lib(task) => lib_task_fits(task, *passed),
7813                crate::heap::Task::Io(_) => true, // Checked against roots/counters in string_work_fits.
7814                // `collectgarbage`'s arguments, any number of them.
7815                crate::heap::Task::Collect { .. } => true,
7816            };
7817            let fits = frame.base == func.saturating_add(1)
7818                && call <= thread.stack.len() as u64
7819                && task_fits
7820                && match called_at {
7821                    Some(slot) => !advance_caller && slot == *func,
7822                    None => *advance_caller && (below.base..below.limit).contains(func),
7823                };
7824            if !fits {
7825                return Err(SnapshotError::InvalidStructure);
7826            }
7827        }
7828        BoundaryImage::Native {
7829            func,
7830            passed,
7831            advance_caller,
7832            kept,
7833            error,
7834            resuming,
7835            ..
7836        } => {
7837            let call = u64::from(*func) + 1 + u64::from(*passed) + u64::from(*kept);
7838            let fits = frame.base == func.saturating_add(1)
7839                && call <= thread.stack.len() as u64
7840                && (!resuming || matches!(frame.pending, PendingImage::NativePrepared { .. }))
7841                && (error.is_none()
7842                    || (index + 1 == thread.frames.len()
7843                        && u64::from(thread.top) == call
7844                        && matches!(
7845                            frame.pending,
7846                            PendingImage::None | PendingImage::NativePrepared { .. }
7847                        )))
7848                && match called_at {
7849                    Some(slot) => !advance_caller && slot == *func,
7850                    None => *advance_caller && (below.base..below.limit).contains(func),
7851                };
7852            if !fits {
7853                return Err(SnapshotError::InvalidStructure);
7854            }
7855        }
7856        // Checked above.
7857        BoundaryImage::Finalizer { .. }
7858        | BoundaryImage::Hook { .. }
7859        | BoundaryImage::HookNative { .. } => {}
7860    }
7861    Ok(())
7862}
7863
7864/// The prototype a frame runs.
7865fn frame_proto<'a>(image: &'a Image, frame: &FrameImage) -> Result<&'a ProtoImage, SnapshotError> {
7866    let proto_id = image
7867        .closures
7868        .iter()
7869        .find(|closure| closure.id == frame.closure)
7870        .map(|closure| closure.proto)
7871        .ok_or(SnapshotError::DanglingReference)?;
7872    image
7873        .protos
7874        .iter()
7875        .find(|proto| proto.id == proto_id)
7876        .ok_or(SnapshotError::DanglingReference)
7877}
7878
7879/// A Lua frame above another answers the call that frame is making: its
7880/// call slot, just below its arguments, is that call's slot, and it
7881/// returns what that call wants. The call is an ordinary frame's `Call`,
7882/// its `pc` just past it; a metamethod or close call; or the call a
7883/// boundary stands for. A restored frame must answer the call it claims to;
7884/// old images where a native tail call already erased its Lua frame remain
7885/// valid (ADR 0029).
7886fn validate_called(image: &Image, thread: &ThreadImage, index: usize) -> Result<(), SnapshotError> {
7887    let frame = &thread.frames[index];
7888    let Some(below) = index.checked_sub(1).map(|below| &thread.frames[below]) else {
7889        return Ok(());
7890    };
7891    if frame.boundary.is_some() {
7892        return Ok(());
7893    }
7894    let slot = frame
7895        .base
7896        .checked_sub(frame.vararg_len)
7897        .and_then(|args| args.checked_sub(1))
7898        .ok_or(SnapshotError::InvalidStructure)?;
7899    let fits = match (&below.boundary, &below.meta) {
7900        (Some(boundary), _) => {
7901            boundary.call_slot() == slot && frame.nresults == boundary.call_wants()
7902        }
7903        (None, Some(meta)) => {
7904            meta.slot == slot
7905                && meta.phase == crate::heap::MetaPhase::Running
7906                && frame.nresults == 1
7907        }
7908        (None, None) => {
7909            let proto = frame_proto(image, below)?;
7910            let call = below
7911                .pc
7912                .checked_sub(1)
7913                .and_then(|pc| proto.ops.get(pc as usize));
7914            matches!(call, Some(Op::Call { func, nresults, .. })
7915                if u64::from(below.base) + u64::from(*func) == u64::from(slot)
7916                    && *nresults == frame.nresults)
7917        }
7918    };
7919    if fits {
7920        Ok(())
7921    } else {
7922        Err(SnapshotError::InvalidStructure)
7923    }
7924}
7925
7926/// A frame's registers are its prototype's; its extra arguments, only for
7927/// a vararg prototype, sit just below them, and the call's slot below
7928/// those lies in the frame that called it (ADR 0028); an assignment's
7929/// cursor and register targets stay within the frame.
7930fn validate_frame_slots(
7931    thread: &ThreadImage,
7932    index: usize,
7933    proto: &ProtoImage,
7934) -> Result<(), SnapshotError> {
7935    let frame = &thread.frames[index];
7936    let registers_fit = frame.boundary.is_some()
7937        || u64::from(frame.limit) == u64::from(frame.base) + u64::from(proto.max_reg);
7938    // A message handler's function sits just below its boundary's base, so
7939    // the handler's frame starts where the boundary does.
7940    let start = frame.base.checked_sub(frame.vararg_len);
7941    let above_caller = start.is_some_and(|start| {
7942        index == 0 || {
7943            let below = &thread.frames[index - 1];
7944            start > below.base
7945                || (start == below.base
7946                    && matches!(below.boundary, Some(BoundaryImage::Handler { .. })))
7947                // A finalizer's frame starts at the first slot past what
7948                // the frame below holds, which is its base when it holds
7949                // nothing (ADR 0048).
7950                || (start == below.base
7951                    && matches!(frame.boundary, Some(BoundaryImage::Finalizer { .. })))
7952                // An empty interrupted native activation can put the hook
7953                // boundary exactly at its base/limit.
7954                || (start == below.base
7955                    && matches!(frame.boundary, Some(BoundaryImage::Hook { target, func, .. }) if target as usize + 1 == index && func == below.limit))
7956                || (start == below.base && matches!((&below.boundary, &frame.boundary),
7957                    (Some(BoundaryImage::HookNative { func: a, .. }), Some(BoundaryImage::Protect { func: b, .. } | BoundaryImage::Builtin { func: b, .. } | BoundaryImage::Native { func: b, .. })) if a == b))
7958        }
7959    });
7960    let varargs_fit = frame.vararg_len == 0 || (proto.vararg && frame.boundary.is_none());
7961    // Only a Lua activation is ever entered by a tail call.
7962    let varargs_fit =
7963        varargs_fit && !((frame.tail || frame.return_hook) && frame.boundary.is_some());
7964    let cursor_fits = match frame.pending {
7965        PendingImage::Assigning { next, .. } => {
7966            next >= 1 && usize::from(next) <= frame.targets.len()
7967        }
7968        _ => true,
7969    };
7970    let targets_fit = frame.targets.iter().all(|target| match target {
7971        TargetImage::Register(slot) => (frame.base..frame.limit).contains(slot),
7972        TargetImage::Field { .. } => true,
7973    });
7974    // A protected or base-function call the frame's `pc` moves past is the
7975    // frame's own `Call`.
7976    let call_fits = match thread.frames.get(index + 1).and_then(|above| {
7977        above
7978            .boundary
7979            .as_ref()
7980            .and_then(BoundaryImage::advances)
7981            .map(|func| (func, above.nresults))
7982    }) {
7983        None => true,
7984        Some((func, wanted)) => match proto.ops.get(frame.pc as usize) {
7985            Some(Op::Call {
7986                func: reg,
7987                nresults,
7988                ..
7989            }) => u64::from(frame.base) + u64::from(*reg) == u64::from(func) && *nresults == wanted,
7990            // A native tail call runs from its own Lua frame, for every
7991            // result, even when that frame has a caller (ADR 0029).
7992            Some(Op::TailCall { func: reg, .. }) => {
7993                u64::from(frame.base) + u64::from(*reg) == u64::from(func)
7994                    && wanted == crate::opcode::COUNT_OPEN
7995            }
7996            _ => false,
7997        },
7998    };
7999    if !(registers_fit && above_caller && varargs_fit && cursor_fits && targets_fit && call_fits) {
8000        return Err(SnapshotError::InvalidStructure);
8001    }
8002    Ok(())
8003}
8004
8005fn validate_meta(meta: &MetaImage, op: Op, frame: &FrameImage) -> Result<(), SnapshotError> {
8006    use crate::heap::{MetaEvent, MetaPhase};
8007    // Two operands, plus one argument per `__call` step when the handler
8008    // was a callable value. `__index` / `__newindex` handlers are functions.
8009    let callable = |base: u8| {
8010        meta.nargs >= base && u32::from(meta.nargs - base) <= crate::runtime::MAX_CALL_CHAIN
8011    };
8012    let idle = meta.phase == MetaPhase::Idle;
8013    let event = match &meta.event {
8014        EventImage::Plain(event) => *event,
8015        EventImage::Close { from, next } => {
8016            // A close call gets the value and the error or nil; between
8017            // calls nothing runs. The frame's instruction is the one that
8018            // began the closes, or, for an unwind, any it stopped.
8019            let call_fits = if idle {
8020                meta.slot == 0 && meta.nargs == 0
8021            } else {
8022                callable(2) && meta.slot >= frame.limit
8023            };
8024            let at = |reg: u8| u64::from(frame.base) + u64::from(reg);
8025            let next_fits = match next {
8026                NextImage::Advance => {
8027                    matches!(op, Op::CloseScope { from: reg } if at(reg) == u64::from(*from))
8028                }
8029                NextImage::Return { src, produced } => {
8030                    *from == frame.base
8031                        && (idle || u64::from(meta.slot) >= u64::from(*src) + u64::from(*produced))
8032                        && matches!(op, Op::Return { base, count }
8033                            if at(base) == u64::from(*src)
8034                                && (count == crate::opcode::COUNT_OPEN
8035                                    || u32::from(count) == *produced))
8036                }
8037                NextImage::Unwind(unwind) => {
8038                    *from == frame.base
8039                        && matches!(unwind.phase, crate::heap::UnwindPhase::Popping { .. })
8040                }
8041            };
8042            let alone = matches!(
8043                frame.pending,
8044                PendingImage::None | PendingImage::Capability { .. }
8045            ) && frame.targets.is_empty();
8046            if !(call_fits && next_fits && alone) {
8047                return Err(SnapshotError::InvalidStructure);
8048            }
8049            return Ok(());
8050        }
8051    };
8052    if idle {
8053        return Err(SnapshotError::InvalidStructure);
8054    }
8055    let fits = match (event, op) {
8056        (
8057            MetaEvent::Store { dst },
8058            Op::Index { dst: op_dst, .. } | Op::GetField { dst: op_dst, .. },
8059        ) => dst == op_dst && meta.nargs == 2,
8060        (
8061            MetaEvent::Store { dst },
8062            Op::Len { dst: op_dst, .. }
8063            | Op::Add { dst: op_dst, .. }
8064            | Op::Arith { dst: op_dst, .. }
8065            | Op::ArithK { dst: op_dst, .. }
8066            | Op::Neg { dst: op_dst, .. }
8067            | Op::BNot { dst: op_dst, .. }
8068            | Op::Concat { dst: op_dst, .. },
8069        ) => dst == op_dst && callable(2),
8070        (
8071            MetaEvent::Truth { dst, negate },
8072            Op::Compare {
8073                kind, dst: op_dst, ..
8074            },
8075        ) => dst == op_dst && negate == (kind == crate::opcode::CmpKind::Ne) && callable(2),
8076        (MetaEvent::Truth { dst, negate }, Op::CompareBranch { kind, .. }) => {
8077            dst == crate::opcode::COUNT_OPEN
8078                && negate == (kind == crate::opcode::CmpKind::Ne)
8079                && callable(2)
8080        }
8081        (MetaEvent::NewIndex, Op::SetIndex { .. } | Op::SetField { .. }) => meta.nargs == 3,
8082        (MetaEvent::NewIndexAssign, Op::AssignCommit { .. }) => {
8083            meta.nargs == 3 && matches!(frame.pending, PendingImage::Assigning { .. })
8084        }
8085        _ => false,
8086    };
8087    if !fits || meta.slot < frame.limit {
8088        return Err(SnapshotError::InvalidStructure);
8089    }
8090    Ok(())
8091}
8092
8093fn native_call_policy(
8094    image: &Image,
8095    registry: &HostRegistry,
8096    thread: &ThreadImage,
8097    index: usize,
8098) -> Result<crate::host::NativePolicy, SnapshotError> {
8099    let frame = &thread.frames[index];
8100    // A boundary frame calls the protected function, the message handler,
8101    // or what a base function calls.
8102    if let Some(boundary) = &frame.boundary {
8103        let slot = boundary.call_slot();
8104        let Some(index) = slot_native(image, thread.stack.get(slot as usize)) else {
8105            return Err(SnapshotError::InvalidStructure);
8106        };
8107        if thread.top <= slot {
8108            return Err(SnapshotError::InvalidStructure);
8109        }
8110        return native_policy(image, registry, index);
8111    }
8112    let proto_id = image
8113        .closures
8114        .iter()
8115        .find(|closure| closure.id == frame.closure)
8116        .map(|closure| closure.proto)
8117        .ok_or(SnapshotError::DanglingReference)?;
8118    let proto = image
8119        .protos
8120        .iter()
8121        .find(|proto| proto.id == proto_id)
8122        .ok_or(SnapshotError::DanglingReference)?;
8123    // A native tail call runs from the tail-calling Lua frame.
8124    let func = match proto.ops.get(frame.pc as usize) {
8125        Some(Op::Call { func, .. }) => func,
8126        Some(Op::TailCall { func, .. }) => func,
8127        _ => return Err(SnapshotError::InvalidStructure),
8128    };
8129    let slot = frame
8130        .base
8131        .checked_add(u32::from(*func))
8132        .ok_or(SnapshotError::InvalidStructure)?;
8133    let Some(index) = slot_native(image, thread.stack.get(slot as usize)) else {
8134        return Err(SnapshotError::InvalidStructure);
8135    };
8136    // The native's arguments end at `top`. Their count need not be the
8137    // `Call`'s: `__call` inserts arguments, and a native a callee tail-called
8138    // takes over the call with arguments of its own (ADR 0029).
8139    if thread.top <= slot {
8140        return Err(SnapshotError::InvalidStructure);
8141    }
8142    native_policy(image, registry, index)
8143}
8144
8145/// The native a call slot's value runs: a native's own index, or a native
8146/// closure's builtin (ADR 0035).
8147fn slot_native(image: &Image, value: Option<&EncValue>) -> Option<u32> {
8148    match value? {
8149        EncValue::Native(index) => Some(*index),
8150        EncValue::NativeClosure(id) => image
8151            .native_closures
8152            .iter()
8153            .find(|closure| closure.id == *id)
8154            .map(|closure| closure.native),
8155        _ => None,
8156    }
8157}
8158
8159fn native_policy(
8160    image: &Image,
8161    registry: &HostRegistry,
8162    index: u32,
8163) -> Result<crate::host::NativePolicy, SnapshotError> {
8164    let symbol = image
8165        .natives
8166        .get(index as usize)
8167        .ok_or(SnapshotError::DanglingReference)?;
8168    let slot = registry
8169        .native_slot(symbol)
8170        .ok_or(SnapshotError::UnknownHostSymbol)?;
8171    Ok(registry
8172        .native(slot)
8173        .ok_or(SnapshotError::UnknownHostSymbol)?
8174        .policy)
8175}
8176
8177/// The restored object of every snapshot id, by kind, for [`dec_value`].
8178struct Handles<'a> {
8179    strings: &'a std::collections::HashMap<u64, Handle<StringObj>>,
8180    tables: &'a std::collections::HashMap<u64, Handle<TableObj>>,
8181    closures: &'a std::collections::HashMap<u64, Handle<ClosureObj>>,
8182    threads: &'a std::collections::HashMap<u64, Handle<ThreadObj>>,
8183    native_closures: &'a std::collections::HashMap<u64, Handle<NativeClosureObj>>,
8184    userdata: &'a std::collections::HashMap<u64, Handle<crate::heap::UserdataObj>>,
8185    natives: usize,
8186    next_object_id: u64,
8187}
8188
8189fn dec_value(handles: &Handles<'_>, value: &EncValue) -> Result<Value, SnapshotError> {
8190    let Handles {
8191        strings,
8192        tables,
8193        closures,
8194        threads,
8195        native_closures,
8196        userdata,
8197        natives,
8198        next_object_id,
8199    } = handles;
8200    let natives = *natives;
8201    Ok(match value {
8202        EncValue::Nil => Value::Nil,
8203        EncValue::Bool(bit) => Value::Bool(*bit),
8204        EncValue::Integer(integer) => Value::Integer(*integer),
8205        EncValue::Float(bits) => Value::Float(f64::from_bits(*bits)),
8206        EncValue::String(id) => {
8207            Value::String(*strings.get(id).ok_or(SnapshotError::DanglingReference)?)
8208        }
8209        EncValue::Table(id) => {
8210            Value::Table(*tables.get(id).ok_or(SnapshotError::DanglingReference)?)
8211        }
8212        EncValue::Closure(id) => {
8213            Value::Closure(*closures.get(id).ok_or(SnapshotError::DanglingReference)?)
8214        }
8215        EncValue::Thread(id) => {
8216            Value::Thread(*threads.get(id).ok_or(SnapshotError::DanglingReference)?)
8217        }
8218        EncValue::Native(index) => {
8219            if *index as usize >= natives {
8220                return Err(SnapshotError::DanglingReference);
8221            }
8222            Value::Native(*index)
8223        }
8224        EncValue::NativeClosure(id) => Value::NativeClosure(
8225            *native_closures
8226                .get(id)
8227                .ok_or(SnapshotError::DanglingReference)?,
8228        ),
8229        EncValue::Userdata(id) => {
8230            Value::Userdata(*userdata.get(id).ok_or(SnapshotError::DanglingReference)?)
8231        }
8232        EncValue::Light(domain, bits) => {
8233            if !light_fits(*domain, *bits, *next_object_id) {
8234                return Err(SnapshotError::InvalidStructure);
8235            }
8236            Value::LightUserdata(*domain, *bits)
8237        }
8238    })
8239}
8240
8241pub(crate) fn crc32(data: &[u8]) -> u32 {
8242    let mut crc = 0xffff_ffffu32;
8243    for &byte in data {
8244        crc ^= u32::from(byte);
8245        for _ in 0..8 {
8246            let mask = (crc & 1).wrapping_neg();
8247            crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
8248        }
8249    }
8250    !crc
8251}
8252
8253fn hook_image(
8254    heap: &Heap,
8255    registry: &HostRegistry,
8256    h: &crate::runtime::hooks::HookState,
8257) -> Result<HookImage, SnapshotError> {
8258    use crate::runtime::hooks::HookTarget;
8259    // The registry index is resolved by the runtime below, never serialized.
8260    let target = match h.target {
8261        HookTarget::None => HookTargetImage::None,
8262        HookTarget::Lua(v) => HookTargetImage::Lua(enc_value(heap, v)?),
8263        HookTarget::InheritedLua => HookTargetImage::InheritedLua,
8264        HookTarget::Host(slot) => HookTargetImage::Host(
8265            registry
8266                .hook(slot)
8267                .ok_or(SnapshotError::UnknownHostSymbol)?
8268                .0
8269                .to_owned(),
8270        ),
8271    };
8272    Ok(HookImage {
8273        target,
8274        mask: h.mask,
8275        base_count: h.base_count,
8276        remaining_count: h.remaining_count,
8277        allow_hook: h.allow_hook,
8278        old_pc: h.old_pc,
8279        pending: h.pending,
8280        hook_yield: h.hook_yield,
8281        names: h
8282            .names
8283            .iter()
8284            .map(|v| enc_value(heap, *v))
8285            .collect::<Result<_, _>>()?,
8286        instruction: h.instruction,
8287        after: h.after,
8288        transfer: h.transfer,
8289        restore_cursor: h.restore_cursor,
8290    })
8291}
8292fn write_hook_after(out: &mut Vec<u8>, after: crate::runtime::hooks::AfterHook) {
8293    match after {
8294        crate::runtime::hooks::AfterHook::Continue => out.push(0),
8295        crate::runtime::hooks::AfterHook::Return { src, produced } => {
8296            out.push(1);
8297            out.extend(src.to_le_bytes());
8298            out.extend(produced.to_le_bytes());
8299        }
8300    }
8301}
8302fn read_hook_after(input: &mut &[u8]) -> Result<crate::runtime::hooks::AfterHook, SnapshotError> {
8303    Ok(match opcode::read_u8(input)? {
8304        0 => crate::runtime::hooks::AfterHook::Continue,
8305        1 => crate::runtime::hooks::AfterHook::Return {
8306            src: opcode::read_u32(input)?,
8307            produced: opcode::read_u32(input)?,
8308        },
8309        _ => return Err(SnapshotError::InvalidTag),
8310    })
8311}
8312fn write_hook_instruction(
8313    out: &mut Vec<u8>,
8314    instruction: Option<(usize, u32, u8)>,
8315) -> Result<(), SnapshotError> {
8316    out.push(u8::from(instruction.is_some()));
8317    if let Some((frame, pc, stage)) = instruction {
8318        write_count(out, frame, MAX_FRAMES)?;
8319        out.extend(pc.to_le_bytes());
8320        out.push(stage);
8321    }
8322    Ok(())
8323}
8324fn read_hook_instruction(input: &mut &[u8]) -> Result<Option<(usize, u32, u8)>, SnapshotError> {
8325    Ok(if read_flag(input)? {
8326        Some((
8327            checked_len(input, MAX_FRAMES)? as usize,
8328            opcode::read_u32(input)?,
8329            opcode::read_u8(input)?,
8330        ))
8331    } else {
8332        None
8333    })
8334}
8335fn write_hook_cursor(
8336    out: &mut Vec<u8>,
8337    cursor: Option<(usize, u32, Option<u32>)>,
8338) -> Result<(), SnapshotError> {
8339    out.push(u8::from(cursor.is_some()));
8340    if let Some((frame, pc, line)) = cursor {
8341        write_count(out, frame, MAX_FRAMES)?;
8342        out.extend(pc.to_le_bytes());
8343        out.push(u8::from(line.is_some()));
8344        if let Some(line) = line {
8345            out.extend(line.to_le_bytes());
8346        }
8347    }
8348    Ok(())
8349}
8350fn read_hook_cursor(input: &mut &[u8]) -> Result<Option<(usize, u32, Option<u32>)>, SnapshotError> {
8351    Ok(if read_flag(input)? {
8352        let frame = checked_len(input, MAX_FRAMES)? as usize;
8353        let pc = opcode::read_u32(input)?;
8354        let line = if read_flag(input)? {
8355            Some(opcode::read_u32(input)?)
8356        } else {
8357            None
8358        };
8359        Some((frame, pc, line))
8360    } else {
8361        None
8362    })
8363}
8364fn write_hook(out: &mut Vec<u8>, hook: Option<&HookImage>) -> Result<(), SnapshotError> {
8365    out.push(u8::from(hook.is_some()));
8366    let Some(h) = hook else { return Ok(()) };
8367    match &h.target {
8368        HookTargetImage::None => out.push(0),
8369        HookTargetImage::Lua(v) => {
8370            out.push(1);
8371            write_value(out, v);
8372        }
8373        HookTargetImage::Host(s) => {
8374            out.push(2);
8375            write_str(out, s)?;
8376        }
8377        HookTargetImage::InheritedLua => out.push(3),
8378    }
8379    out.push(h.mask);
8380    out.extend(h.base_count.to_le_bytes());
8381    out.extend(h.remaining_count.to_le_bytes());
8382    out.push(u8::from(h.allow_hook));
8383    write_hook_cursor(out, h.old_pc)?;
8384    out.push(u8::from(h.pending.is_some()));
8385    if let Some(e) = h.pending {
8386        out.push(e.event as u8);
8387        out.push(u8::from(e.line.is_some()));
8388        if let Some(line) = e.line {
8389            out.extend(line.to_le_bytes());
8390        }
8391        out.extend(e.frame.to_le_bytes());
8392        out.extend(e.transfer.0.to_le_bytes());
8393        out.extend(e.transfer.1.to_le_bytes());
8394        write_hook_after(out, e.after);
8395    }
8396    out.push(u8::from(h.hook_yield));
8397    for v in &h.names {
8398        write_value(out, v);
8399    }
8400    write_hook_instruction(out, h.instruction)?;
8401    write_hook_after(out, h.after);
8402    out.push(u8::from(h.transfer.is_some()));
8403    if let Some((frame, first, count)) = h.transfer {
8404        out.extend(frame.to_le_bytes());
8405        out.extend(first.to_le_bytes());
8406        out.extend(count.to_le_bytes());
8407    }
8408    write_hook_cursor(out, h.restore_cursor)?;
8409    Ok(())
8410}
8411fn read_hook(input: &mut &[u8]) -> Result<Option<HookImage>, SnapshotError> {
8412    use crate::runtime::hooks::{Event, PendingEvent};
8413    if !read_flag(input)? {
8414        return Ok(None);
8415    }
8416    let target = match opcode::read_u8(input)? {
8417        0 => HookTargetImage::None,
8418        1 => HookTargetImage::Lua(read_value(input)?),
8419        2 => HookTargetImage::Host(read_string(input)?),
8420        3 => HookTargetImage::InheritedLua,
8421        _ => return Err(SnapshotError::InvalidTag),
8422    };
8423    let mask = opcode::read_u8(input)?;
8424    let base_count = opcode::read_u32(input)? as i32;
8425    let remaining_count = opcode::read_u32(input)? as i32;
8426    let allow_hook = read_flag(input)?;
8427    let old_pc = read_hook_cursor(input)?;
8428    let pending = if read_flag(input)? {
8429        let event = match opcode::read_u8(input)? {
8430            0 => Event::Call,
8431            1 => Event::Return,
8432            2 => Event::Line,
8433            3 => Event::Count,
8434            4 => Event::TailCall,
8435            _ => return Err(SnapshotError::InvalidTag),
8436        };
8437        let line = if read_flag(input)? {
8438            Some(opcode::read_u32(input)?)
8439        } else {
8440            None
8441        };
8442        Some(PendingEvent {
8443            event,
8444            line,
8445            frame: opcode::read_u32(input)?,
8446            transfer: (opcode::read_u32(input)?, opcode::read_u32(input)?),
8447            after: read_hook_after(input)?,
8448        })
8449    } else {
8450        None
8451    };
8452    let hook_yield = read_flag(input)?;
8453    let mut names = Vec::with_capacity(5);
8454    for _ in 0..5 {
8455        names.push(read_value(input)?);
8456    }
8457    let instruction = read_hook_instruction(input)?;
8458    let after = read_hook_after(input)?;
8459    let transfer = if read_flag(input)? {
8460        Some((
8461            opcode::read_u32(input)?,
8462            opcode::read_u32(input)?,
8463            opcode::read_u32(input)?,
8464        ))
8465    } else {
8466        None
8467    };
8468    let restore_cursor = read_hook_cursor(input)?;
8469    Ok(Some(HookImage {
8470        target,
8471        mask,
8472        base_count,
8473        remaining_count,
8474        allow_hook,
8475        old_pc,
8476        pending,
8477        hook_yield,
8478        names,
8479        instruction,
8480        after,
8481        transfer,
8482        restore_cursor,
8483    }))
8484}
8485fn realize_hook(
8486    h: &HookImage,
8487    owner: Handle<ThreadObj>,
8488    registry: &HostRegistry,
8489    decode: &Decode<'_>,
8490) -> Result<crate::runtime::hooks::HookState, SnapshotError> {
8491    use crate::runtime::hooks::{HookState, HookTarget};
8492    let target = match &h.target {
8493        HookTargetImage::None => HookTarget::None,
8494        HookTargetImage::InheritedLua => HookTarget::InheritedLua,
8495        HookTargetImage::Lua(v) => HookTarget::Lua(decode(v)?),
8496        HookTargetImage::Host(s) => HookTarget::Host(
8497            registry
8498                .hook_slot(s)
8499                .ok_or(SnapshotError::UnknownHostSymbol)?,
8500        ),
8501    };
8502    let mut names = [Value::Nil; 5];
8503    for (to, from) in names.iter_mut().zip(&h.names) {
8504        *to = decode(from)?;
8505    }
8506    Ok(HookState {
8507        owner,
8508        target,
8509        mask: h.mask,
8510        base_count: h.base_count,
8511        remaining_count: h.remaining_count,
8512        allow_hook: h.allow_hook,
8513        old_pc: h.old_pc,
8514        pending: h.pending,
8515        hook_yield: h.hook_yield,
8516        names,
8517        instruction: h.instruction,
8518        after: h.after,
8519        transfer: h.transfer,
8520        restore_cursor: h.restore_cursor,
8521        boundary_spare: matches!(h.target, HookTargetImage::Lua(_)).then(Box::default),
8522    })
8523}
8524
8525fn hook_after_fits(thread: &ThreadImage, after: crate::runtime::hooks::AfterHook) -> bool {
8526    match after {
8527        crate::runtime::hooks::AfterHook::Continue => true,
8528        crate::runtime::hooks::AfterHook::Return { src, produced } => {
8529            u64::from(src) + u64::from(produced) <= thread.stack.len() as u64
8530        }
8531    }
8532}
8533fn validate_hooks(
8534    image: &Image,
8535    thread: &ThreadImage,
8536    require: &dyn Fn(u64, Kind) -> Result<(), SnapshotError>,
8537) -> Result<(), SnapshotError> {
8538    use crate::runtime::hooks::{AfterHook, Event, HOOK_BYTES};
8539    let boundaries: Vec<_> = thread
8540        .frames
8541        .iter()
8542        .enumerate()
8543        .filter(|(_, f)| matches!(f.boundary, Some(BoundaryImage::Hook { .. })))
8544        .collect();
8545    let Some(h) = &thread.hook else {
8546        return if boundaries.is_empty() && !thread.frames.iter().any(|f| f.return_hook) {
8547            Ok(())
8548        } else {
8549            Err(SnapshotError::InvalidStructure)
8550        };
8551    };
8552    let invalid = || Err(SnapshotError::InvalidStructure);
8553    if h.mask & !15 != 0
8554        || h.names.len() != 5
8555        || ((h.base_count > 0) != (h.mask & 8 != 0)) && !matches!(h.target, HookTargetImage::None)
8556        || (h.mask & 8 != 0 && !(1..=h.base_count).contains(&h.remaining_count))
8557        || (h.mask & 8 == 0 && h.remaining_count != h.base_count)
8558        || thread.charged_held < HOOK_BYTES
8559        || thread.charged_held > image.gc.quota
8560        || !hook_after_fits(thread, h.after)
8561    {
8562        return invalid();
8563    }
8564    match &h.target {
8565        HookTargetImage::None if h.mask != 0 || h.base_count > 0 => return invalid(),
8566        HookTargetImage::Lua(value) => {
8567            if !matches!(
8568                value,
8569                EncValue::Closure(_) | EncValue::Native(_) | EncValue::NativeClosure(_)
8570            ) {
8571                return invalid();
8572            }
8573            require_value(require, value)?;
8574        }
8575        HookTargetImage::Host(symbol) if symbol.len() > MAX_STRING_BYTES as usize => {
8576            return invalid();
8577        }
8578        _ => {}
8579    }
8580    for (name, expected) in h
8581        .names
8582        .iter()
8583        .zip(["call", "return", "line", "count", "tail call"])
8584    {
8585        if !matches!(name, EncValue::Nil | EncValue::String(_)) {
8586            return invalid();
8587        }
8588        require_value(require, name)?;
8589        if let EncValue::String(id) = name
8590            && image.string(*id) != Some(expected.as_bytes())
8591        {
8592            return invalid();
8593        }
8594    }
8595    if matches!(h.target, HookTargetImage::Lua(_))
8596        && h.names.iter().any(|n| !matches!(n, EncValue::String(_)))
8597    {
8598        return invalid();
8599    }
8600    for cursor in [h.old_pc, h.restore_cursor].into_iter().flatten() {
8601        // The per-thread cursor may refer to a returned callback's historical
8602        // activation/prototype; traceexec clamps it in the next current proto.
8603        if cursor.0 >= MAX_FRAMES as usize || cursor.1 >= MAX_INSTRUCTIONS {
8604            return invalid();
8605        }
8606    }
8607    if h.instruction.is_some_and(|(depth, pc, stage)| {
8608        depth >= MAX_FRAMES as usize || pc >= MAX_INSTRUCTIONS || !(1..=2).contains(&stage)
8609    }) {
8610        return invalid();
8611    }
8612    let failed = thread.status == Status::Failed.tag();
8613    if let AfterHook::Return { src, .. } = h.after
8614        && (h.pending.is_some()
8615            || !h.allow_hook
8616            || thread
8617                .frames
8618                .last()
8619                .is_none_or(|f| !f.return_hook || f.boundary.is_some() || src < f.base))
8620    {
8621        return invalid();
8622    }
8623    for (index, frame) in thread.frames.iter().enumerate() {
8624        if frame.return_hook && !failed && !thread.closing {
8625            let pending_return = h.pending.is_some_and(|event| {
8626                event.frame as usize == index && matches!(event.after, AfterHook::Return { .. })
8627            });
8628            let delivering_return = boundaries.iter().any(|(_, boundary)| {
8629                matches!(boundary.boundary, Some(BoundaryImage::Hook { target, after: AfterHook::Return { .. }, .. }) if target as usize == index)
8630            });
8631            let finishing_return =
8632                index + 1 == thread.frames.len() && matches!(h.after, AfterHook::Return { .. });
8633            if !pending_return && !delivering_return && !finishing_return {
8634                return invalid();
8635            }
8636        }
8637    }
8638    // Failure retains the callback stack until coroutine.close. Those old
8639    // boundaries are abandoned, not active suppression. A close callback can
8640    // deliver a new hook above them; its transfer owner identifies the one
8641    // current boundary, which must be innermost.
8642    let active_boundary = if failed {
8643        None
8644    } else if thread.closing {
8645        h.transfer.and_then(|(activation, _, _)| boundaries.iter().find(|(_, frame)| {
8646            matches!(frame.boundary, Some(BoundaryImage::Hook { target, .. }) if target == activation)
8647        }))
8648    } else {
8649        boundaries.first()
8650    };
8651    if (!thread.closing && boundaries.len() > 1)
8652        || h.allow_hook != active_boundary.is_none()
8653        || h.transfer.is_some() != active_boundary.is_some()
8654        || (h.restore_cursor.is_some() && active_boundary.is_none())
8655        || active_boundary
8656            .is_some_and(|(index, _)| boundaries.last().is_none_or(|(last, _)| last != index))
8657    {
8658        return invalid();
8659    }
8660    if let Some((index, frame)) = active_boundary {
8661        let Some(BoundaryImage::Hook { target, .. }) = frame.boundary else {
8662            unreachable!()
8663        };
8664        if h.transfer
8665            .is_none_or(|(activation, _, _)| activation != target)
8666            || *index != target as usize + 1
8667        {
8668            return invalid();
8669        }
8670    }
8671    let transfer_fits = |frame: u32, first: u32, count: u32| {
8672        thread.frames.get(frame as usize).is_some_and(|f| {
8673            (first == 0) == (count == 0)
8674                && (count == 0
8675                    || u64::from(f.base) + u64::from(first) - 1 + u64::from(count)
8676                        <= thread.stack.len() as u64)
8677        })
8678    };
8679    if let Some((frame, first, count)) = h.transfer
8680        && !transfer_fits(frame, first, count)
8681    {
8682        return invalid();
8683    }
8684    if let Some(e) = h.pending {
8685        let bit = match e.event {
8686            Event::Call | Event::TailCall => 1,
8687            Event::Return => 2,
8688            Event::Line => 4,
8689            Event::Count => 8,
8690        };
8691        if !h.allow_hook
8692            || h.hook_yield
8693            || h.mask & bit == 0
8694            || matches!(
8695                h.target,
8696                HookTargetImage::None | HookTargetImage::InheritedLua
8697            )
8698            || !transfer_fits(e.frame, e.transfer.0, e.transfer.1)
8699            || e.frame as usize + 1 != thread.frames.len()
8700            || !hook_after_fits(thread, e.after)
8701            || (e.event != Event::Line && e.line.is_some())
8702            || (matches!(e.event, Event::Line | Event::Count)
8703                && (e.transfer != (0, 0) || !matches!(e.after, AfterHook::Continue)))
8704            || (matches!(e.event, Event::Call | Event::TailCall)
8705                && !matches!(e.after, AfterHook::Continue))
8706        {
8707            return invalid();
8708        }
8709        let frame = &thread.frames[e.frame as usize];
8710        match e.event {
8711            Event::Line | Event::Count => {
8712                if frame.boundary.is_some()
8713                    || h.instruction
8714                        .is_none_or(|(depth, pc, _)| depth != e.frame as usize || pc != frame.pc)
8715                    || (e.event == Event::Line
8716                        && (h.instruction != Some((e.frame as usize, frame.pc, 2))
8717                            || h.old_pc != Some((e.frame as usize, frame.pc, e.line))))
8718                {
8719                    return invalid();
8720                }
8721            }
8722            Event::Call | Event::TailCall => {
8723                let valid = match frame.boundary {
8724                    None => frame.pc == 0 && (e.event != Event::TailCall || frame.tail),
8725                    Some(BoundaryImage::HookNative { phase: 1, .. }) => e.event == Event::Call,
8726                    _ => false,
8727                };
8728                if !valid {
8729                    return invalid();
8730                }
8731            }
8732            Event::Return => {
8733                let valid = match (frame.boundary.as_ref(), e.after) {
8734                    (None, AfterHook::Return { src, produced }) => {
8735                        frame.return_hook
8736                            && src >= frame.base
8737                            && e.transfer
8738                                == if produced == 0 {
8739                                    (0, 0)
8740                                } else {
8741                                    (src - frame.base + 1, produced)
8742                                }
8743                    }
8744                    (
8745                        Some(BoundaryImage::HookNative {
8746                            phase: 4,
8747                            result,
8748                            produced,
8749                            ..
8750                        }),
8751                        AfterHook::Continue,
8752                    ) => {
8753                        *result >= frame.base
8754                            && e.transfer
8755                                == if *produced == 0 {
8756                                    (0, 0)
8757                                } else {
8758                                    (result - frame.base + 1, *produced)
8759                                }
8760                    }
8761                    _ => false,
8762                };
8763                if !valid {
8764                    return invalid();
8765                }
8766            }
8767        }
8768        if let AfterHook::Return { .. } = e.after
8769            && (e.event != Event::Return || !thread.frames[e.frame as usize].return_hook)
8770        {
8771            return invalid();
8772        }
8773    }
8774    if h.hook_yield {
8775        let current = thread
8776            .frames
8777            .len()
8778            .checked_sub(1)
8779            .and_then(|i| thread.frames.get(i).map(|f| (i, f)));
8780        // A suspended host yield survives clearing or replacing its hook.
8781        // The marker describes the interrupted instruction, not the new target.
8782        if !h.allow_hook
8783            || h.pending.is_some()
8784            || h.transfer.is_some()
8785            || !thread.coroutine
8786            || thread.id == image.entry
8787            || thread.closing
8788            || !matches!(thread.status, s if s == Status::LuaSuspended.tag() || s == Status::Ready.tag())
8789            || !matches!(h.after, AfterHook::Continue)
8790            || current
8791                .is_none_or(|(i, f)| f.boundary.is_some() || h.instruction != Some((i, f.pc, 2)))
8792        {
8793            return invalid();
8794        }
8795    }
8796    Ok(())
8797}
8798
8799#[cfg(test)]
8800mod proto_count_tests {
8801    use super::*;
8802
8803    #[test]
8804    fn forged_prototype_counts_are_checked_before_allocation() {
8805        for (field, ceiling) in [(0, MAX_INSTRUCTIONS), (1, MAX_CONSTS), (2, MAX_PROTOS)] {
8806            for count in [ceiling, u32::MAX] {
8807                let mut bytes = Vec::new();
8808                bytes.extend(1u32.to_le_bytes()); // One prototype.
8809                bytes.extend(1u64.to_le_bytes());
8810                bytes.extend([1, 0, 0]);
8811                if field == 0 {
8812                    bytes.extend(count.to_le_bytes());
8813                } else {
8814                    bytes.extend(1u32.to_le_bytes());
8815                    Op::Halt.encode(&mut bytes);
8816                    bytes.extend(if field == 1 { count } else { 0 }.to_le_bytes());
8817                    if field == 2 {
8818                        bytes.extend(0u32.to_le_bytes()); // Captures.
8819                        bytes.extend(count.to_le_bytes());
8820                    }
8821                }
8822                // Enough for the outer prototype count, too little for the
8823                // forged inner count. No vector reserves the declared size.
8824                bytes.resize(40, 0);
8825                let error = read_protos(
8826                    &mut bytes.as_slice(),
8827                    &mut HashSet::new(),
8828                    &std::collections::HashMap::new(),
8829                )
8830                .unwrap_err();
8831                assert!(matches!(
8832                    error,
8833                    SnapshotError::Truncated | SnapshotError::LimitExceeded
8834                ));
8835            }
8836        }
8837    }
8838}