frame-core 0.1.0

Component model, lifecycle, process isolation, and WASM module host
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

//! Correct beamr scheduler composition for hot-loading hosts.
//!
//! `Scheduler::with_services` silently installs an EMPTY BIF registry
//! (beamr 0.15.1 `scheduler/mod.rs:1010-1024`). Import resolution is
//! bif-registry-first, so every `erlang:*` import in hot-loaded bytecode
//! resolves Deferred; guard-BIF dispatch requires a Native entry
//! (beamr `guards.rs:193-195`) and refuses at the first arithmetic
//! instruction with a process-fatal
//! `InvalidOperand("guard bif native import")` — the composition defect
//! attributed in `frame-host/attribution/gcbif-wedge/` and Artemis's
//! 2026-07-18 gcbif probe report (Round 2).
//!
//! Every frame scheduler that hot-loads component bytecode must therefore be
//! composed through [`compose_scheduler`], which populates the registry via
//! beamr's canonical gate-1 population path
//! ([`beamr::native::bifs::register_gate1_bifs`]) and constructs through
//! [`Scheduler::with_services_and_code_server`]. As defense in depth,
//! [`crate::registry::ComponentRegistry::start`] refuses any hot-loaded
//! module whose committed import table still defers an `erlang:*` entry.

use std::sync::Arc;

use beamr::atom::AtomTable;
use beamr::module::ModuleRegistry;
use beamr::native::{BifRegistryImpl, NativeRegistrationError};
use beamr::scheduler::{Scheduler, SchedulerConfig, SchedulerServices};
use thiserror::Error;

/// A typed refusal from scheduler composition.
#[derive(Debug, Error)]
pub enum SchedulerCompositionError {
    /// The canonical BIF population path refused a registration.
    #[error("BIF registry population failed: {source}")]
    BifRegistration {
        /// Exact beamr registration refusal.
        #[source]
        source: NativeRegistrationError,
    },
    /// beamr refused scheduler construction.
    #[error("scheduler construction failed: {detail}")]
    Construction {
        /// Exact beamr construction refusal.
        detail: String,
    },
}

/// Composes a scheduler whose BIF registry is populated BEFORE any module
/// can load against it.
///
/// The atom table (seeded with beamr's common atoms) and the gate-1-populated
/// BIF registry are handed to [`Scheduler::with_services_and_code_server`] so
/// load-time import resolution can bind `erlang:*` imports to Native entries.
/// Never construct a hot-loading scheduler through bare
/// [`Scheduler::with_services`]: it installs an empty BIF registry and every
/// `erlang:*` import silently defers into a process-fatal dispatch refusal.
///
/// # Errors
///
/// Returns a typed failure when gate-1 BIF population or beamr scheduler
/// construction refuses.
pub fn compose_scheduler(
    config: SchedulerConfig,
    services: SchedulerServices,
    module_registry: Arc<ModuleRegistry>,
) -> Result<Scheduler, SchedulerCompositionError> {
    let atom_table = Arc::new(AtomTable::with_common_atoms());
    let bif_registry = Arc::new(BifRegistryImpl::new());
    beamr::native::bifs::register_gate1_bifs(&bif_registry, &atom_table)
        .map_err(|source| SchedulerCompositionError::BifRegistration { source })?;
    Scheduler::with_services_and_code_server(
        config,
        services,
        module_registry,
        atom_table,
        bif_registry,
    )
    .map_err(|detail| SchedulerCompositionError::Construction { detail })
}