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.

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, and the LoadGate. 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.
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.

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 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.

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

Raises:: RuntimeError -- If the object has been cleaned.
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".

Threading:: State transition applied under the Aether lock.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:

RuntimeError -- If Aether is not configured, or the installed configuration has not been activated.
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.

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

Return the registered root conduit identifiers for one frame.

Parameters:: aetheric_frame_name -- Name of the target frame.
Returns:: Snapshot of root conduit ids.
Return type:: Tuple[str, ...]
Raises:: ValueError -- If the specified frame does not exist.

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

Return the registered root conduit names for one frame.

Parameters:: aetheric_frame_name -- Name of the target frame.
Returns:: Snapshot of root conduit names.
Return type:: Tuple[str, ...]
Raises:: ValueError -- If the specified frame does not exist.

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

Return the number of registered root conduits for one frame.

Parameters:: aetheric_frame_name -- Name of the target frame.

Contract:

Derived from list_conduit_ids(...), so it BUILDS THE WHOLE ID LIST just to take its length. Prefer it for clarity, not for hot paths.

Scoped to one aetheric frame.

Threading:: Inherits the listing call's synchronization; a point-in-time count.
Lifecycle / Cleanup:: Guarded indirectly, via the listing call it delegates to.

Raises:: RuntimeError -- If Aether has been cleaned.
Returns:: Number of registered root conduits.
Return type:: int

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

Return whether one root conduit id exists in one frame.

Parameters:

conduit_id -- Root conduit id to check.
aetheric_frame_name -- Name of the target frame.

Contract:

A LINEAR SCAN, not a dict lookup: it materializes the full id list and tests membership in it. Fine for occasional checks, wasteful in a loop.

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

Threading:: Inherits the listing call's synchronization; a point-in-time answer.
Lifecycle / Cleanup:: Guarded indirectly, via the listing call it delegates to.

Raises:: RuntimeError -- If Aether has been cleaned.
Returns:: True when the conduit id exists in the target frame.
Return type:: bool

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

Return whether one root conduit name exists in one frame.

Parameters:

name -- Root conduit name to check.
aetheric_frame_name -- Name of the target frame.

Contract:

A LINEAR SCAN over the name list, like the id variant.

Only NAMED conduits can match, so False also covers "registered but unnamed". Scoped to one aetheric frame.

Threading:: Inherits the listing call's synchronization; a point-in-time answer.
Lifecycle / Cleanup:: Guarded indirectly, via the listing call it delegates to.

Raises:: RuntimeError -- If Aether has been cleaned.
Returns:: True when the conduit name exists in the target frame.
Return type:: bool

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

Return the registered root conduit id for one name, if present.

Parameters:

name -- Root conduit name to resolve.
aetheric_frame_name -- Name of the target frame.

Returns:

Matching conduit id, or None when missing.

Return type:

Optional[str]

Raises:

ValueError -- If the specified frame does not exist.

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

Return one registered root conduit by name.

Parameters:

name -- Root conduit name to resolve.
aetheric_frame_name -- Name of the target frame.

Returns:

Matching root conduit.

Return type:

Conduit

Raises:

ValueError -- If the frame does not exist or the conduit is missing.

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

Return one registered root conduit by id.

Parameters:

conduit_id -- Root conduit id to resolve.
aetheric_frame_name -- Name of the target frame.

Returns:

Matching root conduit.

Return type:

Conduit

Raises:

ValueError -- If the frame does not exist or the conduit is missing.

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