On this page

• AetherConfiguration
  • AetherConfiguration
    • AetherConfiguration.cleanup()
    • AetherConfiguration.id
    • AetherConfiguration.frozen
    • AetherConfiguration.activated
    • AetherConfiguration.channel_logger_activation_enabled
    • AetherConfiguration.channel_logger_resolver
    • AetherConfiguration.default_logger
    • AetherConfiguration.process_wide_unique_spell_ids
    • AetherConfiguration.get_configuration_dictionary()
    • AetherConfiguration.with_defaults()
    • AetherConfiguration.from_recorded_payload()
    • AetherConfiguration.with_channel_logger_activation_enabled()
    • AetherConfiguration.with_channel_logger_resolver()
    • AetherConfiguration.with_default_logger()
    • AetherConfiguration.with_process_wide_unique_spell_ids()
    • AetherConfiguration.set_channel_logger_activation_enabled()
    • AetherConfiguration.set_channel_logger_resolver()
    • AetherConfiguration.set_default_logger()
    • AetherConfiguration.set_process_wide_unique_spell_ids()
    • AetherConfiguration.validate()
    • AetherConfiguration.freeze()
    • AetherConfiguration.finalize()
    • AetherConfiguration.activate()
    • AetherConfiguration.emit_configured_twin_when_recording()

AetherConfiguration

Use md.AetherConfiguration from the public package namespace.

Implementation source

class AetherConfiguration

Mutable-to-frozen configuration surface for Aether root policy.

Purpose:

Hold process-wide Aether policy inputs before the root applies them to hosted subsystems. The current owned policy slice is logger activation control for AetherUtilitySystem.

Contract:

• mutable until frozen

• activation is explicit and implies successful validation/freeze

• automatic channel logger activation is disabled by default

• explicit logger attachment remains outside this config surface

Note

System caching policy is owned by AethericFrameConfiguration (frame-level toggle plus the cache root path), not by this root config.

Registration:

MELDER KERNEL - guarded. Obtained through Aether.create_configuration().

Subsystem Context:

The root policy surface, following the same mutable-then-frozen shape as the Spellbook, crystallizer, mutation-research, and Nexus configurations

• so an agent that has learned one configuration lane can drive all of

them.

System Context:

Its scope is deliberately NARROW: process-wide logger activation policy for AetherUtilitySystem, and the docstring's Note draws the boundary explicitly by pointing system caching policy at AethericFrameConfiguration instead. Root configuration answers only what must be true for the whole process. Automatic channel-logger activation being DISABLED BY DEFAULT is the conservative posture that matters: a library that silently activated logging on import would emit into a host application's logging configuration uninvited. Explicit attachment via attach_logger(...) stays outside this surface for the same reason - handing over a live logger object is an act, not a policy.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Root logger-activation policy for AetherUtilitySystem. Mutable until frozen; activation implies validation. Automatic channel logging is OFF by default. Obtain via Aether.create_configuration().

cleanup() → None

Idempotently clear configuration state.

Contract:

• IDEMPOTENT: a second call returns without re-running teardown.

• Releases only configuration-owned state. Loggers and resolvers handed in by the caller are BORROWED and are not cleaned here.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

None.

property id: str

Return the stable configuration id.

Contract:

• Identifies THIS CONFIGURATION OBJECT, not the Aether it configures.

• Assigned at construction and stable for the object's life; freezing and activating do not change it.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

Stable configuration id.

Return type:

str

property frozen: bool

Return whether the configuration is frozen.

Contract:

• True once freeze() has sealed the values. Frozen means SETTERS ARE REFUSED; it does NOT mean the configuration is in use - that is activated.

• Part of the three-stage configuration lifecycle: MUTABLE -> FROZEN -> ACTIVATED. Setters work only while mutable; freeze() seals values; activate() additionally marks the config live and records it.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when the mutation is closed.

Return type:

bool

property activated: bool

Return whether the configuration has been activated.

Contract:

• True only after activate(). Activation implies frozen, but frozen does NOT imply activated: finalize() freezes WITHOUT activating, so a configuration can be sealed and never made live.

• Part of the three-stage configuration lifecycle: MUTABLE -> FROZEN -> ACTIVATED. Setters work only while mutable; freeze() seals values; activate() additionally marks the config live and records it.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when validated, frozen, and marked ready for Aether.

Return type:

bool

property channel_logger_activation_enabled: bool

Return whether automatic channel logger activation is enabled.

Contract:

• DEFENSIVE READ: the stored value's type is re-checked on every read and a drifted value raises TypeError rather than being returned. That guards against direct tampering with the underlying property map.

• Reflects the sealed value once frozen, so a post-freeze read is stable.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when resolve_channel_logger(...) may auto-attach.

Return type:

bool

property channel_logger_resolver: Callable[[...], Any] | None

Return the configured channel logger resolver, if any.

Contract:

• None is a legitimate value meaning "no resolver attached", not an error. The read accepts None and rejects any non-callable.

