unityrs-core 1.0.0

Read and write Unity asset bundles, serialized files and typetrees.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
//! The registry's reach and settle keep their invariants (plan section 3.16,
//! R1, R3 and R4) whatever the order in which threads take their steps
//! (review round 5: a `settle` that popped a slot let a concurrent
//! registration return before the slot was reached). Every interleaving is
//! forced with the Environment's hooks ([`crate::env::gate`]), never by
//! repetition: each operation stopped at each point between its steps,
//! while each other operation runs whole, or stops at a point of its own
//! and the two are let go in either order. A stress run of random
//! operations on several threads follows as a second check, the invariants
//! checked when each step returns.

// The source scan behind "the core starts no thread and never waits"
// (`unityrs_testkit::waits`) takes only an item under `#[cfg(test)]` in its
// own file for test code, so every item here that names a thread, a channel
// or a barrier carries one.
use std::sync::Arc;
#[cfg(test)]
use std::sync::Mutex;

use super::pending::List;
use super::{Hook, Registry, Slot};
#[cfg(test)]
use crate::env::gate::{Event, Gate, Run};
use crate::env::{Cab, EnvOptions, Environment, LoadMode, RawCab, Source};
use crate::limits::Meter;
use crate::raw::RawStr;
use bytes::Bytes;
use unityrs_testkit::env::{Obj, bundle, res_bytes, serialized};
use unityrs_testkit::rng::Rng;

impl Registry {
    /// The slot under `key` (already simplified), without settling.
    pub(super) fn peek(&self, key: &str) -> Option<Arc<Slot>> {
        self.read()
            .slots
            .get(key.as_bytes())
            .map(|e| e.slot.clone())
    }

    /// Whether `key` (already simplified) is registered, without settling.
    pub(super) fn has(&self, key: &str) -> bool {
        self.read().slots.contains_key(key.as_bytes())
    }

    /// The slots listed now, on either list.
    pub(crate) fn listed(&self) -> Vec<Arc<Slot>> {
        let inner = self.read();
        inner.pending.all().into_iter().map(|(_, s)| s).collect()
    }

    /// R1's tables agree (every key of the order is in the table at its
    /// position, and no other; a key's value ranks at or above its
    /// position), and the list is in its order and counted right.
    pub(crate) fn check(&self) {
        let inner = self.read();
        assert_eq!(inner.order.len(), inner.slots.len(), "order and table");
        for (rank, key) in &inner.order {
            let e = inner.slots.get(key.as_bytes()).expect("a key of the order");
            assert_eq!(&e.first, rank, "a key's position");
            assert!(e.slot.rank >= e.first, "a key's value ranks below it");
        }
        let listed = inner.pending.all();
        assert!(listed.windows(2).all(|w| w[0].0 < w[1].0), "list order");
        let len = |l| inner.pending.len(l);
        let ordering = std::sync::atomic::Ordering::Acquire;
        assert_eq!(
            self.pending_len.load(ordering),
            len(List::Listed),
            "the list's count"
        );
        assert_eq!(
            self.evicted_len.load(ordering),
            len(List::Evicted),
            "the evicted list's count"
        );
    }
}

fn cab(name: &str) -> Vec<u8> {
    serialized(&[], &[Obj::named(1, name, &[])])
}

/// The bundles: `o` holds `INNER` (a container of `CAB-I` and its
/// `.resS`), which `p`'s `INNER` (a CAB) drops; `q` holds `X` (a container
/// of `CAB-X`), which `r`'s `X` drops; `s` holds `Y`, a container nothing
/// drops.
#[derive(Clone)]
struct Scene {
    o: Bytes,
    p: Bytes,
    q: Bytes,
    r: Bytes,
    s: Bytes,
}

impl Scene {
    fn new() -> Self {
        let inner = bundle(&[("CAB-I", cab("i")), ("CAB-I.resS", res_bytes(8, 1))]);
        let x = bundle(&[("CAB-X", cab("x"))]);
        let y = bundle(&[("CAB-Y", cab("y"))]);
        Self {
            o: Bytes::from(bundle(&[("CAB-O", cab("o")), ("INNER", inner)])),
            p: Bytes::from(bundle(&[("INNER", cab("p-inner"))])),
            q: Bytes::from(bundle(&[("CAB-Q", cab("q")), ("X", x)])),
            r: Bytes::from(bundle(&[("X", cab("r-x"))])),
            s: Bytes::from(bundle(&[("Y", y)])),
        }
    }
}

