On this page

Aether
- Aether

Aether

Use md.Aether from the public package namespace.

class Aether(*args: object, **kwargs: object)[source]

The global singleton root that owns all AethericFrame instances.

Aether is the top-level runtime host for Melder. It owns the named frame registry, the always-present default frame, and the frame-level services that other runtime objects resolve through when they need configuration, conduit, cluster, spell, or DevOps state.

Contract:

Enforces singleton construction through __new__.

Owns the lifecycle of registered AethericFrame instances.

Owns the default frame and ensures it exists while the singleton is live.

Hosts singleton-level subsystems such as Nexus, Crystallizer, and the utility system.

Hosts the singleton MutationResearch root above frame-local runtime state.

Hosts ReleaseManagedSpell, the registry managed objects are given back through: built last at boot, cleaned right after the frames.

Owns one optional Aether root configuration that applies policy into the hosted utility system.

Becomes reinitializable only after cleanup() fully resets singleton state.

Threading / Concurrency:

Uses the class-level _lock to serialize singleton construction and reset.
Uses the instance _lock to guard cleanup and frame-registry mutation.

Lifecycle / Cleanup:

Cleans registered frames before dropping singleton-level references.
Resets _instance and _initialized so tests or later runtime flows can create a fresh singleton after teardown.

Registration:: MELDER KERNEL - guarded. Aether() returns the process singleton; users construct it (that IS the norm), but it is never bound as a spell.
Subsystem Context:: Layer 1 - the substrate everything else hangs from. It owns the named frame registry and hosts the singleton subsystems: AetherUtilitySystem, Crystallizer, Nexus, the MutationResearch root, the LoadGate and ReleaseManagedSpell. All three subsystem roots are constructed EAGERLY in __init__, in that order - Crystallizer leads because the other two read it out of this host as they build - and the release registry is built last, because nothing reads it at boot.
System Context:: Under V3 Horizon LAZY FRAMES, import melder and the first Aether() create ZERO frames - the eager default-frame construction is gone. The first Spellbook births the frame it names via _ensure_frame (get-or-create is the intended semantic), and a collapsed configuration falls back to a lazily created "default". The boot ORDER is load-bearing: Aether|AetherUtilitySystem -> Crystallizer -> MutationResearch -> Nexus -> AethericFrame -> Spellbook -> Conduit|Ward. The LoadGate is constructed BEFORE any frame can exist, which is precisely why a mid-load-born frame still inherits gate coverage - a crystallizer load acquires exclusive system authority and every new-root transaction waits at wait_for_passage. Hosting Nexus, Crystallizer, and MutationResearch PRIVATELY rather than exposing them on the public surface is what keeps the substrate hidden: Nexus is the public AR root, and reaching AR or mutation control through Aether is deliberately not a supported path.

AGENT_ACCESS: public

AGENT_PURPOSE:: access: public. The global singleton root. Aether() returns the process-wide instance and boots the hidden substrate (utility system, Crystallizer, Nexus, LoadGate). Creates ZERO frames - the first Spellbook births the frame it names. Use create_configuration()/configure()/activate() for root logger policy, attach_logger(...) to install one directly.

cleanup() → None[source]

Cleanup the entire Aether singleton and all owned frame/subsystem state.

Purpose:: Tear down the global runtime host, including every owned frame and singleton-level subsystem, so a later clean bootstrap starts from a truly empty root.

Contract:

Idempotent.

Cleans owned frames before dropping singleton-level references.

Cleans the hosted Nexus singleton and utility system when they exist.

Cleans ReleaseManagedSpell right after the frames: their root stores unregister their pools as they are torn down, so the registry is empty when it is retired.

Resets singleton bootstrap state in a finally, so Aether() can construct a fresh root even when a child cleanup fails: the child error is logged and re-raised, but this cleaned instance is never republished as the singleton (BUG-149 regression contract, 2026-07-17 audit). A failed child keeps its own singleton/lifecycle state; only this root's constructibility is recovered here.