• DEFENSIVE READ: the stored value's type is re-checked on every read and a drifted value raises TypeError rather than being returned. That guards against direct tampering with the underlying property map.

• Reflects the sealed value once frozen, so a post-freeze read is stable.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

Configured resolver.

Return type:

Optional[Callable[..., Any]]

property default_logger: Logger | None

Return the configured stdlib fallback logger, if any.

Contract:

• None is a legitimate value meaning "no default logger", not an error. Any non-logging.Logger value raises on read.

• DEFENSIVE READ: the stored value's type is re-checked on every read and a drifted value raises TypeError rather than being returned. That guards against direct tampering with the underlying property map.

• Reflects the sealed value once frozen, so a post-freeze read is stable.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

Configured default logger.

Return type:

Optional[logging.Logger]

property process_wide_unique_spell_ids: bool

Return whether spell_id uniqueness is enforced across the whole process.

Contract:

• DEFENSIVE READ: the stored value's type is re-checked on every read and a drifted value raises TypeError rather than being returned.

• Reflects the sealed value once frozen, so a post-freeze read is stable.

• True (the default) means one spell_id may exist ONCE per process: every AethericFrame registers into a single Aether-owned id set instead of its own. False restores per-frame scoping, where two frames may each hold the same id - the multi-tenant shape, where one class can be bound independently in several isolated worlds.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

• RuntimeError -- If the configuration has been cleaned.

• TypeError -- If the stored value is no longer a bool.

Returns:

True when spell_id uniqueness is process-wide.

Return type:

bool

get_configuration_dictionary() → dict[str, object]

Return a snapshot of the properties this configuration currently holds.

Purpose:

Let a host compare two configurations - for example a policy it was handed against the one installed on the root - without reading the private property bag.

Contract:

• Returns a NEW dict of every property currently set, name to value. Changing the returned dict never changes this configuration.

• Values are the stored objects BY REFERENCE (no deep copy, no serialization); all four logger/regime properties are always present.

• Never validates, freezes, activates or emits a recorded twin, and works in every lifecycle state until cleanup.

Threading:

Taken under the configuration lock, so the snapshot never sees a half-applied write.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

Property name to stored value.

Return type:

dict[str, object]

with_defaults() → AetherConfiguration

Apply the default Aether logger policy.

Contract:

• MUTATES THIS OBJECT and returns self; it is not a copying builder.

• Applies the default logger policy in place, overwriting anything set earlier, so call it FIRST and override afterwards.

• Refused once frozen.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This configuration instance.

Return type:

AetherConfiguration

classmethod from_recorded_payload(recorded_payload: dict[str, object]) → tuple[AetherConfiguration, dict[str, list[str]]]

Reload lane: rebuild one Aether configuration from its recorded twin payload.

Purpose:

The restore counterpart to the fluent authoring lane. A sealed AetherCrystal payload is the configuration truth; the reload lane applies it and seals in one motion (load it in, freeze it), reporting every deviation to the caller.

Contract:

• channel_logger_activation_enabled reloads from the record; when absent it falls to the documented default (False) and is reported under "missing".

• process_wide_unique_spell_ids (the spell-id regime, recorded since record major 4) reloads the same way; when absent (an older record) it keeps the default (True) and is reported under "missing".

• Callable-bearing entries can NEVER reload from a record: when the payload marks channel_logger_resolver_present or default_logger_present True, the key is reported under "code_participation" and the live value stays None - the booting code must re-supply its callables explicitly.

• LOADS AND FREEZES in one motion: the returned configuration is sealed. The freeze carries no emission; emission rides activate(), which the booting Aether performs.

Parameters:

recorded_payload -- AetherCrystal configuration_payload shaped mapping (JSON-safe, the cached-item shape).

Returns:

(the rebuilt FROZEN configuration,

{"missing": [keys defaulted-with-report],

"code_participation": [keys needing live callables]}).

Return type:

Tuple[AetherConfiguration, Dict[str, List[str]]]

Raises:

ValueError -- If the reloaded values fail validation at the internal freeze.

with_channel_logger_activation_enabled(enabled: bool) → AetherConfiguration

Set whether automatic channel logger resolution is enabled.

Parameters:

enabled -- True when resolve_channel_logger(...) may auto-attach a logger for callers that opt into that path.

Contract:

• FLUENT WRAPPER over the matching set_... method: it delegates and returns self, adding no validation of its own.

• MUTATES THIS OBJECT; it does not produce a variant.

• Refused once frozen.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This configuration instance.

Return type:

AetherConfiguration

with_channel_logger_resolver(resolver: Callable[[...], Any] | None) → AetherConfiguration

Set the channel logger resolver used by the utility system.

Parameters:

resolver -- Resolver callable or None.

Contract:

• FLUENT WRAPPER over the matching set_... method; delegates and returns self, adding no validation of its own.

• None is accepted and clears the resolver.

• Refused once frozen.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This configuration instance.

Return type:

AetherConfiguration

with_default_logger(logger: Logger | None) → AetherConfiguration

Set the stdlib fallback logger used by the utility system.

Parameters:

logger -- Fallback stdlib logger or None.