fn src(name: &str, data: &Bytes) -> Source {
    Source::Bytes {
        name: RawStr::from(name),
        data: data.clone(),
    }
}

/// The containers, and the keys their reach registers.
const SUBTREES: [(&str, &[&str]); 3] = [
    ("inner", &["cab-i", "cab-i.ress"]),
    ("x", &["cab-x"]),
    ("y", &["cab-y"]),
];

/// A `Lazy` Environment with `o`, `q` and `s` loaded, and the slots of
/// their containers.
struct Rig {
    scene: Scene,
    env: Environment,
    containers: Vec<(Arc<Slot>, &'static [&'static str])>,
}

impl Rig {
    fn new(scene: &Scene) -> Self {
        let mut o = EnvOptions::unitypy();
        o.load = LoadMode::Lazy;
        let env = Environment::new(o);
        for (name, data) in [
            ("o.bundle", &scene.o),
            ("q.bundle", &scene.q),
            ("s.bundle", &scene.s),
        ] {
            env.load(src(name, data)).unwrap();
        }
        let reg = env.registry();
        let containers = SUBTREES
            .iter()
            .map(|(k, sub)| (reg.peek(k).expect("a container's key"), *sub))
            .collect();
        Self {
            scene: scene.clone(),
            env,
            containers,
        }
    }

    /// The invariants that hold at any moment: R1's tables (and the list's
    /// order), and R3: a container's slot marked reached has every key of
    /// its subtree registered.
    fn check(&self) {
        let reg = self.env.registry();
        reg.check();
        for (slot, sub) in &self.containers {
            if !slot.unreached() {
                for k in *sub {
                    assert!(reg.has(k), "R3: a reached container lacks {k}");
                }
            }
        }
    }
}

/// An operation that touches the registry's slots or its list.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Op {
    /// A load whose entry drops `o`'s `INNER` unreached.
    LoadP,
    /// A load whose entry drops `q`'s `X` unreached.
    LoadR,
    /// A reload of `o` on the same `Bytes`, whose `INNER` stands in for
    /// the key's value when that is unreached (plan section 9, Q14).
    LoadO2,
    /// A lookup by name of an entry inside `INNER`.
    GetI,
    /// A lookup of `Y`, a live container, which reaches it.
    GetY,
    /// The key listing.
    Keys,
    /// The container pass.
    Pass,
}

const OPS: [Op; 7] = [
    Op::LoadP,
    Op::LoadR,
    Op::LoadO2,
    Op::GetI,
    Op::GetY,
    Op::Keys,
    Op::Pass,
];

/// Whether `op` is a load.
fn is_load(op: Op) -> bool {
    matches!(op, Op::LoadP | Op::LoadR | Op::LoadO2)
}

/// The file a load op loads.
fn loaded(scene: &Scene, op: Op) -> (&'static str, &Bytes) {
    match op {
        Op::LoadP => ("p.bundle", &scene.p),
        Op::LoadR => ("r.bundle", &scene.r),
        _ => ("o2.bundle", &scene.o),
    }
}

/// The points an operation may be stopped at.
const POINTS: [Hook; 4] = [
    Hook::Published,
    Hook::Deferred,
    Hook::SettleTook,
    Hook::Reached,
];

/// Runs `op` on `env`; whether a lookup by name found its CAB.
fn apply(env: &Environment, scene: &Scene, op: Op) -> Option<bool> {
    let meter = Meter::unlimited();
    match op {
        Op::LoadP | Op::LoadR | Op::LoadO2 => {
            let (name, data) = loaded(scene, op);
            drop(env.load(src(name, data)).unwrap());
        }
        Op::GetI => {
            let found = env.get_cab(&RawStr::from("CAB-I"), &meter).unwrap();
            return Some(found.is_some());
        }
        Op::GetY => drop(env.get_cab(&RawStr::from("Y"), &meter).unwrap()),
        Op::Keys => drop(env.registry().keys().count()),
        Op::Pass => drop(env.container().unwrap().count()),
    }
    None
}