Logger cleanup is performed after frame and subsystem teardown.

Returns:: None.

cleanup_aetheric_frames() → None[source]

Cleanup every frame currently owned by the singleton.

Contract:

Iterates over a snapshot of the frame registry.

Attempts every frame cleanup even if one frame raises.

Logs cleanup failures instead of stopping the full singleton teardown on the first frame error.

Returns:: None.

property logger: IChannelLogger | Logger | None

Return the raw logger currently wrapped by the internal SafeLogger.

Contract:

Exposes the underlying logger object for diagnostics or replacement.

Returns None when the wrapper currently holds the null logger.

Returns:: The raw logger object, or None if no logger is set.

attach_logger(logger: IChannelLogger | Logger | None) → None[source]

Attach one real logger after Aether boot.

Purpose:: Aether is created too early in runtime boot for a real logger to be attached reliably in __init__. This method is the explicit post-boot logger-attachment seam.

Contract:

Aether starts with a null SafeLogger wrapper and no attached raw logger.

Passing a real logger attaches it through the SafeLogger facade.

Passing None resets Aether back to the null logger wrapper.

Successful replacement RETIRES the displaced owned wrapper (best-effort cleanup; BUG-278, 2026-07-17 audit) so a cleanup-capable sink can never be orphaned by re-attachment.

Same-sink re-attachment never tears the sink down: the displaced wrapper is retired only when the underlying raw sinks differ (sink-identity aliasing law, mirrors BUG-279).

Parameters:: logger -- Real logger object to attach, or None to detach back to the null logger wrapper.
Returns:: None.

enable_logging(logger: IChannelLogger | Logger | None = None) → None[source]

Enable Aether's own logger after boot.

Purpose:: Attach one explicit logger when provided, otherwise try the current automatic channel logger path through AetherUtilitySystem.

Contract:

Passing an explicit logger always uses the direct safe-logger attachment path and does not require Aether root configuration.

Calling this method without an explicit logger requires:

an installed and activated AetherConfiguration

automatic channel logger activation enabled in that config

at least one automatic provider path registered on the hosted utility system (channel resolver or default logger)

The automatic path fails fast when that setup is incomplete instead of silently leaving Aether on the null logger path.

The automatic result is validated BEFORE publication (BUG-278, 2026-07-17 audit): a resolution that yields no logger raises while the previously attached working logger stays installed and untouched.

A successful automatic attach retires the displaced owned wrapper unless it shares the same underlying raw sink.

Parameters:: logger -- Optional explicit logger override.
Returns:: None.
Raises:: RuntimeError -- If the automatic logger path is requested before Aether root configuration has been activated, if automatic channel logger activation is disabled, if no automatic logger provider has been registered into the utility system, or if automatic resolution returns no logger (the existing logger is preserved in that case).

property configuration: AetherConfiguration | None

Return the installed Aether root configuration, if any.

Contract:

Returns the INSTALLED configuration by reference, not a copy. None means nothing has been installed yet.

Threading:: Unsynchronized read; a snapshot only.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: Installed root config.
Return type:: Optional[AetherConfiguration]

property configured: bool

Return whether an Aether root configuration is installed.

Contract:

Reports that a configuration has been INSTALLED, which is weaker than being usable: configure() accepts a configuration that has not been activated, so configured can be True while activate() would still refuse.

Threading:: Unsynchronized read; a snapshot only.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: True when a config is installed.
Return type:: bool

property process_wide_unique_spell_ids: bool

True when one spell_id may exist only once per process.

Purpose:: Say which regime governs this process without reading private state. configuration cannot answer it: before the first frame it is the policy the next first frame will seal, and after it a first frame may have sealed frozen defaults without the root ever being configured. The crystallizer records this value in the Aether twin and keys spell custody by it, and a restore uses it to tell whether a recorded regime can still be installed.

Contract:

