On this page

Nexus
- Nexus

Nexus

Use md.Nexus from the public package namespace.

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

Purpose:: Provide the public singleton root for Rift-domain registry, configuration, ACL-container access, and Nexus-managed frame policy.

Contract:

Nexus is a process-wide singleton.

It owns Nexus configuration, configured/enabled state, live Rift registries, Rift profile templates, frame-descriptor management, and frame-local ACL manager access.

It holds the hidden Aether substrate reference required for Nexus-managed frame realization and disposal.

It creates Rift objects from policy-approved configuration and frame-name assignments.

It exposes NexusFrameManager as the sole Nexus-managed frame authoring and topology facade while leaving actual AethericFrame ownership to the hidden substrate.

Lifecycle:: Created eagerly by Aether at package/runtime boot, but starts unconfigured and disabled until a caller explicitly enables Rift-domain behavior.
Threading:: Uses one class-level singleton lock for instance creation and one instance threading.RLock for multi-step mutable state transitions.
Threading:: Registry mutation and ACL-change fan-out are serialized internally. The refresh barrier is config-backed through NexusConfiguration (projection_refresh_gate_enabled plus timeout and poll interval).
Registration:: MELDER KERNEL - guarded. Process-wide singleton created eagerly by Aether at boot; users engage it, they never construct it.
Subsystem Context:: The PUBLIC AR root - and the one to hold onto: Nexus is public, Aether is hidden substrate. It owns process-wide policy, the Rift registry, FrameDescriptorManager, NexusFrameManager, FrameACLManager, and RiftGateController.
System Context:: Nexus exists so the AR surface can be public WITHOUT exposing the substrate. It holds a hidden Aether reference for Nexus-managed frame realization and disposal, but Aether never appears in its public contract - which is what lets frame ownership stay with the substrate while authoring and topology policy live up here. It starts UNCONFIGURED AND DISABLED even though it is constructed eagerly at boot. That two-step engagement means merely importing melder never opens an AR surface; a user must configure and enable before any Rift can be created, so the AR layer is opt-in rather than ambient. Its most load-bearing runtime behaviour is the ACL fan-out: on a chain bump it computes the UNION of impacted Rifts by testing each Rift's assigned frame-contract set, then refreshes each impacted Rift once for its changed-frame SUBSET rather than wholesale. Single-frame callbacks delegate into that same batch primitive, so there is exactly one refresh path rather than two that could diverge.

AGENT_ACCESS: public

AGENT_PURPOSE:: access: public. The PUBLIC AR root over the hidden Aether substrate. Starts unconfigured and disabled - call configure(...) then enable() before create_rift_configuration()/create_rift(...). Owns frame descriptors, ACL, and managed-frame authoring.

cleanup() → None[source]

Idempotently cleanup Nexus-owned state and reset singleton status.

Purpose:: Tear down the Rift-domain root, its owned registries/managers, and the singleton bookkeeping used for later clean test reinitialization.

Contract:

Safe to call more than once.

Cleans registered Rifts, profile templates, installed configuration, ACL manager, and descriptor manager before dropping references.

Resets class-level singleton state after instance teardown completes.

Threading:: Acquires the instance lock for mutable-state teardown, then the class-level singleton lock to reset singleton bookkeeping.

Returns:: None.

property id: str

Purpose:: Return the stable Nexus identifier.

Contract:

Identifies the Nexus singleton instance; assigned once and stable for the process.

Distinct from any rift, frame or configuration id.

Returns:: Stable singleton id.
Return type:: str

property frame_manager: NexusFrameManager

Return the Nexus frame authoring facade.

Contract:

Exposes the frame manager BY REFERENCE for advanced callers.

Owned by Nexus: it must not be cleaned or replaced by the caller, and it becomes invalid once Nexus is cleaned.

Exposes the frame manager BY REFERENCE for advanced callers. It is owned by Nexus, so it must not be cleaned or replaced by the caller, and it becomes invalid once Nexus is cleaned.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Manager for authored Nexus-managed frames.
Return type:: NexusFrameManager

property configuration: NexusConfiguration

Purpose:: Return the installed Nexus configuration.

Contract:

