Struct ComponentRegistry 

pub struct ComponentRegistry { /* private fields */ }

Registry for component definitions and their native process trees.

Implementations

impl ComponentRegistry

pub fn update_fragment_content( &self, key: &FragmentKey, held: ComponentIncarnation, content: Vec<u8>, ) -> Result<(), RegistryError>

Applies one atomic whole-content swap to a declared fragment of a Running incarnation, then publishes the fragment-affecting news item (the stream carries the news; the snapshot stays the authority — F-5a R3).

Validation is identical to registration: the new content is checked against the registry’s caller-supplied max_fragment_bytes. The mid-flight-mutation race class is handled, not avoided: the swap and its Running/incarnation fence commit under the record’s content lock, so an update racing stop, crash, or remove either commits while the incarnation is still live (and is invisible the instant the incarnation leaves Running) or loses cleanly with the typed held-vs-current refusal.

Errors

Refuses an unregistered component, an unconfigured or exceeded byte limit, a non-Running component or stale incarnation (both the typed held-vs-current shape), an undeclared fragment id, and poisoned synchronization.

pub fn fragment_snapshot(&self) -> Result<Vec<FragmentRow>, RegistryError>

Returns the authoritative all-components fragment snapshot: one row per declared fragment of every component currently in Running, carrying current content bytes, sorted by FragmentKey canonical byte order (F-5a R3’s linearizable authority query; assembly ordering — the R4 tuple — belongs to the assembly crate, not here).

Per-component atomicity holds by construction: Running-ness is read once per record, the incarnation ordinal is the one minted by that entry into Running, and the record’s content lock is held while its rows are collected — a snapshot therefore contains ALL of a component’s fragments with one incarnation and no torn content, or none of them.

Errors

Returns a synchronization failure if registry state was poisoned, and surfaces a declared id missing from the live store as the typed unknown-fragment breach (impossible by construction, loud if broken).

impl ComponentRegistry

pub fn action_snapshot(&self) -> Result<Vec<ActionRow>, RegistryError>

Returns the authoritative all-components action snapshot: one row per declared action of every component currently in Running, sorted by ActionKey canonical byte order (F-6a R1/R3’s authority query).

Per-component atomicity holds by construction: a component’s complete batch rides its registration record, Running-ness is read once per record, and the incarnation ordinal is the one minted by that entry into Running — a snapshot therefore contains ALL of a component’s actions with one incarnation, or none of them.

Errors

Returns a synchronization failure if registry state was poisoned.

pub fn status( &self, id: ComponentId, ) -> Result<Option<ComponentStatus>, RegistryError>

Returns the current status snapshot, or None when unregistered.

Errors

Returns a synchronization failure if registry state was poisoned.

pub fn len(&self) -> Result<usize, RegistryError>

Returns the number of registrations, including Failed components.

Errors

Returns a synchronization failure if registry state was poisoned.

pub fn is_empty(&self) -> Result<bool, RegistryError>

Returns whether the registry has no component definitions.

Errors

Returns a synchronization failure if registry state was poisoned.

impl ComponentRegistry

pub fn new(scheduler: Arc<Scheduler>, config: LifecycleConfig) -> Self

Creates a registry over an embedding-owned scheduler.

The scheduler is never shut down by the registry. The caller must remove or stop every component before shutting it down.

pub fn subscribe( &self, capacity: NonZeroUsize, ) -> Result<LifecycleSubscription, RegistryError>

Adds a bounded lifecycle subscriber.

Each subscriber drops its own oldest event on overflow and increments its lag counter; publication never waits for a consumer.

Errors

Returns a synchronization failure if a prior panic poisoned the stream.

pub fn host_capabilities(&self) -> HostCapabilityFacade<'_>

Borrows the embedding host’s sole grant mutation and inspection facade.

This Rust host value has no BEAM representation and is never passed to a component entrypoint; component-facing code receives check-only paths.

pub fn capability_checker( &self, component_id: ComponentId, ) -> Result<CapabilityChecker, CapabilityMutationError>

Creates a retained check-only path for one registered component.

Errors

Refuses a missing component or poisoned capability table.

pub fn check_capability( &self, component_id: ComponentId, capability: &Capability, ) -> Result<CheckVerdict, CapabilityCheckError>

Performs a fresh capability check for one host-mediated consuming act.

Denials are returned as typed verdicts and emitted exactly once on the lifecycle stream. No verdict or authority token is retained.

Errors

Refuses a missing component or poisoned table/event synchronization.

pub fn register( &self, meta: ComponentMeta, bytecode: Vec<u8>, ) -> Result<(), RegistryError>

Validates and atomically registers metadata with its BEAM bytecode.

Errors

Refuses duplicate identities, missing/cyclic dependency edges, capability collisions, duplicate child keys, and absent/invalid policy.

pub fn start(&self, id: ComponentId) -> Result<(), RegistryError>

Starts one component after checking every dependency is Running.

Successful return means every child answered its declared mailbox probe.

Errors

Returns typed state, dependency, loader, spawn, liveness, or protocol failures. A runtime failure leaves an observable Failed registration.

pub fn stop(&self, id: ComponentId) -> Result<StopOutcome, RegistryError>

Stops a running component by draining children in declaration order and then observing the host supervisor’s Normal tombstone.

Errors

Returns typed in-flight, protocol, timeout, or non-normal exit failures.

pub fn remove(&self, id: ComponentId) -> Result<RemoveOutcome, RegistryError>

Stops if needed, unloads every loaded generation, and unregisters.

Errors

Refuses concurrent operations, running dependents, abnormal drain, unsafe purge, failed deletion, or post-delete lookup residue.

pub fn upgrade_bytecode( &self, id: ComponentId, bytecode: Vec<u8>, ) -> Result<(), RegistryError>

Replaces the registered bytecode a component’s NEXT start hot-loads — the F-7b hot-reload staging seam. The component identity, its registered metadata, grants, and durable branch are untouched: the branch outlives the bytes.

Only legal while the component is Registered or Stopped: the upgrade barrier drains and stops the old incarnation first, so new bytes never stage under a live tree.

Staging PURGES the retained old module generation (the C5 law: the wall is retention-based, so drain alone never re-opens loading — without this purge the third stop→stage→start lap of one registration refuses OldCodeStillRunning). The purge is the SAFE one: after an ordered stop nothing references old code, and a StillReferenced refusal here is the typed drain-failure signal, surfaced, never forced over.

Errors

Refuses concurrent operations and non-stopped states; surfaces a purge refusal as the drain failure it is. All typed.

pub fn component_incarnation( &self, id: ComponentId, ) -> Result<u64, RegistryError>

The component’s live incarnation ordinal — the per-identity mint, strictly increasing across every entry into Running (the registry-side freshness witness of the F-7b dev status report).

Errors

Refuses unknown identities and non-running components, typed.

pub fn component_module_generation( &self, id: ComponentId, ) -> Result<u64, RegistryError>

The current VM code generation of the component’s own module — the VM-side freshness witness of the F-7b dev status report (beamr’s per-name monotonic counter, surfaced not interpreted).

Errors

Refuses unknown identities, components that never loaded, and a module absent from the VM, all typed.

pub fn send_child( &self, id: ComponentId, child: impl Into<String>, message: i64, ) -> Result<(), RegistryError>

Sends an integer mailbox command to a named live child.

Errors

Refuses non-running components, unknown children, and monitor failures.

pub fn probe_child( &self, id: ComponentId, child: impl Into<String>, ) -> Result<i64, RegistryError>

Runs the child’s declared liveness mailbox round-trip and returns its integer state reply.

Errors

Refuses non-running components, unknown children, timeout, or failure.