/// What `op` must leave when it returns, given the slots listed when it
/// started (R4: each is reached) and what it found.
fn after(rig: &Rig, op: Op, listed: &[Arc<Slot>], found: Option<bool>) {
    rig.check();
    for slot in listed {
        // A slot the key's value stands in for is never listed, so every
        // listed one is reached.
        assert!(
            !slot.unreached(),
            "R4: {op:?} returned with a slot listed before it unreached"
        );
    }
    let [inner, x, y] = [0, 1, 2].map(|i| &rig.containers[i].0);
    let registered = |sub: &[&str], what: &str| {
        let reg = rig.env.registry();
        for k in sub {
            assert!(reg.has(k), "{what}: {k} is not registered");
        }
    };
    match op {
        // A registration that drops a slot returns with its subtree
        // registered: the slot reached, or (`INNER`, after the reload) the
        // reload's slot, which stands in for the first load's, reached.
        Op::LoadP => registered(SUBTREES[0].1, "R4: LoadP's own drop"),
        Op::LoadR => assert!(!x.unreached(), "R4: LoadR's own drop"),
        // A lookup that resolves a container's slot reaches it.
        Op::GetY => assert!(!y.unreached(), "a lookup of Y"),
        Op::Pass => {
            for (_, sub) in &rig.containers {
                registered(sub, "the pass reaches every container");
            }
            assert!(!x.unreached() && !y.unreached(), "the pass");
        }
        Op::LoadO2 | Op::GetI | Op::Keys => {}
    }
    if op == Op::GetI && listed.iter().any(|s| Arc::ptr_eq(s, inner)) {
        assert_eq!(found, Some(true), "a lookup after INNER's drop");
    }
}

/// What each name finds, as a comparable answer; `inner` left out when
/// `own_key` (its own key is (b)'s difference: a reload's container after
/// the last load of `p`'s CAB of its name holds it under `Lazy`, where
/// `Eager` keeps the CAB).
fn answers(env: &Environment, own_key: bool) -> Vec<String> {
    let meter = Meter::unlimited();
    let names = [
        "cab-o",
        "cab-i",
        "cab-i.ress",
        "inner",
        "cab-q",
        "cab-x",
        "x",
        "cab-y",
    ];
    names
        .iter()
        .filter(|n| !(own_key && **n == "inner"))
        .map(|n| match env.get_cab(&RawStr::from(*n), &meter).unwrap() {
            None => format!("{n}: none"),
            Some(Cab::Serialized(sf)) => format!("{n}: {}", sf.name()),
            Some(Cab::Raw(RawCab::InBundle { bundle, dir_index })) => {
                format!("{n}: raw {}", bundle.directory()[dir_index].path)
            }
            Some(Cab::Raw(RawCab::File(f))) => format!("{n}: raw {}", f.name),
        })
        .collect()
}

/// The keys in order, the containers' names out: `Lazy` keys a
/// container's own name at its own position, where `Eager` keys it only as
/// a later CAB's (plan 3.13, (b)).
fn keys(env: &Environment) -> Vec<String> {
    env.registry()
        .keys()
        .map(|k| String::from_utf8_lossy(k.as_bytes()).into_owned())
        .filter(|k| !SUBTREES.iter().any(|(c, _)| c == k))
        .collect()
}

/// Once every operation returned, nothing is listed, and after a container
/// pass the registry answers as an eager load of the same loads in the same
/// order does (R1: whatever order the registrations arrived in).
fn quiet(rig: &Rig, loads: &[Op]) {
    rig.check();
    rig.env.container().unwrap().count();
    rig.check();
    assert!(
        rig.env.registry().listed().is_empty(),
        "a slot stayed listed"
    );
    let eager = Environment::new(EnvOptions::unitypy());
    let scene = &rig.scene;
    let mut order = vec![
        ("o.bundle", &scene.o),
        ("q.bundle", &scene.q),
        ("s.bundle", &scene.s),
    ];
    for op in loads {
        order.push(loaded(scene, *op));
    }
    for (name, data) in order {
        eager.load(src(name, data)).unwrap();
    }
    let at = |op| loads.iter().rposition(|o| *o == op);
    let own_key = matches!((at(Op::LoadP), at(Op::LoadO2)), (Some(p), Some(o2)) if p < o2);
    assert_eq!(
        answers(&rig.env, own_key),
        answers(&eager, own_key),
        "R1: values"
    );
    assert_eq!(keys(&rig.env), keys(&eager), "R1: positions");
}