DOUBLE-GUARDED: it requires Nexus to be configured AND re-checks for a None configuration, so it never hands back None.

Returns the installed configuration BY REFERENCE, not a copy.

Returns the live installed configuration object, not a detached copy.

Returns:: Installed process-wide config.
Return type:: NexusConfiguration
Raises:: RuntimeError -- If Nexus has not been configured yet.

property is_configured: bool

Purpose:: Return whether Nexus currently has an installed configuration.

Contract:

Reports that a configuration has been INSTALLED, which is weaker than being usable - is_activated is the operational switch.

Stays True across disable(), which deliberately keeps the install.

Returns:: True when configured.
Return type:: bool

property activated: bool

Return whether the Nexus root is live.

Contract:

The OPERATIONAL switch, distinct from configured. Nexus can be configured and inactive at the same time; that is the normal settled-but-off state, not an inconsistency.

Short form of is_activated; both report the same flag, matching Crystallizer and MutationResearch which each carry both spellings.

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

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: True when Rift-domain operations are permitted.
Return type:: bool

property configured: bool

Return whether a configuration is installed on the Nexus root.

Contract:

Short form of is_configured; both report the same flag.

Existence of policy, NOT liveness. See activated.

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

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: True when a configuration is installed.
Return type:: bool

property is_activated: bool

Purpose:: Return whether Nexus is currently enabled for Rift operations.

Contract:

The OPERATIONAL switch, distinct from is_configured. Nexus can be configured and disabled at the same time; that is the normal disabled state, not an inconsistency.

Returns:: True when enabled.
Return type:: bool

property rift_gate_controller: RiftGateController

Return the Nexus-owned Rift gate controller.

Contract:

Exposes the rift-gate controller BY REFERENCE; the convenience gate methods on Nexus all route through it.

Owned by Nexus - reach for it directly only for operations Nexus does not wrap.

Exposes the rift-gate controller BY REFERENCE. It is owned by Nexus; the convenience gate methods on Nexus all route through this object, so reaching for it directly is only needed for operations Nexus does not wrap.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Controller for registered Rift gates.
Return type:: RiftGateController

create_configuration() → NexusConfiguration[source]

Create a fresh Nexus configuration object.

Purpose:: The name the other three roots use. create_configuration remains as an alias, but create_configuration is what makes this root readable next to Crystallizer and MutationResearch.

Contract:

FACTORY ONLY: returns a FRESH, unattached NexusConfiguration and does NOT install it.

RETURNS IT WITH DEFAULTS ALREADY LOADED, which is what create_system_configuration did and what every caller of that verb depends on. NexusConfiguration is a property bag whose validate() demands EVERY declared key be present, so a bare instance cannot freeze - handing one back would turn a rename into a behaviour change and break every call site at finalize/activate time.

Override after the call; with_defaults() is idempotent, so chaining it again is harmless.

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

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: New mutable configuration object.
Return type:: NexusConfiguration

create_configuration_builder() → NexusConfigurationBuilder[source]

Create a fresh fluent builder for Nexus configuration assembly.

Contract:

FACTORY ONLY. Returns a fresh builder wrapping a new configuration and does NOT install anything here.

The builder's exits are one-shot and they are different rungs: build() yields a MUTABLE configuration, finalize() a frozen one, activate() an activated one. Installing whichever you get is still a separate configure() / activate() call on this root - a built configuration is not a live Nexus.

Threading:: Unsynchronized read of a plain flag; a snapshot only.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The builder is the caller's to own.

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: New builder instance.
Return type:: NexusConfigurationBuilder

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

Install one configuration on the Nexus root.

Contract:

INSTALLS ONLY - it does not validate, freeze or activate, and it accepts a configuration that is still mutable. This is the separation enable() never offered: install now, settle later.

Type-checked: a non-NexusConfiguration raises TypeError.

Replaces any previously installed configuration - but REFUSES while Nexus is active (0.2.8210): a live Nexus reads its policy at every Rift validation, so a swap would change the rules under existing Rifts. Deactivate first; the installed policy is kept until then. Crystallizer and MutationResearch refuse the same way.

Parameters:: configuration -- Configuration object to install.

