viperjs 0.3.0

An embeddable JavaScript engine in safe Rust, with zero runtime dependencies.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
//! What an object does when its properties are changed, and when they refuse to be.
//!
//! Most of these rows are about one rule — a non-configurable property refuses every change, and
//! restating what is already true is not a change — because that rule is where nearly all of
//! §10.1.6.3's length comes from.

use super::*;
use crate::heap::Handle;
use crate::heap::Heap;
use crate::heap::{PropertyDescriptor, PropertyKind};
use crate::value::Value;

fn key(heap: &mut Heap, text: &str) -> PropertyKey {
    PropertyKey::from_units(heap, &text.encode_utf16().collect::<Vec<_>>())
}

/// The own property, through the heap — the tests all hold an `ObjectId` rather than an
/// `Object`, because that is what everything in the engine will hold.
fn own(heap: &Heap, object: ObjectId, key: PropertyKey) -> Option<Property> {
    heap.object(object)?.get_own_property(key).copied()
}

fn count(heap: &Heap, object: ObjectId) -> usize {
    heap.object(object).map_or(0, Object::property_count)
}

fn keys(heap: &Heap, object: ObjectId) -> Vec<PropertyKey> {
    heap.object(object)
        .map_or_else(Vec::new, |found| found.own_property_keys())
}

fn prevent(heap: &mut Heap, object: ObjectId) {
    if let Some(found) = heap.object_mut(object) {
        found.prevent_extensions();
    }
}

fn delete(heap: &mut Heap, object: ObjectId, key: PropertyKey) -> bool {
    heap.object_mut(object)
        .is_some_and(|found| found.delete(key))
}

/// A descriptor for a plain writable, enumerable, configurable data property — what
/// assignment produces, and what `Object.defineProperty` notably does not.
fn data(value: f64) -> PropertyDescriptor {
    PropertyDescriptor {
        value: Some(Value::Number(value)),
        writable: Some(true),
        enumerable: Some(true),
        configurable: Some(true),
        ..PropertyDescriptor::EMPTY
    }
}

#[test]
fn a_new_property_takes_the_defaults_for_every_field_the_descriptor_omits() {
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    // `Object.defineProperty(o, "a", {value: 1})` — three attributes unstated, and every
    // default is `false`. This is the difference from `o.a = 1`, which states all three.
    let bare = PropertyDescriptor {
        value: Some(Value::Number(1.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &bare));
    let property = own(&heap, object, a).expect("just defined"); // the test is about it
    assert!(!property.enumerable);
    assert!(!property.configurable);
    assert!(matches!(
        property.kind,
        PropertyKind::Data {
            writable: false,
            ..
        }
    ));
}

#[test]
fn nothing_may_be_added_to_a_non_extensible_object_and_what_is_there_may_still_change() {
    let mut heap = Heap::new();
    let (a, b) = (key(&mut heap, "a"), key(&mut heap, "b"));
    let object = heap.new_object(None);
    assert!(heap.define_own_property(object, a, &data(1.0)));
    prevent(&mut heap, object);

    assert!(!heap.object(object).is_some_and(Object::is_extensible));
    assert!(!heap.define_own_property(object, b, &data(2.0)));
    assert_eq!(count(&heap, object), 1);
    // …while the property that was already there is untouched by any of it: extensibility is
    // about *additions*, and `Object.preventExtensions` is not `Object.freeze`.
    assert!(heap.define_own_property(object, a, &data(3.0)));
    assert!(delete(&mut heap, object, a));
    assert_eq!(count(&heap, object), 0);
}

#[test]
fn a_non_configurable_property_refuses_every_change_but_the_ones_that_are_no_change() {
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    let frozen = PropertyDescriptor {
        value: Some(Value::Number(1.0)),
        writable: Some(false),
        enumerable: Some(true),
        configurable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &frozen));

    // Making it configurable again — the one-way door.
    let becoming_configurable = PropertyDescriptor {
        configurable: Some(true),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &becoming_configurable));
    // Changing its enumerability.
    let becoming_hidden = PropertyDescriptor {
        enumerable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &becoming_hidden));
    // Changing its kind.
    let becoming_accessor = PropertyDescriptor {
        getter: Some(Value::Undefined),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &becoming_accessor));
    // Making it writable, or changing its value.
    let becoming_writable = PropertyDescriptor {
        writable: Some(true),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &becoming_writable));
    let other_value = PropertyDescriptor {
        value: Some(Value::Number(2.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &other_value));
    // …and deleting it.
    assert!(!delete(&mut heap, object, a));

    // Restating exactly what is already true is allowed, every time — that is a change of
    // nothing, and §10.1.6.3 only ever refuses changes.
    assert!(heap.define_own_property(object, a, &frozen));
    let restating_attributes = PropertyDescriptor {
        enumerable: Some(true),
        configurable: Some(false),
        writable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &restating_attributes));
    // …as is asking for nothing at all.
    assert!(heap.define_own_property(object, a, &PropertyDescriptor::EMPTY));
    assert_eq!(count(&heap, object), 1);
}