/// Starts `op` on its own thread, stopped at `at` (its first time there),
/// with the slots listed as it starts.
#[cfg(test)]
fn start(gate: &Gate, rig: &Rig, op: Op, at: Option<Hook>) -> (Run<Option<bool>>, Vec<Arc<Slot>>) {
    let listed = rig.env.registry().listed();
    let env = rig.env.clone();
    let scene = rig.scene.clone();
    let run = gate.run(at.map(|h| (h, 1)), move || apply(&env, &scene, op));
    (run, listed)
}

/// Lets `run` (operation `op`) go, and checks what it leaves.
#[cfg(test)]
fn finish(rig: &Rig, op: Op, (run, listed): (Run<Option<bool>>, Vec<Arc<Slot>>)) {
    let found = run.finish();
    after(rig, op, &listed, found);
}

/// Every operation stopped at every point (its first time there), while
/// each operation runs whole, or stops at each point of its own and the two
/// are let go in either order: at each step the invariants hold, at each
/// return its own, and once both returned the registry answers as an eager
/// load does.
#[test]
fn reach_and_settle_keep_their_invariants_under_every_interleaving() {
    let scene = Scene::new();
    let mut cases = 0;
    for a in OPS {
        for p in POINTS {
            for b in OPS {
                for q in std::iter::once(None).chain(POINTS.map(Some)) {
                    for a_first in [true, false] {
                        if q.is_none() && !a_first {
                            continue;
                        }
                        cases += 1;
                        let rig = Rig::new(&scene);
                        let gate = Gate::install(&rig.env);
                        let ra = start(&gate, &rig, a, Some(p));
                        if ra.0.next() == Event::Stopped {
                            rig.check();
                        }
                        let rb = start(&gate, &rig, b, q);
                        if q.is_none() {
                            // `b` runs whole while `a` is stopped.
                            finish(&rig, b, rb);
                            finish(&rig, a, ra);
                        } else {
                            if rb.0.next() == Event::Stopped {
                                rig.check();
                            }
                            if a_first {
                                finish(&rig, a, ra);
                                finish(&rig, b, rb);
                            } else {
                                finish(&rig, b, rb);
                                finish(&rig, a, ra);
                            }
                        }
                        // The loads in the order they took their sequence
                        // numbers: `a` took its own before it stopped.
                        let loads: Vec<Op> = [a, b].into_iter().filter(|o| is_load(*o)).collect();
                        quiet(&rig, &loads);
                    }
                }
            }
        }
    }
    assert_eq!(cases, 7 * 4 * 7 * 9);
}

/// Review round 5's interleaving, by name: a load stopped after it listed
/// the slot it dropped, a lookup stopped after its `settle` picked that
/// slot; the load is let go first and returns with the slot reached, so a
/// lookup by name right after it finds `CAB-I` (a `settle` that popped the
/// slot left the load's own `settle` an empty list).
#[test]
fn a_load_returns_with_its_drop_reached_while_another_settle_holds_it() {
    let scene = Scene::new();
    let rig = Rig::new(&scene);
    let gate = Gate::install(&rig.env);
    let load = start(&gate, &rig, Op::LoadP, Some(Hook::Deferred));
    load.0.stopped();
    let get = start(&gate, &rig, Op::GetI, Some(Hook::SettleTook));
    get.0.stopped();
    finish(&rig, Op::LoadP, load);
    let inner = &rig.containers[0].0;
    assert!(!inner.unreached(), "the load returned with INNER unreached");
    let found = rig
        .env
        .get_cab(&RawStr::from("CAB-I"), &Meter::unlimited())
        .unwrap();
    assert!(found.is_some(), "a lookup right after the load");
    finish(&rig, Op::GetI, get);
    quiet(&rig, &[Op::LoadP]);
}