Once any frame exists: the regime the first frame sealed. configure() and activate() refuse any other while frames exist, so the answer cannot change until every frame is gone.

Before the first frame: the installed configuration's value (the one the next first frame seals), or True when nothing is installed (the default policy a first frame would install).

Read-only: installs, freezes and creates nothing.

Threading:: Lock-free point-in-time read, like the frame lookups. Frame birth seals the regime before it inserts the frame, both under the Aether lock, so a reader that sees a frame also sees the sealed value. The installed configuration is read once into a local so a concurrent configure() cannot swap it between the check and the read.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:

RuntimeError -- If Aether has been cleaned.
TypeError -- If the installed configuration's stored regime is no longer a bool (its defensive read).

Returns:

True for process-wide spell ids, False for per-frame spell ids.

Return type:

bool

Type:

Return the spell-id regime in force

property aetheric_mediator: Mediator

Return the Aether-owned admission plane.

Purpose:: Give subsystems the one handle they need to open a top-level transaction, without any of them constructing a plane of their own.

Contract:

EAGER, like every other hosted root. The plane is constructed with Aether (owner constraint 3) because it must exist before anything it governs; a lazy accessor would let a frame be born before the authority that admits frame-level work.

Returns the OWNED instance by reference. Aether cleans it; callers use it and never clean it.

ONE-WAY: subsystems reach the plane through here. The plane holds no reference back to Aether and must never acquire one.

Threading:: Unsynchronized read; a snapshot only. The plane owns its own locking.
Lifecycle / Cleanup:: Guarded by check_cleaned(). Cleaned by Aether.cleanup right after the LoadGate, so parked claim-table waiters are woken early.

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: The Aether-owned admission plane.
Return type:: AethericMediator

property mutation_research: MutationResearch

Return the Aether-owned MutationResearch root.

Contract:

EAGER, as of the owner ruling 2026-08-03. The root is built in __init__ alongside Crystallizer and Nexus, so this returns a stored reference and never constructs. It was a lazy resolver until that ruling.

Returns the process-wide singleton, not an Aether-private instance.

A CLEANED root raises rather than being rebuilt; cleanup is final.

Threading:: Unsynchronized read; a snapshot only.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: Hosted mutation-research singleton.
Return type:: MutationResearch

property crystallizer: Crystallizer

Return the Aether-owned crystallizer root.

Purpose:: Close the third of four hosted-subsystem accessors. Aether already CONSTRUCTS, OWNS and CLEANS this root - it simply had no public way to hand back the handle it was holding, so callers reached it by calling Crystallizer() and relying on singleton re-entry. That works, but it reads like construction and is not: a bare Crystallizer() returns THIS instance, and would raise ValueError if Aether had not already built it.

Contract:

EAGER, like aetheric_mediator and unlike mutation_research. The root is constructed with Aether (__init__) because it is unfolded into every frame, spellbook and conduit, and into MutationResearch as the passive emission sink.

Returns the OWNED instance by reference. Aether cleans it; callers use it and never clean it.

Returns the PROCESS-WIDE singleton, not an Aether-private instance - it is the same object Crystallizer() returns.

Reports the root as it stands. This is an existence read, not a liveness one: a returned crystallizer may be unconfigured and inactive, and activated is the separate bit that answers that.

Threading:: Unsynchronized read; a snapshot only. The root owns its own locking.
Lifecycle / Cleanup:: Guarded by check_cleaned(). Cleaned by Aether.cleanup.

Raises:: RuntimeError -- If the Aether has been cleaned.
Returns:: The Aether-owned crystallizer root.
Return type:: Crystallizer

property nexus: Nexus

Return the Aether-owned Rift-domain root.

Purpose:: The fourth hosted-subsystem accessor, and the same story as crystallizer: Aether constructs Nexus(aether=self) in __init__, owns it and cleans it, but exposed no public handle. A bare Nexus() reaches this instance through singleton re-entry and refuses with ValueError on a genuine first construction without a host, so the constructor was never the real door.