#[test]
fn restating_the_value_of_a_frozen_property_writes_nothing_which_matters_for_nan() {
    // §10.1.6.3's NOTE, and the reason [`Validation`] has three cases. Two NaNs are the same
    // value to `SameValue` and can be told apart by other means, so the specification is
    // careful to leave the stored one alone.
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    let stored = f64::from_bits(0x7ff8_0000_0000_0001);
    let other = f64::from_bits(0xfff8_0000_0000_0000);
    assert!(stored.is_nan() && other.is_nan() && stored.to_bits() != other.to_bits());

    let frozen = PropertyDescriptor {
        value: Some(Value::Number(stored)),
        writable: Some(false),
        configurable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &frozen));
    // Accepted, because the two are the same *value*…
    let restated = PropertyDescriptor {
        value: Some(Value::Number(other)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &restated));
    // …and the bits that were there are still there.
    let PropertyKind::Data {
        value: Value::Number(kept),
        ..
    } = own(&heap, object, a).expect("still defined").kind
    // the test is about it
    else {
        panic!("still a data property")
    };
    assert_eq!(kept.to_bits(), stored.to_bits());
}

#[test]
fn a_frozen_accessor_keeps_both_of_its_functions_and_may_have_either_restated() {
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    let (getter, setter) = (Value::Number(1.0), Value::Number(2.0));
    let frozen = PropertyDescriptor {
        getter: Some(getter),
        setter: Some(setter),
        enumerable: Some(true),
        configurable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &frozen));

    // §10.1.6.3 step 5.d, both halves — either function being different is a refusal, and
    // the setter is protected exactly as the getter is.
    let other_getter = PropertyDescriptor {
        getter: Some(Value::Number(9.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &other_getter));
    let other_setter = PropertyDescriptor {
        setter: Some(Value::Number(9.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &other_setter));
    // Restating the same pair is a change of nothing, and so is restating one of them.
    assert!(heap.define_own_property(object, a, &frozen));
    let same_setter = PropertyDescriptor {
        setter: Some(setter),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &same_setter));
    // …and a descriptor naming *no* kind is not asking for a change of kind, so step 5.c
    // lets it through even though this property is an accessor and the descriptor is not.
    let restating_configurable = PropertyDescriptor {
        configurable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &restating_configurable));
    // An accessor cannot become a data property while it is non-configurable, though.
    let becoming_data = PropertyDescriptor {
        value: Some(Value::Number(0.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &becoming_data));
}