/// A standing slot that is the key's value learns a lower position from a
/// registration that ranks below it (two loads of `o` with a `CAB-Z` after
/// `INNER`, on the same `Bytes`, the later one's `INNER` registered first:
/// `CAB-Z`'s key then sits between the two positions) while a lookup on a
/// third thread is reaching it, stopped after its registrations and before
/// it closes the position: the close finds the position lower and the
/// reach registers once more there before it marks the slot reached, so
/// the entries take the first load's positions, as an eager load gives
/// them (`reach.rs`'s module docs, "Stand-ins"; plan section 9, Q14,
/// revised after review rounds 6 and 7). Run as well with the reach stopped
/// after its close, and with the reach done before the registration: the
/// registration then finds the position closed and lists the slot it
/// drops, which its load reaches before it returns.
#[test]
fn a_reach_that_learns_a_lower_position_registers_there() {
    let inner = bundle(&[("CAB-I", cab("i")), ("CAB-I.resS", res_bytes(8, 1))]);
    let o = Bytes::from(bundle(&[
        ("CAB-O", cab("o")),
        ("INNER", inner),
        ("CAB-Z", cab("z")),
    ]));
    // Where the reach stops while the first load registers its `INNER`:
    // after its last registration (`cab-i.ress`), after its close, or not
    // at all (it returns first).
    for at in [Some((Hook::Published, 2)), Some((Hook::Reached, 1)), None] {
        let mut options = EnvOptions::unitypy();
        options.load = LoadMode::Lazy;
        let env = Environment::new(options);
        let gate = Gate::install(&env);
        let load = |name: &'static str, at: Option<(Hook, usize)>| {
            let (env, data) = (env.clone(), o.clone());
            gate.run(at, move || drop(env.load(src(name, &data)).unwrap()))
        };
        // The first load stops after its first key, `CAB-O`; the second
        // registers `INNER` first, at its own position.
        let first = load("o.bundle", Some((Hook::Published, 1)));
        first.stopped();
        load("o2.bundle", None).finish();
        let standing = env.registry().peek("inner").expect("INNER");
        assert_eq!(standing.position(), standing.rank.load);
        let get = {
            let env = env.clone();
            gate.run(at, move || {
                let meter = Meter::unlimited();
                drop(env.get_cab(&RawStr::from("INNER"), &meter).unwrap());
            })
        };
        let what = format!("the reach stopped at {at:?}");
        if at.is_none() {
            get.finish();
            first.finish();
        } else {
            get.stopped();
            assert!(env.registry().has("cab-i.ress"), "{what}: it registered");
            first.finish();
            let lowered = standing.position() < standing.rank.load;
            // Before the close the stand-in lowers the position; after it
            // the first load lists its own `INNER` and reaches it.
            assert_eq!(lowered, at == Some((Hook::Published, 2)), "{what}");
            assert!(env.registry().listed().is_empty(), "{what}");
            assert!(standing.unreached(), "{what}: the reach is stopped");
            get.finish();
        }
        assert!(!standing.unreached(), "{what}");
        env.registry().check();
        assert!(env.registry().listed().is_empty());
        let eager = Environment::new(EnvOptions::unitypy());
        for name in ["o.bundle", "o2.bundle"] {
            eager.load(src(name, &o)).unwrap();
        }
        assert_eq!(answers(&env, false), answers(&eager, false), "{what}");
        assert_eq!(keys(&env), keys(&eager), "{what}: the positions");
    }
}