Threading:: Applied under the Nexus lock; the active check and the install are one critical section.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Returns:

None.

Raises:

RuntimeError -- If Nexus has been cleaned, or is active.
TypeError -- If configuration is not a NexusConfiguration.

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

Install configuration if needed and bring the Nexus root live.

Purpose:: Transition Nexus into its enabled state for Rift-domain operations.

Contract:

Optionally replaces the installed configuration before enabling - but not while Nexus is already active (0.2.8210): passing a different configuration then raises, exactly as configure() does. Passing the installed configuration, or none, re-enables as before.

Finalizes the installed configuration before setting enabled.

Does not create a default configuration automatically when none is installed.

Parameters:: configuration -- Optional replacement configuration.
Returns:: None.
Raises:: RuntimeError -- If Nexus has no installed configuration, or it is active and a different configuration is supplied.

deactivate() → None[source]

Disable Rift operations without discarding configuration or registry state.

Purpose:: Turn off Rift-domain operation entrypoints while preserving the installed configuration and current registries.

Contract:

KEEPS THE INSTALLED CONFIGURATION: it flips the operational switch only, so is_configured stays True and the recorded twin is not evicted.

That makes disable REVERSIBLE without re-supplying configuration, which is the point of separating the two flags.

Returns:: None.

create_rift_configuration(profile_name: str | None = None) → RiftConfiguration[source]

Create a per-Rift configuration initialized from Nexus defaults.

Purpose:: Produce a mutable RiftConfiguration for a future Rift creation flow.

Contract:

Requires Nexus to be configured.

When profile_name is supplied, clones the stored profile template instead of returning it directly.

When profile_name is omitted, seeds a fresh configuration from installed Nexus defaults.

Produces a bare Rift configuration: room identity/mode and validation posture only. It does not select a target frame.

Parameters:

profile_name -- Optional registered profile name. When supplied, the returned configuration is cloned from the stored profile template.

Returns:

Mutable per-Rift configuration.

Return type:

RiftConfiguration

Raises:

RuntimeError -- If Nexus is not configured.
ValueError -- If profile_name is unknown.

register_rift_profile(name: str, configuration: RiftConfiguration) → None[source]

Internal

Register one named Rift configuration profile template on Nexus.

Parameters:

name -- Stable profile name.
configuration -- Rift configuration to store as the profile template source.

Contract:

Stores a frozen cloned template, not the original configuration object.

Replaces any existing template with the same name.

Returns:: None.
Raises:: ValueError -- If name is empty.

Internal

Create and register one live Rift object.

Contract:

Enforces the current Rift-creation gate before any object creation begins.

Finalizes the per-Rift configuration when needed and marks it consumed after successful registration.

Allocates default Rift and Nexus-frame names when callers do not supply them.

Creates the primary concrete space from the configured space_type.

Does not select or validate a target frame during bare Rift creation.

Registers the created Rift through add_rift(...) before returning it.

Parameters:

configuration -- Optional per-Rift configuration override.
rift_name -- Optional stable Rift name.
rift_id -- Optional explicit Rift id.
space_id -- Optional explicit primary-space id to seed on the Rift.
metadata -- Optional Rift-level metadata.
creation_token -- Optional creation token when creation is token-gated.
logger -- Optional explicit logger override passed through to the created Rift.

Returns:

Newly created and registered live Rift.

Return type:

Rift

add_rift(rift: Rift) → None[source]

Internal

Register one already-constructed Rift into Nexus.

Contract:

Rejects id/name collisions.

Validates target-frame, Nexus-frame, and active-Rift budgets before mutating registries.

Updates the id/name registries, target-frame ref counts, and Nexus-frame attachments as one Nexus-owned registration flow.

Parameters:: rift -- Live Rift object.
Returns:: None.
Raises:: ValueError -- If ids/names collide or frame budgets are exceeded.

get_rift(rift_id: str, access_token: str | None = None) → Rift[source]

Internal

Return a registered Rift by id.

Parameters:

rift_id -- Canonical Rift id.
access_token -- Optional direct-access token.

Contract:

Applies the current direct-Rift access gate before lookup.