#[test]
fn a_non_configurable_property_that_is_writable_may_still_be_written_to() {
    // The pair of attributes is not one attribute. `Object.seal` leaves properties writable
    // and non-configurable, and that is the common case rather than a corner: the value may
    // change, the property may not be redefined or deleted.
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    let sealed = PropertyDescriptor {
        value: Some(Value::Number(1.0)),
        writable: Some(true),
        enumerable: Some(true),
        configurable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &sealed));

    let other_value = PropertyDescriptor {
        value: Some(Value::Number(2.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &other_value));
    // Restating writability is allowed while it is still writable…
    let staying_writable = PropertyDescriptor {
        writable: Some(true),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &staying_writable));
    // …and giving it up is allowed once, after which neither may come back.
    let freezing = PropertyDescriptor {
        writable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &freezing));
    assert!(!heap.define_own_property(object, a, &staying_writable));
    let third_value = PropertyDescriptor {
        value: Some(Value::Number(3.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(!heap.define_own_property(object, a, &third_value));
    // …while restating the value it now holds is still a change of nothing, and allowed.
    assert!(heap.define_own_property(object, a, &other_value));
    assert!(!delete(&mut heap, object, a));
}

#[test]
fn a_configurable_property_may_become_the_other_kind_and_forgets_what_it_was() {
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    assert!(heap.define_own_property(object, a, &data(1.0)));

    // Data to accessor naming only a *setter*: the old value is gone rather than kept as
    // the getter, which is step 6.a's "or to the attribute's default value otherwise".
    let setter_only = PropertyDescriptor {
        setter: Some(Value::Number(8.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &setter_only));
    assert!(matches!(
        own(&heap, object, a).expect("still defined").kind, // the test is about it
        PropertyKind::Accessor {
            getter: Value::Undefined,
            setter: Value::Number(8.0)
        }
    ));
    assert!(heap.define_own_property(object, a, &data(1.0)));

    // Data to accessor: the value is gone, the unstated accessor is `undefined`, and the two
    // shared attributes survive because the descriptor did not mention them.
    let getter_only = PropertyDescriptor {
        getter: Some(Value::Number(7.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &getter_only));
    let property = own(&heap, object, a).expect("still defined"); // the test is about it
    assert!(matches!(
        property.kind,
        PropertyKind::Accessor {
            getter: Value::Number(7.0),
            setter: Value::Undefined
        }
    ));
    assert!(property.enumerable && property.configurable);

    // …and back, symmetrically.
    let value_only = PropertyDescriptor {
        value: Some(Value::Number(2.0)),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &value_only));
    let property = own(&heap, object, a).expect("still defined"); // same
    assert!(matches!(
        property.kind,
        PropertyKind::Data {
            value: Value::Number(2.0),
            writable: false
        }
    ));
    assert!(property.enumerable && property.configurable);
}

#[test]
fn changing_one_attribute_leaves_the_others_where_they_were() {
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    assert!(heap.define_own_property(object, a, &data(1.0)));
    // Step 6.c — a field the descriptor does not have is an attribute it is not asking about.
    let hide = PropertyDescriptor {
        enumerable: Some(false),
        ..PropertyDescriptor::EMPTY
    };
    assert!(heap.define_own_property(object, a, &hide));
    let property = own(&heap, object, a).expect("still defined"); // the test is about it
    assert!(!property.enumerable);
    assert!(property.configurable);
    assert!(matches!(
        property.kind,
        PropertyKind::Data {
            value: Value::Number(1.0),
            writable: true
        }
    ));
}

#[test]
fn deleting_a_property_that_is_not_there_succeeds() {
    // `delete o.nothing` is `true`, and says nothing about whether there was anything.
    let mut heap = Heap::new();
    let a = key(&mut heap, "a");
    let object = heap.new_object(None);
    assert!(delete(&mut heap, object, a));
    assert!(heap.define_own_property(object, a, &data(1.0)));
    assert!(delete(&mut heap, object, a));
    assert!(delete(&mut heap, object, a));
    assert_eq!(count(&heap, object), 0);
}

#[test]
fn own_keys_put_the_array_indices_first_in_numeric_order_and_the_rest_in_creation_order() {
    let mut heap = Heap::new();
    let object = heap.new_object(None);
    // The example every article about this uses, and it is in the specification because
    // every engine had already agreed on it.
    for text in ["b", "2", "a", "1", "10", "0"] {
        let k = key(&mut heap, text);
        assert!(heap.define_own_property(object, k, &data(0.0)));
    }
    let names: Vec<String> = keys(&heap, object)
        .into_iter()
        .map(|k| k.describe(&heap).unwrap_or_default())
        .collect();
    // Numeric order, not textual — "10" after "2" is the whole point of sorting on the index.
    assert_eq!(names, ["0", "1", "2", "10", "b", "a"]);
}

#[test]
fn a_key_too_large_to_be_an_array_index_is_ordered_as_a_name() {
    let mut heap = Heap::new();
    let object = heap.new_object(None);
    for text in ["4294967295", "5", "4294967294"] {
        let k = key(&mut heap, text);
        assert!(heap.define_own_property(object, k, &data(0.0)));
    }
    let names: Vec<String> = keys(&heap, object)
        .into_iter()
        .map(|k| k.describe(&heap).unwrap_or_default())
        .collect();
    // 2^32 - 1 is a length, never an index, so it keeps its place among the names.
    assert_eq!(names, ["5", "4294967294", "4294967295"]);
}

#[test]
fn a_property_is_found_along_the_prototype_chain_and_the_nearest_one_wins() {
    let mut heap = Heap::new();
    let (a, b, missing) = (
        key(&mut heap, "a"),
        key(&mut heap, "b"),
        key(&mut heap, "z"),
    );
    let grandparent = heap.new_object(None);
    let parent = heap.new_object(Some(grandparent));
    let child = heap.new_object(Some(parent));

    assert!(heap.define_own_property(grandparent, a, &data(1.0)));
    assert!(heap.define_own_property(grandparent, b, &data(1.0)));
    assert!(heap.define_own_property(parent, b, &data(2.0)));

    assert!(heap.has_property(child, a));
    assert!(heap.has_property(child, b));
    assert!(!heap.has_property(child, missing));
    // Shadowing: the nearest object on the chain that has the key is the one that answers.
    assert_eq!(
        heap.find_own(child, b).map(|(owner, _)| owner),
        Some(parent)
    );
    assert_eq!(
        heap.find_own(child, a).map(|(owner, _)| owner),
        Some(grandparent)
    );
    // An object with a null prototype inherits nothing, which is what `Object.create(null)`
    // is for.
    let bare = heap.new_object(None);
    assert!(!heap.has_property(bare, a));
}

#[test]
fn a_prototype_may_not_be_made_to_point_back_at_itself() {
    let mut heap = Heap::new();
    let first = heap.new_object(None);
    let second = heap.new_object(Some(first));
    let third = heap.new_object(Some(second));

    // Directly, and at a distance: `first.__proto__ = third` would close a three-object loop.
    assert!(!heap.set_prototype_of(first, Some(first)));
    assert!(!heap.set_prototype_of(first, Some(third)));
    assert_eq!(heap.object(first).and_then(Object::prototype), None);
    // …while a chain that does not come back is fine.
    let elsewhere = heap.new_object(None);
    assert!(heap.set_prototype_of(first, Some(elsewhere)));
    assert_eq!(
        heap.object(first).and_then(Object::prototype),
        Some(elsewhere)
    );
}

#[test]
fn a_non_extensible_object_keeps_its_prototype_and_may_still_be_told_to_keep_it() {
    let mut heap = Heap::new();
    let prototype = heap.new_object(None);
    let object = heap.new_object(Some(prototype));
    prevent(&mut heap, object);

    assert!(!heap.set_prototype_of(object, None));
    // §10.1.2 step 2 comes *before* the extensibility test, so setting it to what it already
    // is succeeds even here — which is not the same as being able to change it.
    assert!(heap.set_prototype_of(object, Some(prototype)));
    assert_eq!(
        heap.object(object).and_then(Object::prototype),
        Some(prototype)
    );
}

#[test]
fn a_foreign_or_missing_object_handle_answers_rather_than_panicking() {
    // DR-0002 over the handles, on the same terms as `Heap::string`: no panic and no
    // out-of-range read, and no detection either.
    let mut heap = Heap::new();
    let mut other = Heap::new();
    let a = key(&mut heap, "a");
    let stranger = other.new_object(None);
    other.new_object(None);
    let past_the_end = other.new_object(None);

    assert!(heap.object(past_the_end).is_none());
    assert!(!heap.has_property(past_the_end, a));
    assert!(!heap.define_own_property(past_the_end, a, &data(1.0)));
    assert!(heap.find_own(past_the_end, a).is_none());
    assert!(!heap.set_prototype_of(past_the_end, None));
    // §7.3.29 and §7.3.32 answer the same way, and this is the only place the answer can be reached:
    // a compiled chunk always names an object it has just seen on the stack, so the guard exists for
    // a hand-built one and would otherwise be a branch no test could pin.
    let name = heap.new_symbol(None);
    assert!(!heap.add_private_field(past_the_end, name, Value::Number(1.0)));
    assert!(!heap.set_private_field(past_the_end, name, Value::Number(1.0)));
    let method = crate::heap::PrivateElement::Method(Value::Number(1.0));
    assert!(!heap.add_private_element(past_the_end, name, method));
    // …and one that happens to be in range answers about *this* heap's object at that index.
    let mine = heap.new_object(None);
    assert_eq!(stranger, mine);
    assert!(heap.object(stranger).is_some());

    // The same three operations on an object that is *real*, for the answers they give about a name it
    // does not carry and a kind that refuses. Reachable only from here, and after the assertion above
    // because that one is about an object index and a further allocation would move it: the
    // interpreter reads the kind and finds the entry before it asks any of these, so each is a
    // contract this test states rather than a branch a script can take.
    let real = heap.new_object(None);
    assert!(!heap.set_private_field(real, name, Value::Number(1.0)));
    assert!(heap.add_private_element(real, name, method));
    // A name the object does not carry while carrying *others* is a third path, distinct from having
    // no list at all — and it answers the same way, which is what these two rows together say.
    let other = heap.new_symbol(None);
    assert!(!heap.set_private_field(real, other, Value::Number(1.0)));
    // §7.3.32 refuses a *method*, which is the check the interpreter makes for itself.
    assert!(!heap.set_private_field(real, name, Value::Number(2.0)));
    // …and a second add of the same name refuses, which is §7.3.30 step 2 and is what makes an
    // object's set of private names fixed once it has them.
    assert!(!heap.add_private_element(real, name, method));
}

#[test]
fn a_swept_environment_slot_is_handed_out_again_and_the_old_handle_names_nothing() {
    use crate::heap::Roots;
    // DR-0019. Two claims, and the second is the reason the first is allowed: a freed slot is
    // reused, and a handle issued for the *previous* use of that slot reads as `None` rather than
    // as whatever now lives there.
    let mut heap = Heap::new();
    let first = heap.new_environment(None, 1);
    heap.set_variable(first, 0, Value::Number(1.0));
    assert!(matches!(heap.variable(first, 0), Some(Some(Value::Number(n))) if n == 1.0));
    // Nothing roots it, so a collection takes it.
    assert_eq!(heap.collect(&Roots::default()).environments, 1);
    assert!(heap.variable(first, 0).is_none());
    // The next environment gets that same slot back — which is what stops the arena growing, and
    // is the whole of what DR-0019 buys.
    let second = heap.new_environment(None, 1);
    assert_eq!(first.index(), second.index());
    assert_ne!(first.generation(), second.generation());
    heap.set_variable(second, 0, Value::Number(2.0));
    assert!(matches!(heap.variable(second, 0), Some(Some(Value::Number(n))) if n == 2.0));
    // …and the stale handle still names nothing. **Without the generation it would read `2`** — a
    // wrong value rather than a detected mistake, which is the failure this record exists to
    // prevent and the reason a free list alone was not adopted.
    assert!(heap.variable(first, 0).is_none());
    assert!(heap.environment_size(first).is_none());
    assert!(heap.environment_names(first).is_none());
    // Depth 1 and not depth 0: a walk of zero parents never consults the arena, so it hands back
    // the handle it was given — stale or not. That is harmless rather than a gap, because every
    // read *through* the answer goes through the accessor and gets `None` there; but it is the one
    // operation here that a stale handle survives, and saying so beats asserting the tidier thing.
    assert!(heap.environment_at(first, 1).is_none());
    assert!(!heap.set_variable(first, 0, Value::Number(3.0)));
    assert!(!heap.uninitialise(first, 0));
    // The write the stale handle attempted must not have reached the live one.
    assert!(matches!(heap.variable(second, 0), Some(Some(Value::Number(n))) if n == 2.0));
}

#[test]
fn a_reachable_environment_keeps_its_slot_and_its_handle_across_a_collection() {
    use crate::heap::Roots;
    // The other half, without which the test above would pass for a heap that freed everything.
    let mut heap = Heap::new();
    let kept = heap.new_environment(None, 1);
    heap.set_variable(kept, 0, Value::Number(7.0));
    let roots = Roots {
        values: Vec::new(),
        environments: vec![kept],
    };
    assert_eq!(heap.collect(&roots).environments, 0);
    assert!(matches!(heap.variable(kept, 0), Some(Some(Value::Number(n))) if n == 7.0));
    // …and a new environment does **not** take a live slot, so the two stay distinct.
    let other = heap.new_environment(None, 1);
    assert_ne!(kept.index(), other.index());
}

#[test]
fn reusing_a_slot_is_what_stops_the_arena_growing() {
    use crate::heap::Roots;
    // The claim DR-0019 is *for*, as a heap fact rather than a benchmark: a thousand environments
    // made and freed one after another occupy one slot, not a thousand.
    let mut heap = Heap::new();
    let before = heap.footprint();
    for _ in 0..1_000 {
        let short_lived = heap.new_environment(None, 1);
        heap.set_variable(short_lived, 0, Value::Number(1.0));
        heap.collect(&Roots::default());
    }
    // A shape rather than a number: ten slots' worth of room, against the thousand that tombstones
    // would have left behind.
    let grew = heap.footprint() - before;
    assert!(
        grew < 10 * size_of::<Option<crate::heap::Environment>>(),
        "the arena grew by {grew} bytes"
    );
    assert_eq!(heap.environment_count(), 0);
}