/// What UnityPy 1.25.2 recorded for the scene `nested_reloaded_spans_raced`
/// (`tests/fixtures/d/env.json`, `tools/fixtures/env.py`): the container's
/// row paths, and the path of each object of the reload's files, the last
/// of each `(CAB, path id)` in `env.objects` (the files the keys' values
/// are), by `(CAB, path id)`.
#[allow(clippy::type_complexity)]
fn raced_spans_oracle() -> (Vec<Option<String>>, Vec<((String, i64), Option<String>)>) {
    // Read at run time: no file is compiled into the core
    // (`crates/unityrs-tpk/tests/no_tpk.rs`).
    let path = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/d/env.json");
    let text = std::fs::read_to_string(path).expect("env.json");
    let doc: serde_json::Value = serde_json::from_str(&text).expect("env.json");
    let scene = doc["scenes"]
        .as_array()
        .expect("scenes")
        .iter()
        .find(|s| s["name"] == "nested_reloaded_spans_raced")
        .expect("the scene is recorded");
    let step = |op: &str| {
        scene["steps"]
            .as_array()
            .expect("steps")
            .iter()
            .find(|s| s["op"][0] == op)
            .expect("a recorded step")
    };
    let text = |v: &serde_json::Value| v.as_str().map(str::to_owned);
    let rows = step("container")["result"]
        .as_array()
        .expect("rows")
        .iter()
        .map(|r| text(&r[0]))
        .collect();
    let paths = step("paths");
    let objects = paths["objects"].as_array().expect("objects");
    let mut last: Vec<((String, i64), Option<String>)> = Vec::new();
    for (o, p) in objects
        .iter()
        .zip(paths["result"].as_array().expect("paths"))
    {
        let at = (
            o[0].as_str().expect("a CAB").to_owned(),
            o[1].as_i64().expect("a path id"),
        );
        last.retain(|(k, _)| *k != at);
        last.push((at, text(p)));
    }
    (rows, last)
}

/// The container's row paths and, for each `(CAB, path id)` the oracle
/// names, `obj.container` of that object of the key's value.
#[allow(clippy::type_complexity)]
fn raced_spans_answers(
    env: &Environment,
    objects: &[((String, i64), Option<String>)],
) -> (Vec<Option<String>>, Vec<((String, i64), Option<String>)>) {
    use crate::container::ContainerPath;
    let text = |b: &[u8]| String::from_utf8_lossy(b).into_owned();
    let rows = env
        .container()
        .expect("the container")
        .map(|i| i.expect("a row").row.path.map(|p| text(p.as_bytes())))
        .collect();
    let meter = Meter::unlimited();
    let paths = objects
        .iter()
        .map(|((cab, id), _)| {
            let Some(Cab::Serialized(sf)) =
                env.get_cab(&RawStr::from(cab.as_str()), &meter).unwrap()
            else {
                panic!("{cab} is a SerializedFile");
            };
            let obj = sf
                .objects()
                .find(|o| o.path_id() == *id)
                .expect("the object");
            let path = match env.container_path(&obj).expect("a path") {
                None => None,
                Some(ContainerPath::Str(s)) => Some(text(s.as_bytes())),
                Some(ContainerPath::NotAString) => Some("<not a str>".into()),
            };
            ((cab.clone(), *id), path)
        })
        .collect();
    (rows, paths)
}

/// What can stop a reach of the reload's `INNER`, or the pass that reaches
/// it, between its steps.
const RACE_POINTS: [(Hook, usize); 4] = [
    (Hook::Published, 1),
    (Hook::Published, 2),
    (Hook::Reached, 1),
    (Hook::SettleTook, 1),
];

/// Review round 7's race (scene `nested_reloaded_spans_raced`, `Lazy`): the
/// first load `o.bundle` is stopped after its first key; the reload
/// `o2.bundle` loads whole; a reach of the reload's `INNER` (a lookup of
/// its name, or a container pass) is stopped at a point; the first load is
/// let go and registers its `INNER`, which lowers the reach's position, and
/// returns; the reach is let go to a second point, where a container pass
/// runs, every load having returned; then the reach returns. Whatever the
/// two points, the container lists UnityPy's rows and every object of the
/// keys' files has UnityPy's path: no pass walks a reached slot whose
/// entries can still move to a lower position (`reach.rs`'s module docs,
/// "Stand-ins"; plan section 3.16, R4). The reach marked the slot reached
/// and then moved its entries, so a pass in between walked `CAB-Z` before
/// `CAB-I`, published the generation built, and `CAB-Z`'s object 2 kept the
/// path `assets/z.prefab` for good.
#[test]
fn no_pass_walks_a_reached_slot_whose_entries_can_still_move() {
    let scene = unityrs_testkit::env::nested_reloaded_spans_raced();
    let data = Bytes::from(scene.files[0].1.clone());
    let (rows, paths) = raced_spans_oracle();
    let mut cases = 0;
    for pass_reaches in [false, true] {
        for first in RACE_POINTS {
            for second in std::iter::once(None).chain(RACE_POINTS.map(Some)) {
                cases += 1;
                let mut options = EnvOptions::unitypy();
                options.load = LoadMode::Lazy;
                let env = Environment::new(options);
                let gate = Gate::install(&env);
                let load = {
                    let (env, data) = (env.clone(), data.clone());
                    gate.run(Some((Hook::Published, 1)), move || {
                        drop(env.load(src("o.bundle", &data)).unwrap());
                    })
                };
                load.stopped();
                drop(env.load(src("o2.bundle", &data)).unwrap());
                let reach = {
                    let env = env.clone();
                    let stops = std::iter::once(first).chain(second).collect();
                    gate.run_stops(stops, move || {
                        if pass_reaches {
                            env.container().unwrap().count();
                        } else {
                            let meter = Meter::unlimited();
                            drop(env.get_cab(&RawStr::from("INNER"), &meter).unwrap());
                        }
                    })
                };
                let what = format!("pass {pass_reaches}, {first:?} then {second:?}");
                if reach.next() == Event::Stopped {
                    load.finish();
                    reach.release();
                    if reach.next() == Event::Stopped {
                        env.container().unwrap().count();
                    }
                } else {
                    load.finish();
                }
                reach.finish();
                let got = raced_spans_answers(&env, &paths);
                assert_eq!(got.0, rows, "{what}: the rows");
                assert_eq!(got.1, paths, "{what}: the paths");
                env.registry().check();
                assert!(env.registry().listed().is_empty(), "{what}");
            }
        }
    }
    assert_eq!(cases, 2 * 4 * 5);
}