Returns the live registered Rift object, not a detached copy.

Returns:: Registered Rift object.
Return type:: Rift

get_rift_by_name(rift_name: str, access_token: str | None = None) → Rift[source]

Internal

Resolve one registered Rift through the name -> id index.

Parameters:

rift_name -- Stable Rift name.
access_token -- Optional direct-access token.

Contract:

Applies the current direct-Rift access gate before lookup.

Resolves through the name-to-id index and then returns the same live object exposed by get_rift(...).

Returns:: Registered Rift object.
Return type:: Rift

has_rift(rift_id: str) → bool[source]

Internal

Return whether a Rift id is currently registered.

Parameters:: rift_id -- Canonical Rift id.

Contract:

Requires only that Nexus is CONFIGURED, not enabled - so you can probe rift registration while Nexus is disabled.

Note the asymmetry with list_rift_ids, which requires Nexus to be ENABLED. The two have deliberately different gates.

Performs a registry existence check only; it does not apply the direct-access gate or materialize any Rift object.

Returns:: True when registered.
Return type:: bool

remove_rift(rift_id: str) → None[source]

Internal

Remove one Rift from Nexus and update frame lifecycle state.

Contract:

Removes the Rift from Nexus registries under the Nexus lock.

Decrements target-frame ref counts and detaches the Rift from its Nexus-managed frames as part of registry teardown.

Disposes orphaned Nexus-managed frames only after the locked registry mutation phase completes.

Cleans the removed Rift before returning.

Parameters:: rift_id -- Canonical Rift id.
Returns:: None.

list_rift_ids() → list[str][source]

Return the currently registered Rift ids.

Purpose:: Expose the current live Rift registry contents at the id level.

Contract:

REQUIRES NEXUS TO BE ENABLED, a stricter gate than has_rift, which only requires configured. Enumerating the rift set is treated as an operational action rather than a probe.

Returns a point-in-time list; it goes stale as rifts are created or removed.

Requires Nexus to be enabled before callers may inspect the live Rift registry.

Returns:: Snapshot of registered ids.
Return type:: list[str]

get_rift_gate(rift_id: str) → RiftGate | None[source]

Return the registered Rift gate for one Rift id, if present.

Parameters:: rift_id -- Canonical Rift id.

Contract:

Returns None for an unknown rift id rather than raising, so None means "no gate registered" and is not an error channel.

The returned gate is the LIVE object, so opening or closing it directly has the same effect as the Nexus convenience methods.

Returns None for an unknown rift id rather than raising, so None means "no gate registered" and is not an error channel.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Registered Rift gate when present.
Return type:: Optional[RiftGate]

enable_rift_gate(rift_id: str) → None[source]

Open one Rift gate by Rift id.

Parameters:: rift_id -- Canonical Rift id.

Contract:

SILENTLY NO-OPS FOR AN UNKNOWN RIFT ID. A missing gate returns without raising, so a typo'd id looks like success. Confirm with get_rift_gate(...) when the id is not known-good.

Opening an already-open gate is harmless.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: None.

disable_rift_gate(rift_id: str) → None[source]

Close one Rift gate by Rift id.

Parameters:: rift_id -- Canonical Rift id.

Contract:

SILENTLY NO-OPS FOR AN UNKNOWN RIFT ID, exactly like the enable side - a missing gate returns without raising.

Closing the gate stops NEW entry; it does NOT wait for threads already inside. Use close_and_wait_rift(...) when you need quiescence.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: None.

close_and_wait_rift(rift_id: str, timeout: float = 30.0, interval: float = 0.1) → None[source]

Terminally close and drain one Rift gate.

Parameters:

rift_id -- Canonical Rift id.
timeout -- Maximum seconds to wait for ticket drain.
interval -- Poll interval in seconds while draining.

Contract:

BLOCKS. It closes the gate and then waits until no threads remain inside the rift, polling at the given interval up to the timeout - this is the quiescence primitive that plain disable_rift_gate is not.

The timeout bounds the wait, so a return does not by itself prove the rift is empty; check the active-thread count if that matters.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: None.

count_active_rift_threads(rift_id: str) → int[source]