Contract:

EAGER. Constructed with Aether, before any Rift can exist.

Returns the OWNED instance by reference. Aether cleans it; callers use it and never clean it.

Returns the PROCESS-WIDE singleton - the same object Nexus() returns.

Existence, not liveness. The returned Nexus may be unconfigured and disabled; enable() is what makes it live, and Nexus is the one subsystem that seals its own configuration when you call it.

Threading:: Unsynchronized read; a snapshot only. The root owns its own locking.
Lifecycle / Cleanup:: Guarded by check_cleaned(). Cleaned by Aether.cleanup.

Raises:: RuntimeError -- If the Aether has been cleaned.
Returns:: The Aether-owned Rift-domain root.
Return type:: Nexus

property activated: bool

Return whether the Aether root configuration has been applied.

Contract:

Reports that Aether itself is live. It implies the installed configuration was activated first, because activate() refuses otherwise.

Threading:: Unsynchronized read; a snapshot only.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: True when root config has been activated.
Return type:: bool

create_configuration() → AetherConfiguration[source]

Create a fresh Aether root configuration object.

Contract:

FACTORY ONLY: returns a FRESH, unattached AetherConfiguration and does NOT install it. Installation is configure(...), and activation of the configuration is a further separate step.

Threading:: Unsynchronized read; a snapshot only.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: New mutable config object.
Return type:: AetherConfiguration

create_configuration_builder() → AetherConfigurationBuilder[source]

Create a fresh fluent builder for Aether root configuration assembly.

Purpose:: Mirror the repo's configuration-builder workflow at the Aether root so callers do not need to import the builder directly just to assemble the first logger-policy slice.

Returns:: New one-shot builder instance.
Return type:: AetherConfigurationBuilder

configure(configuration: AetherConfiguration) → None[source]

Install one root configuration on Aether.

Parameters:: configuration -- Root configuration object to install.

Contract:

INSTALLS ONLY - it does not validate, freeze or activate the configuration, and it accepts one that is still mutable. Passing an unactivated configuration succeeds here and fails later at activate().

Type-checked: a non-AetherConfiguration raises TypeError.

Replaces any previously installed configuration outright.

SEALED REGIME (0.2.8209): while any frame exists the spell-id regime was sealed when the first frame was born and is in force; a configuration whose process_wide_unique_spell_ids differs is refused and nothing is installed, so configuration can never report a regime that does not apply. With no frame, any regime is accepted and the next first frame seals it.

Threading:: The regime check and the install run under the Aether lock that frame birth holds, so a concurrent first frame either seals from this configuration or is seen by the check.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned, or frames exist and the configuration's spell-id regime differs from the sealed one.
TypeError -- If configuration is not an AetherConfiguration.

Returns:

None.

activate(configuration: AetherConfiguration | None = None) → None[source]

Activate the installed Aether root configuration.

Parameters:: configuration -- Optional configuration to install before activation.

Contract:

ORDERING RULE: THE CONFIGURATION MUST BE ACTIVATED BEFORE AETHER CAN BE. Activating Aether with a merely-frozen configuration raises RuntimeError, so configuration.activate() comes first.

Passing a configuration here is a convenience that calls configure() first; omitting it uses whatever is already installed.

Refuses when nothing is configured, so the two failure modes are distinct: "not configured" and "configuration not activated".

Re-checks the SEALED REGIME (0.2.8209): an installed configuration that was still mutable when installed can have its process_wide_unique_spell_ids changed afterwards, so activation refuses it while frames exist exactly as configure() would.

Threading:: The regime check runs under the Aether lock; the rest of the state transition is unchanged.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:

RuntimeError -- If Aether is not configured, the installed configuration has not been activated, or frames exist and its spell-id regime differs from the sealed one.
TypeError -- If a supplied configuration is not an AetherConfiguration.

Returns:

None.