/// A listed slot is reached by every load's registration, whether or not
/// it drops a slot itself, and by the key listing, as by every other
/// reader (R3; review round 5: only a registration that dropped a slot
/// settled, and `keys` never did, so a refused reach waited for a lookup
/// by name). The slot is listed here directly, as a refused reach leaves
/// it.
#[test]
fn every_load_and_the_key_listing_reach_what_is_listed() {
    let scene = Scene::new();
    let other = Bytes::from(bundle(&[("CAB-C", cab("c"))]));
    for by_keys in [true, false] {
        let rig = Rig::new(&scene);
        let reg = rig.env.registry();
        let y = rig.containers[2].0.clone();
        {
            let mut inner = reg.write();
            inner.pending.push(y.clone());
            reg.store_lens(&inner.pending);
        }
        if by_keys {
            let _ = reg.keys().count();
        } else {
            drop(rig.env.load(src("c.bundle", &other)).unwrap());
        }
        assert!(!y.unreached(), "keys {by_keys}: Y was not reached");
        assert!(reg.has("cab-y"), "keys {by_keys}");
        assert!(reg.listed().is_empty(), "keys {by_keys}");
        rig.check();
    }
}

/// The test's own lock, held across an operation, so not one of the
/// Environment's (`super::super::held`).
#[cfg(test)]
fn plain<T>(m: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
    m.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}

/// Random operations on four threads, each step's invariants checked when
/// it returns (R1, R3, and R4 for what was listed when it started); once
/// all are done, the registry answers as an eager load of the same loads
/// in the order they were made. The loads are made in turn (a lock records
/// their order); every other operation races them.
#[cfg(test)]
#[test]
fn reach_and_settle_keep_their_invariants_under_a_random_stress() {
    let scene = Scene::new();
    for seed in 0..24_u64 {
        let rig = Arc::new(Rig::new(&scene));
        let loads = Arc::new(Mutex::new(Vec::new()));
        let threads: Vec<_> = (0..4_u64)
            .map(|t| {
                let rig = rig.clone();
                let loads = loads.clone();
                std::thread::spawn(move || {
                    let mut rng = Rng::new(seed * 16 + t);
                    for _ in 0..12 {
                        let op = OPS[rng.below(OPS.len())];
                        let listed = rig.env.registry().listed();
                        let found = if is_load(op) {
                            let mut order = plain(&loads);
                            let found = apply(&rig.env, &rig.scene, op);
                            order.push(op);
                            found
                        } else {
                            apply(&rig.env, &rig.scene, op)
                        };
                        after(&rig, op, &listed, found);
                    }
                })
            })
            .collect();
        for t in threads {
            t.join().unwrap();
        }
        let order = plain(&loads).clone();
        quiet(&rig, &order);
    }
}