Return active ticket count for one Rift gate.

Parameters:: rift_id -- Canonical Rift id.

Contract:

A point-in-time count for ONE rift; it can change the instant it returns.

A DIAGNOSTIC, not a synchronization primitive - do not spin on it to decide a rift is quiescent; use close_and_wait_rift for that.

A point-in-time count for ONE rift; it can change the instant it returns, so it is a diagnostic rather than a synchronization primitive.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Active ticket count.
Return type:: int

count_active_rift_threads_total() → int[source]

Return active ticket count summed across all Rift gates.

Contract:

A point-in-time count ACROSS ALL rifts.

The per-rift counts are NOT sampled atomically together, so this total need not equal the sum of individually queried rifts.

A point-in-time count ACROSS ALL rifts. Because the per-rift counts are not sampled atomically together, this total need not equal the sum of individually queried rifts taken at slightly different moments.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Total active ticket count.
Return type:: int

enable_all_rift_gates() → None[source]

Open every registered Rift gate.

Contract:

Opens EVERY registered gate, including ones deliberately closed earlier.

It does NOT remember or restore prior per-gate state, so this is destructive to a hand-tuned gate configuration.

Opens EVERY registered gate, including ones deliberately closed earlier - it does not remember or restore prior per-gate state.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: None.

disable_all_rift_gates() → None[source]

Close every registered Rift gate.

Contract:

Closes EVERY registered gate.

Like the single-rift close, it stops NEW entry without waiting for threads already inside.

Closes EVERY registered gate. Like the single-rift close, it stops new entry without waiting for threads already inside.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: None.

set_rift_gate_entry_mode(rift_id: str, entry_mode: str) → None[source]

Set the admission mode for one registered Rift gate.

Parameters:

rift_id -- Canonical Rift id.
entry_mode -- Admission mode to apply.

Contract:

Sets the admission policy for ONE rift's gate.

Entry mode governs HOW callers are admitted and is independent of whether the gate is open or closed.

Sets the entry policy for ONE rift's gate. Entry mode governs HOW callers are admitted; it is independent of whether the gate is open or closed.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: None.

set_all_rift_gate_entry_mode(entry_mode: str) → None[source]

Set the admission mode for every registered Rift gate.

Parameters:: entry_mode -- Admission mode to apply.

Contract:

Applies one entry mode to EVERY registered gate.

It overwrites per-gate choices without preserving them.

Applies one entry mode to EVERY registered gate, overwriting per-gate choices without preserving them.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: None.

get_frame_acl_version() → str[source]

Return the current placeholder ACL manager version string.

Contract:

A MONOTONIC CHANGE MARKER for the ACL manager: compare it across time to detect that policy changed without diffing configurations.

It describes the manager as a whole, not any single frame.

Returns the version reported by the live Nexus-owned FrameACLManager.

Returns:: Current ACL manager version.
Return type:: str

register_frame_acl_profile(frame_acl_profile: FrameACLProfile) → None[source]

Register or replace one named ACL profile on the Nexus-owned manager.

Parameters:: frame_acl_profile -- Profile object to store by its own name.

Contract:

Registers a REUSABLE profile that frames can then adopt by name; it does not apply the profile to any frame by itself.

Registration is by the profile's own name, so re-registering the same name replaces rather than duplicates.

Delegates registration to the Nexus-owned ACL manager and replaces any existing distinct profile with the same name.

Returns:: None.

get_frame_acl_profile(profile_name: str) → FrameACLProfile[source]

Return one registered ACL profile by name.

Parameters:: profile_name -- Profile name to resolve.

Contract:

REQUIRED lookup: an unknown profile name RAISES rather than returning None.

Returns the registered profile by reference.

Resolves through the Nexus-owned ACL manager without synthesizing a missing profile.

Returns:: Existing stored profile.
Return type:: FrameACLProfile
Raises:: KeyError -- If the profile is not registered.

list_frame_acl_profile_names() → List[str][source]

Return the current ACL profile names in insertion order.

Contract:

Lists REGISTERED profile names, which is not the same as profiles currently in use by a frame.

A name absent here cannot be adopted.