acquire_load_authority(label: str, drain_timeout: float = 30.0) → None[source]

Public API

Grant the calling thread exclusive load authority over the system.

Purpose:: Entry verb for crystallizer loads: claim the singleton LoadGate, then DRAIN - wait for every in-flight transaction session across all live frames to finish - so replay begins against a quiescent registry. New root transactions from other threads park at the gate; the loading thread's own per-verb transactions pass free.

Contract:

Claims the gate FIRST (barring new roots), then polls every live frame's TransactionMediator active-session count to zero.

Frames are re-snapshotted each poll slice: frames born mid- drain (e.g. by a Spellbook on another thread) are counted.

On drain timeout the gate is RELEASED before raising - a failed acquisition never leaves the system barred.

Parameters:

label -- Load descriptor surfaced to blocked callers (typically the crystal source label).
drain_timeout -- Maximum seconds to wait for in-flight sessions to drain.

Raises:

RuntimeError -- If another load already holds the gate, or the drain does not complete before "drain_timeout".
ValueError -- If label is falsy.

Threading:: Drain polling runs WITHOUT the Aether lock held; each slice takes a registry snapshot under the lock and releases it before sleeping.

Returns:: None.

release_load_authority() → None[source]

Public API

Release load authority and wake every parked root-transaction start.

Purpose:: Exit verb for crystallizer loads; pairs with acquire_load_authority (callers wrap the load span in try/finally).

Contract:

Delegates to LoadGate.release: only the holder thread may release, and all condition waiters are notified.

Raises:: RuntimeError -- If the gate is not held, or held by a different thread.
Returns:: None.

enroll_load_worker(thread_ident: int) → None[source]

Public API

Enroll one worker thread into the current load-authority span.

Purpose:: Parallel restore admission (parallel_restore_ulid_identity S3): the loading thread names its scheduler pool threads so restore units pass the LoadGate for the span while every foreign thread keeps parking exactly as before.

Contract:

Delegates to LoadGate.enroll_worker: HOLDER-ONLY, active- span-only, idempotent set semantics; the cohort never survives the span (release/cleanup clear it).

Parameters:

thread_ident -- The worker thread's identity (threading.Thread.ident). Positive int; bools refuse.

Raises:

RuntimeError -- If the LoadGate is unavailable or cleaned, no load span is active, or the caller is not the span holder.
ValueError -- If thread_ident is not a positive int.

Returns:

None.

withdraw_load_worker(thread_ident: int) → None[source]

Public API

Withdraw one worker thread from the current load-authority span.

Purpose:: Pairs with enroll_load_worker so the span owner can retire a worker mid-span; loaders withdraw their pool in finally.

Contract:

Delegates to LoadGate.withdraw_worker: HOLDER-ONLY, active- span-only, idempotent discard; a withdrawn thread parks at its next passage check.

Parameters:

thread_ident -- The worker thread identity to remove. Positive int; bools refuse.

Raises:

RuntimeError -- If the LoadGate is unavailable or cleaned, no load span is active, or the caller is not the span holder.
ValueError -- If thread_ident is not a positive int.

Returns:

None.

find_frame(aetheric_frame_name: str) → AethericFrame | None[source]

Return the registered, live frame with this exact name, or None, without creating any frame.

Purpose:: Let a host that creates frames (by constructing Spellbooks) find them again without reading Aether's private registry. The frame-scoped calls such as get_conduit_cloud and the conduit lookups resolve "default" through the lazy creation path, so asking them about a missing "default" creates it and, on a world with no frames yet, seals the Aether configuration. This lookup never does either.

Contract:

NONCREATING, "default" included: an absent frame returns None. No frame is created, no plane claim is taken, and the Aether configuration is neither installed nor frozen.

Exact name match against the frame registry, which holds every frame ("default" is an ordinary entry once something has created it).

A registered frame that already reads cleaned (its cleanup has started but has not yet detached it from Aether) returns None, like a detached one.