Contract:

• FLUENT WRAPPER over the matching set_... method; delegates and returns self, adding no validation of its own.

• None is accepted and clears the default logger.

• Refused once frozen.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This configuration instance.

Return type:

AetherConfiguration

with_process_wide_unique_spell_ids(enabled: bool) → AetherConfiguration

Set process-wide spell_id uniqueness and return this configuration.

Contract:

• MUTATES THIS OBJECT and returns self; it is not a copying builder.

• Refused once frozen.

• Turning this OFF restores per-frame id scoping, which permits the multi-tenant shape: the same class bound independently in several frames, each with its own instance. Leaving it ON means a second bind of the same object is refused anywhere in the process.

Parameters:

enabled -- True to enforce one spell_id per process; False for per-frame.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

• RuntimeError -- If the configuration is cleaned or frozen.

• TypeError -- If enabled is not a bool.

Returns:

This configuration instance.

Return type:

AetherConfiguration

set_channel_logger_activation_enabled(enabled: bool) → None

Set the automatic channel logger activation flag.

Parameters:

enabled -- Desired activation state.

Returns:

None.

Raises:

• RuntimeError -- If the configuration is frozen.

• TypeError -- If enabled is not a bool.

set_channel_logger_resolver(resolver: Callable[[...], Any] | None) → None

Set the channel logger resolver.

Parameters:

resolver -- Resolver callable or None.

Returns:

None.

Raises:

• RuntimeError -- If the configuration is frozen.

• TypeError -- If resolver is neither callable nor None.

set_default_logger(logger: Logger | None) → None

Set the stdlib fallback logger.

Parameters:

logger -- Fallback logger or None.

Returns:

None.

Raises:

• RuntimeError -- If the configuration is frozen.

• TypeError -- If logger is neither logging.Logger nor None.

set_process_wide_unique_spell_ids(enabled: bool) → None

Set the process-wide spell_id uniqueness flag.

Contract:

• Refused once frozen, so the regime cannot change under a live world. This matters more than for the logger flags: frames register their ids according to the regime in force when they are born, so flipping it mid-process would leave some ids in the unified Aether set and others in per-frame sets, with no single surface able to answer whether an id exists.

Parameters:

enabled -- True to enforce one spell_id per process; False for per-frame.

Returns:

None.

Raises:

• RuntimeError -- If the configuration is cleaned or frozen.

• TypeError -- If enabled is not a bool.

validate() → bool

Validate the logger policy values.

Contract:

• NEVER RETURNS False. Every failure raises ValueError; the bool return is a convention, not a verdict channel. Treat it as an assertion. (freeze()'s if not self.validate() branch is consequently unreachable.)

• Checks VALUE TYPES only - the activation flag must be a bool, the resolver must be callable or None, the default logger must be a logging.Logger or None.

• Does not mutate, and may be called before or after freeze.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when the configuration is valid.

Return type:

bool

freeze() → None

Validate and freeze the configuration.

Contract:

• IDEMPOTENT: a second call returns immediately without re-validating.

• VALIDATES BEFORE SEALING, so an invalid configuration raises and stays MUTABLE. Freeze is all-or-nothing.

• Seals values only; it does NOT activate. Use activate() for that.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

None.

finalize() → AetherConfiguration

Validate and freeze the configuration, then return it.

Contract:

• freeze() plus return self - nothing more. It seals the configuration WITHOUT activating it and WITHOUT recording anything.

• Use this when you want an immutable configuration to hand somewhere; use activate() when the configuration is going live now.

• Idempotent, inheriting freeze()'s early return.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This configuration instance.

Return type:

AetherConfiguration

activate() → AetherConfiguration

Validate, freeze, and mark the configuration active.

Contract:

• Freezes, marks the configuration ACTIVE, and then EMITS a configured-twin record when recording is on. That emission is a real side effect that finalize() does not have.

• NOT FULLY IDEMPOTENT. The freeze and the flag are, but the emission is NOT guarded by the activated flag, so calling activate() twice records TWICE. Call it once.

• Emission happens after the flag is set, so the configuration is already observably active while the record is written.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This activated configuration instance.

Return type:

AetherConfiguration

emit_configured_twin_when_recording() → None

Internal emission seam

Emit the Aether root twin for this configuration into the record.

Purpose:

Configuration activation is the emission factor, so activate() emits here. BUT the Aether root structurally precedes the crystallizer (it hosts it), so in the normal boot order this fires before recording is possible and captures nothing - Crystallizer.activate therefore calls this seam as a targeted root catch-up once recording is live. Same seam class as the nexus enable-time emission.

Contract:

• NO-OP before the crystallizer singleton boots or while it is not activated.

• Callable-bearing entries record as PRESENCE flags only (a record cannot carry live callables); the reload lane reports them as code_participation.

• Records the spell-id regime (process_wide_unique_spell_ids) so a restore can rebuild a per-frame world under per-frame ids.

• Replace-on-emit in the profile keeps exactly one root twin.

Returns:

None.

Topic reference · Full contents