Returns a snapshot list from the Nexus-owned ACL manager's composed profile registry.

Returns:: Current profile names.
Return type:: List[str]

remove_frame_acl_profile(profile_name: str) → bool[source]

Remove and cleanup one registered ACL profile by name.

Parameters:: profile_name -- Profile name to remove.

Contract:

Removes the profile from the registry. Frames that already adopted it are not retroactively stripped by this call.

Returns the removal outcome rather than raising on an unknown name.

Delegates removal to the Nexus-owned ACL manager and returns False when the profile name is not currently registered.

Returns:: True when the profile existed and was removed.
Return type:: bool

get_frame_acl_builder(frame_name: str) → FrameACLBuilder[source]

Return the unique frame ACL builder object for one frame.

Purpose:: Provide the root-level entrypoint for frame-scoped ACL authoring.

Contract:

Ensures the matching frame ACL container exists before builder lookup.

Returns the same builder object for repeated calls against the same frame.

Parameters:: frame_name -- Stable frame name whose ACL builder should be returned.
Returns:: The one builder object owned by the frame's ACL container.
Return type:: FrameACLBuilder

get_current_frame_acl_configuration(frame_name: str, *, view_contract_name: str = 'default', command_contract_name: str = 'default', codegen_contract_name: str = 'default') → FrameACLConfiguration[source]

Return the current selected frame ACL configuration for one frame.

Purpose:: Expose the currently selected ACL configuration for a frame through the Nexus facade.

Contract:

NOT A PURE READ: it ENSURES the frame's ACL container exists, so calling it for a frame with none CREATES the container as a side effect.

Returns the CURRENT effective configuration, which is the composition of whatever contracts are selected - not a stored named configuration.

Parameters:

frame_name -- Stable frame name whose current ACL configuration is requested.
view_contract_name -- Selected view ACL contract name.
command_contract_name -- Selected command ACL contract name.
codegen_contract_name -- Selected codegen ACL contract name.

Returns:

The currently selected ACL configuration for the frame.

Return type:

FrameACLConfiguration

get_current_view_frame_acl_configuration(frame_name: str, *, contract_name: str = 'default') → FrameACLViewConfiguration[source]

Return the current selected view ACL configuration for one frame/contract.

Contract:

NOT A PURE READ: it ENSURES the frame's ACL container exists first, so calling it for a frame that has none CREATES the container as a side effect rather than returning None.

Returns the VIEW surface configuration specifically; the command and codegen surfaces are separate configurations with their own getters.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Current view configuration.
Return type:: FrameACLViewConfiguration
Parameters:: frame_name -- Frame whose currently selected VIEW ACL revision should be read.

get_current_command_frame_acl_configuration(frame_name: str, *, contract_name: str = 'default') → FrameACLCommandConfiguration[source]

Return the current selected command ACL configuration for one frame/contract.

Contract:

NOT A PURE READ: it ENSURES the frame's ACL container exists first, so calling it creates the container when absent.

Returns the COMMAND surface configuration only - distinct from the view and codegen surfaces.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Current command configuration.
Return type:: FrameACLCommandConfiguration
Parameters:: frame_name -- Frame whose currently selected COMMAND ACL revision should be read.

get_current_codegen_frame_acl_configuration(frame_name: str, *, contract_name: str = 'default') → FrameACLCodegenConfiguration[source]

Return the current selected codegen ACL configuration for one frame/contract.

Contract:

NOT A PURE READ: it ENSURES the frame's ACL container exists first, so calling it creates the container when absent.

Returns the CODEGEN surface configuration only - distinct from the view and command surfaces.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Current codegen configuration.
Return type:: FrameACLCodegenConfiguration
Parameters:: frame_name -- Frame whose currently selected CODEGEN ACL revision should be read.

get_named_frame_acl_configuration(frame_name: str, contract_name: str = 'default') → FrameACLConfiguration[source]

Return one named frame ACL configuration for a frame.

Purpose:: Expose the per-frame named ACL contract registry through the Nexus facade.

Contract:

NOT A PURE READ: it ENSURES the frame's ACL container exists first.

Fetches a STORED, NAMED configuration rather than the current effective one, so it is unaffected by which contracts are presently selected.