Returns a borrowed reference and grants no lease. Aether owns every frame, and a Nexus removal, AethericFrame.cleanup() or Aether.cleanup() may clean it at any time, after which the reference must not be used. A later frame can reuse the name: compare identity (is) to tell them apart.

get_frame raises instead of returning None; list_frame_names lists the live names.

Threading:: One dict.get on the registry, without the Aether lock: a point-in-time answer. Taking no lock keeps the lookup off the Aether -> Nexus lock order used while a cleaned frame is detached.

Parameters:

aetheric_frame_name -- Exact frame name, for example "default" or the name a Spellbook was constructed with.

Returns:

The live frame, or None when no live frame has this name.

Return type:

Optional[AethericFrame]

Raises:

TypeError -- If aetheric_frame_name is not a string.
RuntimeError -- If Aether has been cleaned.

get_frame(aetheric_frame_name: str) → AethericFrame[source]

Return the registered, live frame with this exact name, or raise. Never creates a frame.

Purpose:: The raising counterpart of find_frame, for callers that expect the frame to exist.

Contract:

Resolves exactly as find_frame: noncreating ("default" included), exact name, frames that read cleaned are absent, and the reference is borrowed with no lease.

The not-found message starts with "Aetheric frame '<name>' does not exist.", like the frame errors of the conduit lookups, and says how to create the frame or test for it without raising.

Threading:: As find_frame: one registry read, no lock.

Parameters:

aetheric_frame_name -- Exact frame name.

Returns:

The live frame.

Return type:

AethericFrame

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If no live frame has this name.
RuntimeError -- If Aether has been cleaned.

list_frame_names() → tuple[str, ...][source]

Return the names of the live frames in the order they were created, without creating any frame.

Purpose:: Let a host see which frames exist - for example, whether constructing a Spellbook will create its frame or join an existing one - without reading Aether's private registry.

Contract:

NONCREATING: an Aether with no frames returns an empty tuple, and "default" appears only once something has created it.

Built from one copy of the registry, so the tuple is a snapshot: frames created or cleaned later do not change it, and a listed frame may be gone by the time it is used - resolve it with find_frame.

Frames that already read cleaned are left out.

Order is registration order.

Threading:: One dict.copy() of the registry, without the Aether lock; the copy is atomic, so a concurrent frame creation cannot interrupt the listing.

Returns:: Live frame names.
Return type:: tuple[str, ...]
Raises:: RuntimeError -- If Aether has been cleaned.

list_root_conduit_ids(aetheric_frame_name: str = 'default') → tuple[str, ...][source]

Return the ids of the ROOT conduits registered in one frame.

Contract:

