Skip to main content

unityrs_export/ngui/
register.rs

1//! 2.6 steps 2 and 4, the engine's to drive before the cut: X's own open on
2//! `M_X`, the private Environment, and each bundle's marked rows reached
3//! (`docs/plans/batch.md` 2.6; review round 1's B4, round 2's S1 and S2).
4//!
5//! A [`Registration`] is the engine's to drive in 2.6's order:
6//! [`Registration::open`] is step 2 (X's own open on `M_X` by a
7//! `Source::Path`'s rules, the stream reader, after the members' ids are
8//! checked, in bytewise order and none repeated, and the stop), then
9//! step 3 is the engine's ([`Registration::own`] gives X's own handle),
10//! then [`Registration::member`] registers each member in bytewise order of
11//! id with `load_dependency`, handing the engine each loaded bundle (for
12//! the view's name table and its `same_named_cab` rows) and reaching its
13//! marked rows, its peek bits loaded at that reach into a buffer charged to
14//! `M_X` and dropped after ([`PeekBits`], [`Bits`]); and
15//! [`Registration::finish`] registers X last, from the bytes of its own
16//! open, compares the registered header and directory with the own
17//! handle's, and reaches X's rows. [`register`] runs all of it for a view
18//! as staged, with no step 3. Every Environment call is checked as 2.6
19//! step 7 says: its run-level class first, then the evictions (X's own
20//! bare `limit(attempt_evictions, <value>)`, never a member's), then the
21//! rest. Every core call, and every charge of a table registration makes,
22//! is under the refusal probe on its own, with the engine's hooks (2.7;
23//! review round 3's P1). [`peek`] is the peek pass's function, and
24//! [`register_bytes`] the tests' path to the engine's, from bytes.
25//!
26//! The core has no entry point that registers X's slot over its own
27//! handle's parse (step 4's "X's slot shares its own handle's
28//! allocation"): the slot shares the own open's bytes, so nothing is read
29//! twice, but parses them again on a dependency meter of its own; its
30//! resources are served through the own handle by the core's redirect over
31//! shared `Bytes`.
32
33use std::path::Path;
34use std::sync::Arc;
35
36use unityrs_core::budget::{Reservation, Unbounded};
37use unityrs_core::detect::{FileType, check_file_type, check_file_type_with_reader};
38use unityrs_core::env::{DependencyFile, EnvOptions, Environment, Source, read_path};
39use unityrs_core::files::{BundleFile, File, parse_file_with_reader};
40use unityrs_core::limits::{Charge, Limits, Meter, MeteredVec, heap_cost};
41use unityrs_core::pystr::simplify_name;
42use unityrs_core::stream::ReaderKind;
43use unityrs_core::{Bytes, Error, FileContext, LimitError, LimitKind, RawStr};
44
45use super::classify::{self, Class, Reason};
46use super::seam::{self, Hooks, Registered};
47use super::table;
48use super::{Failure, View};
49
50/// A staged bundle's bytes: a spool file, or bytes in hand.
51#[derive(Clone, Copy, Debug)]
52pub enum Data<'a> {
53    /// Its staged file.
54    Path(&'a Path),
55    /// Its bytes.
56    Bytes(&'a Bytes),
57}
58
59/// A bundle of the view as staged.
60#[derive(Clone, Copy, Debug)]
61pub struct Staged<'a> {
62    /// Its spec id.
63    pub id: &'a str,
64    /// The name the core opens it under (its spool name).
65    pub name: &'a RawStr,
66    /// Its bytes.
67    pub data: Data<'a>,
68}
69
70/// A bundle's peek bits (2.6 step 4's peek table): its top-level row count
71/// and a bit per row in directory order, set for a bundle, packed eight to
72/// a byte, in a buffer charged to its meter before it is allocated.
73#[derive(Debug)]
74pub struct Bits {
75    rows: u32,
76    packed: MeteredVec<u8>,
77}
78
79impl Bits {
80    /// The bits of `rows` rows, all clear, charged to `meter` first: the
81    /// buffer a peek fills, or an attempt reads a peek file into.
82    pub fn charged(rows: u32, meter: &Arc<Meter>) -> Result<Self, Class> {
83        let n = usize::try_from(rows.div_ceil(8)).unwrap_or(usize::MAX);
84        let mut packed = table::with_capacity(meter, n)?;
85        for _ in 0..n {
86            table::push(&mut packed, 0u8)?;
87        }
88        Ok(Self { rows, packed })
89    }
90
91    /// A copy of `bits` (as a peek file holds them) in a buffer charged to
92    /// `meter` first, the charge under the refusal probe of `hooks`: what a
93    /// [`PeekBits`] loader gives (review round 4's T2), so a refusal no
94    /// budget counted is the stop `host_memory` there too.
95    pub fn copied(bits: &Self, meter: &Arc<Meter>, hooks: &dyn Hooks) -> Result<Self, Failure> {
96        let mut out = seam::probe(hooks, || Self::charged(bits.rows, meter)).map_err(own)?;
97        out.bytes_mut().copy_from_slice(bits.bytes());
98        Ok(out)
99    }
100
101    /// The row count.
102    #[must_use]
103    pub fn rows(&self) -> u32 {
104        self.rows
105    }
106
107    /// The packed bits, `ceil(rows / 8)` bytes: a peek file's bytes.
108    #[must_use]
109    pub fn bytes(&self) -> &[u8] {
110        self.packed.as_slice()
111    }
112
113    /// The packed bits to fill (a peek file's bytes, read into them).
114    pub fn bytes_mut(&mut self) -> &mut [u8] {
115        self.packed.as_mut_slice()
116    }
117
118    /// Row `i`'s bit.
119    #[must_use]
120    pub fn get(&self, i: usize) -> bool {
121        self.packed
122            .as_slice()
123            .get(i / 8)
124            .is_some_and(|b| b & (1 << (i % 8)) != 0)
125    }
126
127    /// Sets row `i`'s bit.
128    pub fn set(&mut self, i: usize) {
129        if let Some(b) = self.packed.as_mut_slice().get_mut(i / 8) {
130            *b |= 1 << (i % 8);
131        }
132    }
133}
134
135/// Where an attempt reads a bundle's peek bits at its reach: the engine's
136/// peek file, read into [`Bits::charged`] on `meter` (`M_X`). A refused
137/// charge is X's own reason, an I/O error `host_io`; the bits are checked
138/// against the registered directory's row count here.
139pub trait PeekBits {
140    /// The bits of the bundle `id`, charged to `meter`, the charge under
141    /// the refusal probe of `hooks` ([`Bits::copied`] makes them so).
142    fn load(&self, id: &str, meter: &Arc<Meter>, hooks: &dyn Hooks) -> Result<Bits, Failure>;
143}
144
145/// The first 21 bytes the core's detection reads of an entry.
146const PEEK: u64 = 21;
147
148/// A member's failure: `dependency_failed(<id>, <reason>)`, the member's
149/// own reason inside (a code is `container_error`'s).
150pub(super) fn dependency_failed(id: &str, c: Class) -> Failure {
151    let inner = match c {
152        Class::Run(r) => return Failure::Run(r),
153        Class::Skip(r) | Class::Input(r) => container(r),
154    };
155    Failure::Input(Reason {
156        reason: format!("dependency_failed({id}, {})", inner.reason),
157        detail: inner.detail,
158        cut: inner.cut,
159    })
160}
161
162/// A load's error the bytes decide is the bundle's `container_error`.
163fn container(r: Reason) -> Reason {
164    if r.reason == "decode_error" {
165        Reason {
166            reason: "container_error".to_owned(),
167            detail: r.detail,
168            cut: r.cut,
169        }
170    } else {
171        r
172    }
173}
174
175/// An open's failure: a code is the bundle's `container_error`.
176fn opened(e: &Error) -> Class {
177    match classify::error(e) {
178        Class::Skip(r) | Class::Input(r) => Class::Input(container(r)),
179        run @ Class::Run(_) => run,
180    }
181}
182
183/// X's own class as its failure: a charge to `M_X` or a read of its own.
184fn own(c: Class) -> Failure {
185    Failure::from(c)
186}
187
188/// The cutter's own fault: a run failure, `internal`.
189fn internal() -> Failure {
190    Failure::Run(Reason::plain("internal"))
191}
192
193/// Step 2: the bundle opened on `meter` by a `Source::Path`'s rules (the
194/// stream reader), its bytes, and their charge when they were in hand
195/// (`Data::Bytes`, charged to `meter` as a staged file's read is). A file
196/// of another kind is `not_a_bundle`. The read (or the charge), the
197/// detection and the parse are each under the probe of `hooks` on their
198/// own.
199fn open(
200    name: &RawStr,
201    data: Data<'_>,
202    context: &Arc<FileContext>,
203    meter: &Arc<Meter>,
204    hooks: &dyn Hooks,
205) -> Result<(Bytes, Option<Charge>, Arc<BundleFile>), Class> {
206    let limits = &context.limits;
207    let (bytes, charge) = match data {
208        Data::Path(p) => {
209            let read = seam::probe(hooks, || {
210                read_path(p, limits, meter).map_err(|e| opened(&e))
211            });
212            (read?, None)
213        }
214        Data::Bytes(b) => {
215            let len = u64::try_from(b.len()).unwrap_or(u64::MAX);
216            if len > limits.max_input_bytes {
217                let e = Error::Limit(LimitError::refused(
218                    LimitKind::InputBytes,
219                    len,
220                    limits.max_input_bytes,
221                ));
222                return Err(opened(&e));
223            }
224            let charge = seam::probe(hooks, || {
225                meter.charge(heap_cost(len)).map_err(|e| table::refused(&e))
226            })?;
227            (b.clone(), Some(charge))
228        }
229    };
230    let ty = seam::probe(hooks, || {
231        check_file_type_with_reader(&bytes, limits, ReaderKind::Stream)
232            .map_err(|e| opened(&e.into()))
233    })?;
234    let file = seam::probe(hooks, || {
235        parse_file_with_reader(
236            name.clone(),
237            bytes.clone(),
238            ty,
239            None,
240            meter,
241            context,
242            ReaderKind::Stream,
243        )
244        .map_err(|e| opened(&e))
245    })?;
246    match file {
247        File::Bundle(b) => Ok((bytes, charge, b)),
248        _ => Err(Class::Input(Reason::plain("not_a_bundle"))),
249    }
250}
251
252/// Whether top-level row `i` of `b` is a bundle, as the peek reads it: a
253/// `Limit` there is the bundle's failure, as a host's error or a refusal
254/// is, and any other error "not a container".
255fn is_bundle_entry(b: &BundleFile, i: usize) -> Result<bool, Error> {
256    match b.entry_range(i, 0..PEEK) {
257        Ok(head) => match check_file_type(&head, &Limits::default()) {
258            Ok(ty) => Ok(ty == FileType::BundleFile),
259            Err(e @ unityrs_core::detect::DetectError::Allocator(_)) => Err(e.into()),
260            Err(_) => Ok(false),
261        },
262        Err(e @ (Error::Limit(_) | Error::Io(_) | Error::Budget(_))) => Err(e),
263        // Allocator provenance can be nested in an entry, tree, read or
264        // dereference error. Keep the single recursive classifier authoritative:
265        // UnityCN header and walk refusals classify as per-input (Skip), so at
266        // this probe they mean "not a container", and registration/load_all
267        // later reports them as per-input failures.
268        Err(e) => match classify::error(&e) {
269            Class::Run(_) => Err(e),
270            Class::Skip(_) | Class::Input(_) => Ok(false),
271        },
272    }
273}
274
275/// A peek's class as its outcome (2.6 step 4's peek rule): a refusal can
276/// only be the allocator's, since the peek's budget's limit is its meter's
277/// bound, which the meter checks first, so a `budget(...)` is `host_memory`;
278/// a run-level class stays one; anything else is the bundle's peek failure.
279fn peeked(c: Class) -> Failure {
280    match c {
281        Class::Run(r) => Failure::Run(r),
282        Class::Skip(r) | Class::Input(r) if r.reason.starts_with("budget(") => {
283            Failure::Run(Reason::plain("host_memory"))
284        }
285        Class::Skip(r) | Class::Input(r) => Failure::Input(r),
286    }
287}
288
289/// The peek (2.6 step 4's peek table): the bundle opened by step 2's rules
290/// on `meter`, the peek's own, then a bit per top-level row in directory
291/// order, a dropped row included, set for a bundle, in a buffer charged on
292/// that meter first. The stop is checked between entries. Its failure is
293/// the bundle's peek failure (`Failure::Input`): its open's, or a row's
294/// `Limit`; a refusal is the allocator's, `host_memory`; an I/O error
295/// `host_io`.
296pub fn peek(
297    name: &RawStr,
298    data: Data<'_>,
299    context: &Arc<FileContext>,
300    meter: &Arc<Meter>,
301    hooks: &dyn Hooks,
302) -> Result<Bits, Failure> {
303    let (_, _held, b) = open(name, data, context, meter, hooks).map_err(peeked)?;
304    let n = b.directory().len();
305    let rows = u32::try_from(n).map_err(|_| internal())?;
306    let mut bits = seam::probe(hooks, || Bits::charged(rows, meter)).map_err(peeked)?;
307    for i in 0..n {
308        if hooks.stopped() {
309            return Err(Failure::Stopped);
310        }
311        if seam::probe(hooks, || is_bundle_entry(&b, i).map_err(|e| opened(&e))).map_err(peeked)? {
312            bits.set(i);
313        }
314    }
315    Ok(bits)
316}
317
318/// One Environment call of registration, checked as 2.6 step 7 says: under
319/// the refusal probe, its run-level class first, then the evictions (X's
320/// own bare reason), and only then the call's own error, given back for
321/// the caller to name.
322fn call<T>(
323    env: &Environment,
324    admit: &Admit<'_>,
325    f: impl FnOnce() -> Result<T, Error>,
326) -> Result<Result<T, Error>, Failure> {
327    seam::allocator_check(admit.hooks).map_err(Failure::from)?;
328    let before = admit.hooks.refusals();
329    let out = f();
330    #[cfg(feature = "test-hooks")]
331    let out = match admit.hooks.environment_fault(env) {
332        Some(error) => Err(error),
333        None => out,
334    };
335    admit.hooks.environment(env);
336    seam::allocator_check(admit.hooks).map_err(Failure::from)?;
337    if let Err(e) = &out
338        && let Class::Run(r) = seam::probed(admit.hooks, before, classify::error(e))
339    {
340        return Err(Failure::Run(r));
341    }
342    seam::evictions(env, admit.max_evictions).map_err(own)?;
343    Ok(out)
344}
345
346/// What a reach's failure is named for: X's own row, or a member's.
347#[derive(Clone, Copy)]
348enum Whose<'a> {
349    Own,
350    Member(&'a str),
351}
352
353impl Whose<'_> {
354    /// A load's or a reach's error as the input's failure.
355    fn failed(self, e: &Error, path: &RawStr, admit: &Admit<'_>, before: Option<u64>) -> Failure {
356        let c = seam::probed(admit.hooks, before, classify::error(e));
357        match (self, c) {
358            (_, Class::Run(r)) => Failure::Run(r),
359            (Self::Own, _) => own(seam::probed(
360                admit.hooks,
361                before,
362                classify::entry_error(e, path),
363            )),
364            (Self::Member(id), c) => dependency_failed(id, c),
365        }
366    }
367}
368
369/// Reaches `b`'s nested containers (2.6 step 4): each top-level row whose
370/// bit is set, in directory order, but a dropped row, one whose key
371/// (`simplify_name`) a later row of the bundle takes. The rows' keys are
372/// computed once into a buffer, and a permutation of the rows (a `u32`
373/// each) sorted in place by (key, row), a row dropped when the next in that
374/// order has its key; the buffer, the permutation and the dropped rows'
375/// bits are charged to `M_X` and dropped after, each charge (and each
376/// `simplify_name`) under the probe on its own. Each `get_cab` is an
377/// Environment call ([`call`]).
378fn reach(
379    env: &Environment,
380    b: &BundleFile,
381    bits: &Bits,
382    whose: Whose<'_>,
383    admit: &Admit<'_>,
384) -> Result<(), Failure> {
385    let meter = admit.meter;
386    let dir = b.directory();
387    let _sample = super::read::Sample(b.meter(), admit.hooks);
388    let n = dir.len();
389    if u32::try_from(n).ok() != Some(bits.rows()) {
390        return Err(internal());
391    }
392    let hooks = admit.hooks;
393    // The keys, one buffer; each row's end in it.
394    let mut keys: MeteredVec<u8> = MeteredVec::new(meter);
395    let mut ends: MeteredVec<usize> =
396        seam::probe(hooks, || table::with_capacity(meter, n)).map_err(own)?;
397    for row in dir {
398        let key = seam::probe(hooks, || {
399            simplify_name(&row.path, meter).map_err(|e| table::refused(&e))
400        })
401        .map_err(own)?;
402        seam::probe(hooks, || {
403            keys.extend_from_slice(key.as_bytes())
404                .map_err(|e| table::refused(&e))
405        })
406        .map_err(own)?;
407        let end = keys.len();
408        seam::probe(hooks, || table::push(&mut ends, end)).map_err(own)?;
409    }
410    let key = |i: u32| {
411        let i = usize::try_from(i).unwrap_or(usize::MAX);
412        let start = i
413            .checked_sub(1)
414            .and_then(|p| ends.as_slice().get(p))
415            .copied();
416        let end = ends.as_slice().get(i).copied().unwrap_or(0);
417        keys.as_slice()
418            .get(start.unwrap_or(0)..end)
419            .unwrap_or_default()
420    };
421    let mut order: MeteredVec<u32> =
422        seam::probe(hooks, || table::with_capacity(meter, n)).map_err(own)?;
423    for i in 0..bits.rows() {
424        seam::probe(hooks, || table::push(&mut order, i)).map_err(own)?;
425    }
426    order
427        .as_mut_slice()
428        .sort_unstable_by(|a, b| key(*a).cmp(key(*b)).then(a.cmp(b)));
429    let mut dropped = seam::probe(hooks, || Bits::charged(bits.rows(), meter)).map_err(own)?;
430    for pair in order.as_slice().windows(2) {
431        if let [a, b] = pair
432            && key(*a) == key(*b)
433        {
434            dropped.set(usize::try_from(*a).unwrap_or(usize::MAX));
435        }
436    }
437    drop(order);
438    for (i, row) in dir.iter().enumerate() {
439        if !bits.get(i) || dropped.get(i) {
440            continue;
441        }
442        let before = admit.hooks.refusals();
443        if let Err(e) = call(env, admit, || env.get_cab(&row.path, meter))? {
444            return Err(whose.failed(&e, &row.path, admit, before));
445        }
446    }
447    Ok(())
448}
449
450/// What registration needs beside the view.
451type Loaded<'a> = dyn FnMut(&str, &Arc<BundleFile>) -> Result<(), Failure> + 'a;
452type WithHandle<'a> = dyn FnMut(&str, &Arc<BundleFile>, DependencyFile) -> Result<(), Failure> + 'a;
453
454#[derive(Clone, Copy)]
455pub struct Admit<'a> {
456    /// The private Environment's options: `EnvOptions::batch(ctx_X)` with
457    /// `dep_cache_bytes` set to `D` (2.2); its context's limits and budget
458    /// are the attempt's.
459    pub env: &'a EnvOptions,
460    /// `M_X`.
461    pub meter: &'a Arc<Meter>,
462    /// The stop flag and the refusal count.
463    pub hooks: &'a dyn Hooks,
464    /// `max_attempt_evictions`.
465    pub max_evictions: u64,
466}
467
468/// A view's registration, as the engine drives it (module docs).
469pub struct Registration<'a> {
470    admit: Admit<'a>,
471    input: Staged<'a>,
472    env: Environment,
473    own: Arc<BundleFile>,
474    bytes: Bytes,
475    held: Option<Charge>,
476    /// The members' ids, in the order they are registered.
477    ids: &'a [&'a str],
478    /// How many of them are registered.
479    next: usize,
480}
481
482/// Whether `ids` are in strictly ascending bytewise order (so none is
483/// repeated) and none is X's own `x`.
484fn in_order(ids: &[&str], x: &str) -> bool {
485    ids.windows(2)
486        .all(|w| matches!(w, [a, b] if a.as_bytes() < b.as_bytes()))
487        && !ids.contains(&x)
488}
489
490impl<'a> Registration<'a> {
491    /// Step 2: the members' `ids` checked first (in bytewise order, none
492    /// repeated, X's not among them; any other is `internal`, the caller's
493    /// fault, review round 3's P4), then the stop, then X's own open on
494    /// `M_X`, and the private Environment, empty.
495    pub fn open(input: Staged<'a>, ids: &'a [&'a str], admit: Admit<'a>) -> Result<Self, Failure> {
496        if !in_order(ids, input.id) {
497            return Err(internal());
498        }
499        if admit.hooks.stopped() {
500            return Err(Failure::Stopped);
501        }
502        let context = &admit.env.context;
503        let (bytes, held, own) = open(input.name, input.data, context, admit.meter, admit.hooks)?;
504        Ok(Self {
505            admit,
506            input,
507            env: Environment::new(admit.env.clone()),
508            own,
509            bytes,
510            held,
511            ids,
512            next: 0,
513        })
514    }
515
516    /// Current private Environment figures, including a failed member call.
517    #[must_use]
518    pub fn stats(&self) -> unityrs_core::env::EnvStats {
519        self.env.stats()
520    }
521
522    /// X's own handle, on `M_X`: step 3 reads its AssetBundle object.
523    #[must_use]
524    pub fn own(&self) -> &Arc<BundleFile> {
525        &self.own
526    }
527
528    /// Step 4 for one member, after the stop check: its load (the next of
529    /// the ids [`Self::open`] took; any other is `internal`), the loaded
530    /// bundle handed to `loaded` (the name table), then its reach, its bits
531    /// loaded from `bits` and dropped after. A failure the member makes is
532    /// `dependency_failed(<id>, <reason>)`.
533    pub fn member(
534        &mut self,
535        m: &Staged<'a>,
536        bits: &dyn PeekBits,
537        loaded: &mut Loaded<'_>,
538    ) -> Result<(), Failure> {
539        self.member_with_handle(m, bits, &mut |id, bundle, _| loaded(id, bundle))
540    }
541
542    /// Register a member and pass its evictable handle to the caller.
543    pub fn member_with_handle(
544        &mut self,
545        m: &Staged<'a>,
546        bits: &dyn PeekBits,
547        loaded: &mut WithHandle<'_>,
548    ) -> Result<(), Failure> {
549        let admit = self.admit;
550        if admit.hooks.stopped() {
551            return Err(Failure::Stopped);
552        }
553        if self.ids.get(self.next) != Some(&m.id) {
554            return Err(internal());
555        }
556        self.next += 1;
557        let whose = Whose::Member(m.id);
558        let env = &self.env;
559        let before = admit.hooks.refusals();
560        let source = match m.data {
561            Data::Bytes(b) => Source::Bytes {
562                name: m.name.clone(),
563                data: b.clone(),
564            },
565            Data::Path(p) => Source::Path(p.to_path_buf()),
566        };
567        let (file, handle) = call(env, &admit, || env.load_dependency_with_handle(source))?
568            .map_err(|e| whose.failed(&e, m.name, &admit, before))?;
569        let File::Bundle(b) = file else {
570            return Err(dependency_failed(
571                m.id,
572                Class::Input(Reason::plain("not_a_bundle")),
573            ));
574        };
575        loaded(m.id, &b, handle)?;
576        let bits = bits.load(m.id, admit.meter, admit.hooks)?;
577        reach(env, &b, &bits, whose, &admit)
578    }
579
580    /// X last, every member registered (else `internal`), after the stop
581    /// check: its load from its own open's bytes, the registered header and
582    /// directory compared with the own handle's ([`same_open`]), the bundle
583    /// handed to `loaded`, then X's reach.
584    pub fn finish(
585        self,
586        bits: &dyn PeekBits,
587        loaded: &mut Loaded<'_>,
588    ) -> Result<Registered, Failure> {
589        self.finish_with_handle(bits, &mut |id, bundle, _| loaded(id, bundle))
590    }
591
592    /// Finish registration and pass the registered input's evictable handle.
593    pub fn finish_with_handle(
594        self,
595        bits: &dyn PeekBits,
596        loaded: &mut WithHandle<'_>,
597    ) -> Result<Registered, Failure> {
598        let admit = self.admit;
599        if self.next != self.ids.len() {
600            return Err(internal());
601        }
602        if admit.hooks.stopped() {
603            return Err(Failure::Stopped);
604        }
605        let env = &self.env;
606        let before = admit.hooks.refusals();
607        let source = Source::Bytes {
608            name: self.input.name.clone(),
609            data: self.bytes.clone(),
610        };
611        let (file, handle) = call(env, &admit, || env.load_dependency_with_handle(source))?
612            .map_err(
613                |e| match seam::probed(admit.hooks, before, classify::error(&e)) {
614                    Class::Skip(r) | Class::Input(r) => Failure::Input(container(r)),
615                    Class::Run(r) => Failure::Run(r),
616                },
617            )?;
618        let File::Bundle(slot) = file else {
619            return Err(Failure::Input(Reason::plain("not_a_bundle")));
620        };
621        same_open(&slot, &self.own)?;
622        loaded(self.input.id, &slot, handle)?;
623        let bits = bits.load(self.input.id, admit.meter, admit.hooks)?;
624        reach(env, &slot, &bits, Whose::Own, &admit)?;
625        drop(slot);
626        Ok(Registered {
627            env: self.env,
628            own: self.own,
629            _held: self.held,
630        })
631    }
632}
633
634/// Step 4's comparison: X's slot, read by the memory reader's rules, against
635/// its own handle, read by the stream reader's. A difference (a header
636/// string with no NUL in its first 32,767 bytes, which the two readers
637/// return differently) fails X, `container_error`, detail `malformed`.
638pub fn same_open(slot: &BundleFile, own: &BundleFile) -> Result<(), Failure> {
639    if slot.header() != own.header() || slot.directory() != own.directory() {
640        return Err(Failure::Input(container(Reason::decode_error("malformed"))));
641    }
642    Ok(())
643}
644
645/// 2.6 steps 2 and 4 for a view as staged, with no step 3: the members
646/// sorted in bytewise order of id (X among them is passed over), their ids
647/// checked (a repeated one is `internal`) and the stop, before X's own
648/// open; then the members in that order; then X ([`Registration`]).
649pub fn register(
650    input: Staged<'_>,
651    members: &[Staged<'_>],
652    bits: &dyn PeekBits,
653    admit: Admit<'_>,
654    loaded: &mut Loaded<'_>,
655) -> Result<Registered, Failure> {
656    let mut sorted: Vec<&Staged<'_>> = members.iter().filter(|m| m.id != input.id).collect();
657    sorted.sort_by(|a, b| a.id.as_bytes().cmp(b.id.as_bytes()));
658    let ids: Vec<&str> = sorted.iter().map(|m| m.id).collect();
659    let mut reg = Registration::open(input, &ids, admit)?;
660    for m in sorted {
661        reg.member(m, bits, loaded)?;
662    }
663    reg.finish(bits, loaded)
664}
665
666/// The bits [`register_bytes`] peeked, served at each reach as the engine
667/// serves a peek file: copied into a buffer charged to `M_X`.
668struct Peeked<'a> {
669    ids: Vec<&'a str>,
670    bits: Vec<Bits>,
671}
672
673impl PeekBits for Peeked<'_> {
674    fn load(&self, id: &str, meter: &Arc<Meter>, hooks: &dyn Hooks) -> Result<Bits, Failure> {
675        let Some(i) = self.ids.iter().position(|x| *x == id) else {
676            return Err(internal());
677        };
678        let Some(peeked) = self.bits.get(i) else {
679            return Err(internal());
680        };
681        Bits::copied(peeked, meter, hooks)
682    }
683}
684
685/// [`register`] from bytes, each bundle named by its id and its bits
686/// peeked here first, each on a meter of its own (an unbounded budget, the
687/// context's limits), as the engine's peek pass would: X's peek failure
688/// first, then the member's of least id (2.3, rule 1). The tests' path to
689/// the engine's.
690pub fn register_bytes(view: View<'_>, admit: Admit<'_>) -> Result<Registered, Failure> {
691    let context = &admit.env.context;
692    let mut sorted: Vec<&super::Member> = view
693        .members
694        .iter()
695        .filter(|m| m.id != view.input.id)
696        .collect();
697    sorted.sort_by(|a, b| a.id.as_bytes().cmp(b.id.as_bytes()));
698    let ids: Vec<&str> = sorted.iter().map(|m| m.id.as_str()).collect();
699    if !in_order(&ids, &view.input.id) {
700        return Err(internal());
701    }
702    let peek_of = |m: &super::Member| {
703        let meter = Meter::for_input(&context.limits, Arc::new(Unbounded), Reservation::Input);
704        peek(
705            &RawStr::from(m.id.as_str()),
706            Data::Bytes(&m.data),
707            context,
708            &meter,
709            admit.hooks,
710        )
711    };
712    let mut peeked = Peeked {
713        ids: vec![view.input.id.as_str()],
714        bits: vec![peek_of(view.input)?],
715    };
716    for m in &sorted {
717        match peek_of(m) {
718            Ok(b) => {
719                peeked.ids.push(&m.id);
720                peeked.bits.push(b);
721            }
722            Err(Failure::Input(r)) => return Err(dependency_failed(&m.id, Class::Input(r))),
723            Err(f) => return Err(f),
724        }
725    }
726    let names: Vec<RawStr> = sorted.iter().map(|m| RawStr::from(m.id.as_str())).collect();
727    let staged: Vec<Staged<'_>> = sorted
728        .iter()
729        .zip(&names)
730        .map(|(m, name)| Staged {
731            id: &m.id,
732            name,
733            data: Data::Bytes(&m.data),
734        })
735        .collect();
736    let x_name = RawStr::from(view.input.id.as_str());
737    let input = Staged {
738        id: &view.input.id,
739        name: &x_name,
740        data: Data::Bytes(&view.input.data),
741    };
742    register(input, &staged, &peeked, admit, &mut |_, _| Ok(()))
743}