Parameters:

frame_name -- Stable frame name whose named ACL contract is requested.
contract_name -- Frame-local contract name to resolve.

Returns:

Named ACL configuration for the frame.

Return type:

FrameACLConfiguration

list_named_frame_acl_configuration_names(frame_name: str) → List[str][source]

Return all named ACL contract names for a frame.

Purpose:: Expose the frame-local named ACL registry keys through the Nexus facade.

Contract:

NOT A PURE READ: it ENSURES the frame's ACL container exists first, so listing a frame that had none leaves a container behind.

Lists STORED configuration names for one frame, not profiles.

Parameters:: frame_name -- Stable frame name whose contract names are requested.
Returns:: Registered ACL contract names for the frame.
Return type:: List[str]

register_named_frame_acl_configuration(frame_name: str, configuration: FrameACLConfiguration, *, contract_name: str = 'default') → FrameACLConfiguration[source]

Register one named ACL configuration for a frame.

Purpose:: Add a new frame-local named ACL contract through the Nexus facade.

Contract:

Type-checked: a non-FrameACLConfiguration raises TypeError rather than being coerced.

STORES the configuration under a name for later selection; it does not make it current.

Parameters:

frame_name -- Stable frame name that owns the contract registry.
configuration -- Locked ACL configuration node to register.
contract_name -- Frame-local contract name.

Returns:

Registered named configuration node.

Return type:

FrameACLConfiguration

create_frame_projection_sets(frame_names: Sequence[str], *, contract_names_by_frame_name: Mapping[str, str | Mapping[str, str]] | None = None) → Dict[str, FrameProjectionSet][source]

Build projection sets for the requested frame names.

Parameters:

frame_names -- Frame names to project.
contract_names_by_frame_name -- Optional per-frame selected ACL contract names.

Contract:

EXPLICITLY REJECTS A BARE STRING for frame_names, even though a string is a valid Sequence. Passing one raises TypeError rather than silently iterating its characters as frame names.

Every entry must be a non-empty string; a bad element raises ValueError before any projection is built, so the call is all-or-nothing.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Fresh projection sets keyed by frame name.
Return type:: Dict[str, IFrameProjectionSet]

insert_head_frame_acl_configuration(frame_name: str, configuration: FrameACLConfiguration, *, select_as_current: bool = True) → FrameACLConfiguration[source]

Install one replacement revision into the selected same-name ACL contract.

Purpose:: Expose the public Nexus seam for replacing the current selected same-name ACL bundle revision under an existing named contract.

Contract:

Installs the supplied locked ACL bundle into the selected named contract set for the frame.

Preserves the current same-name contract model by advancing the selected bundle revision instead of creating a new contract name.

select_as_current is retained for compatibility with existing callers, but current/head separation is already implicit in the install path and does not require separate branch logic here.

Parameters:

frame_name -- Stable frame name that owns the ACL registry.
configuration -- Locked ACL configuration node to install.
select_as_current -- Compatibility-only flag preserved for existing callers.

Returns:

Installed assembled configuration snapshot.

Return type:

FrameACLConfiguration

create_frame_projection_sets_for_rift(rift_id: str, *, frame_names: Sequence[str] | None = None) → Dict[str, FrameProjectionSet][source]

Build projection sets from one Rift's current frame contracts.

Parameters:

rift_id -- Existing Rift id whose frame contracts should be projected.
frame_names -- Optional explicit multi-frame scope for one or more engaged frames.

Contract:

DEFAULTS TO THE RIFT'S ASSIGNED FRAMES when frame_names is None, which is the normal path - you rarely need to enumerate them yourself.

Supplying frame_names NARROWS within the rift's assignment; it cannot widen it, so naming an unassigned frame is rejected rather than granted.

Empty rift_id is rejected up front.

Threading:: Delegated to the rift-gate controller, which owns the gate locking.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If Nexus has been cleaned.
Returns:: Projection sets keyed by frame name.
Return type:: Dict[str, IFrameProjectionSet]

get_nexus_frame_for_rift(rift_id: str, frame_name: str | None = None) → Conduit[source]

Internal