Covers normal root conduits only (the frame's root registry). Lesser scopes, named or anonymous, are never listed; get_conduit_by_id reaches any live conduit by id and the frame's ConduitCloud lists its named scopes.

Returns a TUPLE SNAPSHOT; it goes stale as roots are conjured or cleaned.

Scoped to one frame: "default" resolves lazily, a custom frame must exist.

Threading:: Reads the frame's root registry without taking a lock; a point-in-time answer.

Parameters:

aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

Snapshot of root conduit ids.

Return type:

Tuple[str, ...]

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the specified custom frame does not exist.
RuntimeError -- If Aether has been cleaned.

list_root_conduit_names(aetheric_frame_name: str = 'default') → tuple[str, ...][source]

Return the names of the ROOT conduits registered in one frame.

Contract:

Covers normal root conduits only. Named lesser scopes are not roots and are never listed; the frame's ConduitCloud.list_conduit_names() lists every named scope, roots included.

Returns a TUPLE SNAPSHOT; it goes stale as roots are conjured or cleaned.

Scoped to one frame: "default" resolves lazily, a custom frame must exist.

Threading:: Reads the frame's root name registry without taking a lock; a point-in-time answer.

Parameters:

aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

Snapshot of root conduit names.

Return type:

Tuple[str, ...]

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the specified custom frame does not exist.
RuntimeError -- If Aether has been cleaned.

count_root_conduits(aetheric_frame_name: str = 'default') → int[source]

Return the number of ROOT conduits registered in one frame.

Contract:

Counts normal root conduits only; lesser scopes are never counted.

Reads the size of the frame's root registry directly; it builds no id list.

Scoped to one frame: "default" resolves lazily, a custom frame must exist.

Threading:: Reads the frame's root registry without taking a lock; a point-in-time count.

Parameters:

aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

Number of registered root conduits.

Return type:

int

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the specified custom frame does not exist.
RuntimeError -- If Aether has been cleaned.

has_root_conduit_id(conduit_id: str, aetheric_frame_name: str = 'default') → bool[source]

Return whether a ROOT conduit with this id is registered in one frame.

Contract:

Answers over normal root conduits only, so False also covers "this is a live lesser scope's id"; get_conduit_by_id resolves any live conduit.

One membership test on the frame's root registry.

Scoped to one frame, so False can mean "exists, but in a different frame".

Threading:: Reads the frame's root registry without taking a lock; a point-in-time answer.

Parameters:

conduit_id -- Root conduit id to check.
aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

True when a root conduit with this id is registered in the frame.

Return type:

bool

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the specified custom frame does not exist.
RuntimeError -- If Aether has been cleaned.

has_root_conduit_name(name: str, aetheric_frame_name: str = 'default') → bool[source]

Return whether a ROOT conduit with this name is registered in one frame.

Contract:

Answers over normal root conduits only, so False also covers "this names a live lesser scope"; ConduitCloud.has_conduit_name answers over every named scope.

One membership test on the frame's root name registry.

Scoped to one frame, so False can mean "exists, but in a different frame".

Threading:: Reads the frame's root name registry without taking a lock; a point-in-time answer.

Parameters:

name -- Root conduit name to check.
aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

True when a root conduit with this name is registered in the frame.

Return type:

bool

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the specified custom frame does not exist.
RuntimeError -- If Aether has been cleaned.

find_root_conduit_id_by_name(name: str, aetheric_frame_name: str = 'default') → str | None[source]

Return the id of the ROOT conduit registered under a name in one frame, if any.

Contract:

Answers over normal root conduits only; a named lesser scope's name returns None (ConduitCloud.find_conduit_id_by_name answers over every named scope).

Returns None instead of raising when no root has the name.

Scoped to one frame: "default" resolves lazily, a custom frame must exist.

Threading:: One read of the frame's root name registry without taking a lock.

Parameters:

name -- Root conduit name to resolve.
aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

The root conduit id, or None when no root has this name.

Return type:

Optional[str]

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the specified custom frame does not exist.
RuntimeError -- If Aether has been cleaned.

get_root_conduit_by_name(name: str, aetheric_frame_name: str = 'default') → Conduit[source]

Return the ROOT conduit registered under a name in one frame.

Contract:

Resolves normal root conduits only. A named lesser scope is not a root and raises here; get_conduit_by_name resolves any named conduit, roots included, to the same object for a root.

Returns a borrowed reference; grants no lease.

Scoped to one frame: "default" resolves lazily, a custom frame must exist.

Threading:: Reads the frame's root registries without taking a lock.

Parameters:

name -- Root conduit name to resolve.
aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

The matching root conduit.

Return type:

Conduit

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the custom frame does not exist, or no root conduit in the frame has this name (the message names the frame).
RuntimeError -- If Aether has been cleaned.

get_root_conduit_by_id(conduit_id: str, aetheric_frame_name: str = 'default') → Conduit[source]

Return the ROOT conduit with an id in one frame.

Contract:

Resolves normal root conduits only. A lesser scope's id raises here; get_conduit_by_id resolves any live conduit, roots included, to the same object for a root.

Returns a borrowed reference; grants no lease.

Scoped to one frame: "default" resolves lazily, a custom frame must exist.

Threading:: One read of the frame's root registry without taking a lock.

Parameters:

conduit_id -- Root conduit id to resolve.
aetheric_frame_name -- Name of the target frame; a string, "default" when omitted.

Returns:

The matching root conduit.

Return type:

Conduit

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the custom frame does not exist, or no root conduit in the frame has this id (the message names the frame).
RuntimeError -- If Aether has been cleaned.

get_conduit_by_name(name: str, aetheric_frame_name: str = 'default') → Conduit[source]

Return the conduit registered under a name in one frame: a named root or an active named lesser.

Purpose:: Frame-wide discovery by name from the runtime root, so a named scope - a root, or a lesser created with create_lesser_conduit(name=...) at any depth - resolves without holding its parent.

Contract:

Answers over the frame's NAMED directory, the one its ConduitCloud owns: every named normal root and every active named lesser. The result is the same object as get_conduit_cloud(aetheric_frame_name).get_conduit_by_name(name).

Names are unique within a frame, not across frames, so the lookup is frame-scoped. The frame is optional and defaults to "default"; a scope in another frame is found only by naming that frame.

A named lesser returned to its pool retires its name first, so it does not resolve; neither do anonymous lessers (get_conduit_by_id resolves those) nor cleaned scopes.

Returns a borrowed reference and grants no lease: the scope's owner may return or clean it at any time, after which the reference must not be used.

Root-only resolution is get_root_conduit_by_name.

Threading:: One read of the Cloud's directory under the Cloud's leaf lock; invokes no callbacks.

Parameters:

name -- Exact name of the scope.
aetheric_frame_name -- Name of the frame to search; a string, "default" when omitted.

Returns:

The named conduit.

Return type:

Conduit

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the custom frame does not exist, or no named scope in the frame has this name (the message names the frame).
RuntimeError -- If Aether or the frame's Cloud has been cleaned.

get_conduit_by_id(conduit_id: str, aetheric_frame_name: str = 'default') → Conduit[source]

Return any live conduit in one frame by id: a root, or a named or anonymous lesser at any depth.

Purpose:: Lead an id taken from a record, a log line or a descriptor back to the live scope from the runtime root, whether or not that scope has a name.

Contract:

Answers over LIVE conduits: the frame's root registry first, then every root's attached lesser lineage, depth-first through each ConduitWard. Anonymous lessers resolve here; the frame's ConduitCloud holds named scopes only and does not see them.

Reads snapshots, never live registries: a scope attached or returned while the lookup runs may or may not be found, and the lookup never fails because of it.

A lesser returned to its pool is detached from its parent and a cleaned scope leaves its registry, so neither resolves.

Returns a borrowed reference and grants no lease.

Frame-scoped; the frame is optional and defaults to "default". Root-only resolution is get_root_conduit_by_id.

Cost grows with the number of live scopes in the frame: a discovery call, not a hot path.

Threading:: Takes no lock and invokes no callbacks.

Parameters:

conduit_id -- Id of the conduit.
aetheric_frame_name -- Name of the frame to search; a string, "default" when omitted.

Returns:

The live conduit with this id.

Return type:

Conduit

Raises:

TypeError -- If aetheric_frame_name is not a string.
ValueError -- If the custom frame does not exist, or no live conduit in the frame has this id (the message names the frame).
RuntimeError -- If Aether has been cleaned.

get_conduit_cloud(aetheric_frame_name: str = 'default') → ConduitCloud[source]

Return the frame-local conduit and cluster service for one frame.

Purpose:: Expose the frame-owned ConduitCloud through Aether so callers can start from the top-level runtime host and move into the frame-local conduit and cluster service surface explicitly.

Parameters:: aetheric_frame_name -- Name of the target frame.
Returns:: The frame-local conduit cloud for the requested frame.
Return type:: ConduitCloud
Raises:: ValueError -- If the requested frame does not exist.

Topic reference · Full contents