Return a rooted Nexus-managed conduit for one Rift under the current topology rules.

Contract:

Returns the frame's ROOT CONDUIT, as the -> Conduit signature states. The frame object is deliberately NOT handed to rift-facing callers; the root conduit is the intended handle, and the frame is resolved only to find it.

That is the same boundary the viewer family keeps: rift-facing access hands back the thing you may act through, not the container it lives in.

The root conduit is REQUIRED - a managed frame without one raises rather than returning None.

Parameters:

rift_id -- Requesting Rift id.
frame_name -- Optional explicit Nexus frame name. When omitted, Nexus derives the requested frame from the current topology mode.

Returns:

Root conduit for the resolved Nexus-managed frame.

Return type:

Conduit

Raises:

ValueError -- If the requesting Rift or requested frame is not available under the current mode rules.

create_nexus_frame_for_rift(rift_id: str, frame_name: str | None = None, root_conduit_name: str = 'root', immutable: bool = False) → Conduit[source]

Internal

Create one rooted Nexus-managed conduit for one Rift under the current topology rules.

Contract:

Returns the ROOT CONDUIT of the newly created frame, as the -> Conduit signature states, matching the getter: the frame object is deliberately not exposed to rift-facing callers.

root_conduit_name names that conduit and defaults to "root".

immutable fixes the new frame's posture at creation, so it cannot be reconfigured afterwards - choose it deliberately.

Parameters:

rift_id -- Requesting Rift id.
frame_name -- Optional explicit Nexus frame name.
root_conduit_name -- Root conduit name to use for newly created frames.
immutable -- True when the new frame should survive zero attachments until an explicit external cleanup path removes it.

Returns:

Root conduit for the newly created frame.

Return type:

Conduit

Raises:

ValueError -- If creation is not valid under the current topology rules or the target frame already exists.

authorize_frame_link_for_rift(rift_id: str, frame_name: str) → bool[source]

Internal

Authorize one Rift frame-link request against Nexus-managed frame policy.

Purpose:: Keep Nexus as the owner of Nexus-managed frame topology rules when a live Rift tries to attach to a frame by name through its frame-link API.

Parameters:

rift_id -- Requesting Rift id.
frame_name -- Target frame name being attached through the Rift frame-link path.

Contract:

Returns False when the target frame is not Nexus-managed.

Returns True when the frame is Nexus-managed and accessible to the requesting Rift.

Raises ValueError when the frame is Nexus-managed but not accessible under the current topology mode.

Returns:: True when the target frame is Nexus-managed and authorized.
Return type:: bool

list_accessible_nexus_frame_names(rift_id: str) → Tuple[str, ...][source]

Internal

Return the Nexus frame names the requesting Rift may currently access.

Parameters:: rift_id -- Requesting Rift id.

Contract:

Requires Nexus to be enabled.

Applies the current Nexus-frame topology mode when determining visibility.

Returns a snapshot tuple of currently accessible frame names.

Returns:: Accessible Nexus frame names.
Return type:: Tuple[str, ...]

list_accessible_non_nexus_frame_names(rift_id: str) → Tuple[str, ...][source]

Internal

Return the published non-Nexus frame names the requesting Rift may currently target.

Parameters:: rift_id -- Requesting Rift id.

Contract:

Requires Nexus to be enabled.

Starts from published descriptor truth only.

Excludes every manager-owned Nexus frame name.

Applies generic target-frame name policy and the requesting Rift's current room runtime requirements before returning names.

Returns:: Accessible published non-Nexus frame names.
Return type:: Tuple[str, ...]

check_for_aetheric_frame(frame_name: str) → None[source]

Internal

Drop Nexus-managed frame state when Aether is about to dispose a frame directly.

Parameters:: frame_name -- Frame name about to be removed from Aether.

Contract:

Short-circuits when Nexus is cleaned or missing the descriptor manager.

Drops manager-owned authored state when the frame is a Nexus-managed frame.

Falls back to descriptor/ACL cleanup for non-managed frames that still have passive Nexus-side state.

Logs and returns quietly when no managed or descriptor-owned state is present.

Returns:: None.

Topic reference · Full contents