On this page

• NexusConfiguration
  • NexusConfiguration
    • NexusConfiguration.id
    • NexusConfiguration.frozen
    • NexusConfiguration.cleanup()
    • NexusConfiguration.set_property()
    • NexusConfiguration.get_property()
    • NexusConfiguration.has_property()
    • NexusConfiguration.load_default_dictionary()
    • NexusConfiguration.load_recorded_dictionary()
    • NexusConfiguration.validate()
    • NexusConfiguration.freeze()
    • NexusConfiguration.emit_configured_twin_when_recording()
    • NexusConfiguration.finalize()
    • NexusConfiguration.activated
    • NexusConfiguration.activate()
    • NexusConfiguration.build()
    • NexusConfiguration.with_defaults()
    • NexusConfiguration.with_rift_creation_enabled()
    • NexusConfiguration.with_creation_token_required()
    • NexusConfiguration.with_creation_token()
    • NexusConfiguration.with_direct_rift_access()
    • NexusConfiguration.with_rift_access_token_required()
    • NexusConfiguration.with_rift_access_token()
    • NexusConfiguration.with_allow_external_rift_registration()
    • NexusConfiguration.with_allow_nested_rift_creation()
    • NexusConfiguration.with_max_active_rift_count()
    • NexusConfiguration.with_nexus_frame_mode()
    • NexusConfiguration.with_default_nexus_frame_name()
    • NexusConfiguration.with_auto_create_nexus_frames()
    • NexusConfiguration.with_max_nexus_frame_count()
    • NexusConfiguration.with_allowed_target_frame_names()
    • NexusConfiguration.with_denied_target_frame_names()
    • NexusConfiguration.with_target_frame_override()
    • NexusConfiguration.with_multiple_target_frames()
    • NexusConfiguration.with_max_target_frame_count()
    • NexusConfiguration.with_projection_refresh_gate()
    • NexusConfiguration.with_projection_refresh_gate_timeout_seconds()
    • NexusConfiguration.with_projection_refresh_gate_poll_interval_seconds()
    • NexusConfiguration.with_default_space_type()
    • NexusConfiguration.with_default_auto_activate_on_program()
    • NexusConfiguration.with_default_auto_create_space()
    • NexusConfiguration.with_default_validation_mode()

NexusConfiguration

Use md.NexusConfiguration from the public package namespace.

Implementation source

class NexusConfiguration

Internal

Process-wide configuration for Nexus.

Purpose:

Hold central Nexus governance and default-programming behavior without pushing per-Rift room/history semantics up into the process-wide layer.

Contract:

• Mutable until frozen.

• Stores typed properties in one property bag.

• Governs process-wide creation/access policy, Nexus-frame topology, target-frame restrictions, and per-Rift defaults.

• Once finalized, property mutation is disallowed.

Lifecycle:

Owned by Nexus once a user explicitly engages it and installs a configuration. Cleanup clears all stored properties and freezes the object permanently.

Threading:

Mutable until frozen; after finalization the property bag is read-only, so concurrent reads need no coordination.

Registration:

MELDER KERNEL - guarded. Installed into Nexus by the user through Nexus.configure(...).

Subsystem Context:

The process-wide policy object for the AR layer, deliberately distinct from per-Rift configuration snapshots and from NexusFrameConfiguration (authored per managed frame).

System Context:

The mutable-then-frozen shape is the same lifecycle Melder uses for SpellbookConfiguration, AetherConfiguration, and the crystallizer and mutation-research configurations. That consistency is deliberate: an agent that has learned one configuration lane can drive all of them. What belongs here versus on a Rift is the real boundary this class draws. Process-wide governance - creation and access gates, frame topology mode, target-frame restrictions, Rift budgets, and the projection refresh barrier - lives here because it must be answered identically for every Rift. Per-Rift room and history semantics stay down on the Rift, because they legitimately differ between Rifts and pushing them up would force one Rift's choice onto all of them.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Process-wide AR policy: creation/access gates, frame topology mode, target-frame restrictions, Rift budgets, and the projection refresh barrier. Mutable until frozen. Per-Rift settings belong on RiftConfiguration.

property id: str

Purpose:

Return the stable identity for this configuration object.

Returns:

Stable configuration identifier.

Return type:

str

property frozen: bool

Purpose:

Return whether further mutation is forbidden.

Returns:

True when the configuration is finalized.

Return type:

bool

cleanup() → None

Internal

Idempotently cleanup the configuration and clear all state.

Contract:

• Marks the object cleaned and frozen.

• Clears the property bag and available-property registry.

• Leaves the object permanently unusable after cleanup.

Returns:

None.

set_property(key: str, value: object) → None

Internal

Set one configuration property before finalize().

Parameters:

• key -- Property name.

• value -- Property value.

Contract:

• Rejects mutation after freeze().

• Normalizes enum-backed and frame-list-backed values before storage.

• Enforces the declared type contract for every property.

Returns:

None.

Raises:

• RuntimeError -- If the configuration is already frozen.

• ValueError -- If the property name is unknown.

• TypeError -- If the supplied value does not satisfy the declared type.

get_property(key: str) → object

Internal

Return one configuration property value.

Parameters:

key -- Property name.

Contract:

• Returns the currently stored property value exactly as normalized during set_property(...).

Returns:

Stored property value.

Return type:

object

Raises:

KeyError -- If the property has not been set.

has_property(key: str) → bool

Internal

Return whether a property has been set.

Parameters:

key -- Property name.

Contract:

• Returns presence only; does not validate semantic completeness.

Returns:

True when present.

Return type:

bool

load_default_dictionary() → None

Internal

Load the standard default property set for Nexus master-user engagement.

Contract:

• Populates every required Nexus-governance field.

• Uses the easy-start defaults agreed for master-user Nexus setup: single Nexus-frame mode, default target frame, and no token requirements.

Returns:

None.

load_recorded_dictionary(recorded_properties: Dict[str, Any]) → Dict[str, List[str]]

Reload lane: apply one RECORDED property payload as configuration truth and seal.

Purpose:

The restore/reload counterpart to load_default_dictionary. A sealed world rebuilds from its recorded values - never from present-day defaults - and the reload lane loads and freezes in one motion.

Contract:

• Defaults land first as the backfill floor, then every recorded key OVERWRITES its default (recorded truth wins); keys the record did not carry are returned under "backfilled" so nothing defaults silently.

• Recorded values re-typed by the emission scalar filter convert back on the way in: registry-typed enums accept their recorded member NAME; registry-typed tuples accept recorded lists (re-tupled element-wise).

• A recorded value the property system still refuses is skipped and returned under "rejected" as "key: reason"; nothing is silently coerced (the per-key exception capture is documented best-effort collection for the caller's shortfall reporting).

• SEALS WITHOUT EMISSION: enable has not happened yet, so the twin emission belongs to Nexus.enable, which calls emit_configured_twin_when_recording for pre-frozen configurations.

Parameters:

recorded_properties -- Property name -> recorded value mapping (one sealed, JSON-safe NexusCrystal configuration_payload).

Returns:

{"rejected": ["key: reason", ...],

"backfilled": [key, ...]}.

Return type:

Dict[str, List[str]]

Raises:

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

• ValueError -- If the reloaded property set fails validation at the internal seal.

validate() → bool

Internal

Validate that all required properties exist and the governance schema is self-consistent.

Contract:

• Ensures every declared property has a value.

• Enforces cross-field invariants such as single-frame mode budget, Nexus-frame mode budget, target-frame allow/deny coherence, and target-frame caps.

Returns:

True when the configuration is valid.

Return type:

bool

Raises:

ValueError -- If a required property is missing or a cross-field invariant is violated.

freeze() → None

Internal

Validate and freeze the configuration.

Contract:

• Calls validate() first.

• Idempotent when already frozen.

Returns:

None.

Raises:

ValueError -- If validation fails.

emit_configured_twin_when_recording() → None

Internal emission seam

Emit the nexus twin for this configuration into the record.

Purpose:

Freeze is this configuration's true activation (Nexus.enable finalizes/freezes it as the enable step's confirmation), so the fresh freeze emits here. Reloaded configurations arrive at Nexus.enable ALREADY frozen (the reload lane seals without emission because enable has not happened yet), so enable calls this seam directly - the same fix class as the spellbook conjure re-freeze.

Contract:

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

• Payload carries plain values only: scalars pass through, enums record their member NAME, collections record as lists of strings, everything else stringifies whole.

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

Returns:

None.

finalize() → NexusConfiguration

Fluent

Validate and freeze the configuration, then return self.

Contract:

• Returns this same configuration instance after freezing it.

• Does not allocate or clone a detached configuration object.

Returns:

This configuration instance.

Return type:

NexusConfiguration

property activated: bool

Return whether this policy object has been marked ready to install.

Contract:

• REPORTS THE POLICY OBJECT, NOT THE NEXUS. A True here means the caller finished authoring and called activate(); it says nothing about whether Nexus.activate(...) was ever reached. Two objects, two bits.

• Independent of frozen. Freezing settles the values; activating declares them ready. A frozen-but-unactivated configuration is the normal state after finalize().

Threading:

Unsynchronized read of a plain flag; a snapshot only.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True once activate() has run on this object.

Return type:

bool

activate() → NexusConfiguration

Validate, freeze, and mark this configuration active.

Purpose:

The activation rung this configuration never had. Crystallizer and mutation-research configurations have always carried it, and their roots take an ALREADY-ACTIVATED policy object. Nexus had no such rung because enable() sealed the configuration on the caller's behalf - which is why it was the one subsystem out of four where the caller could not settle policy before installing it.

Guidance:

The normal final authoring step before Nexus.activate(configuration). It changes only this policy object's readiness.

Contract:

• Freezes and marks this policy object ready. It does NOT enable or activate the Nexus singleton; that is a separate call.

• Idempotent: freeze() is idempotent and the flag is a plain set with no side effect attached.

• finalize() remains freeze-only. The two verbs are different rungs and neither implies the other.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned() through freeze().

Raises:

• RuntimeError -- If the configuration has been cleaned.

• ValueError -- If validation fails during freeze.

Returns:

This activated configuration instance.

Return type:

NexusConfiguration

build() → NexusConfiguration

Fluent alias for finalize().

Contract:

• Preserves the builder-style API used elsewhere in the runtime.

• Returns this same configuration instance after finalize/freeze.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_defaults() → NexusConfiguration

Fluent

Load the standard Nexus defaults and return self.

Contract:

• Delegates to load_default_dictionary().

• Applies the default process-wide governance/property set in-place.

• Leaves the configuration mutable until freeze() or finalize().

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_rift_creation_enabled(enabled: bool = True) → NexusConfiguration

Fluent

Set whether Nexus may create new Rifts.

Parameters:

enabled -- True to permit Rift creation/programming under the remaining policy gates.

Contract:

• The master gate for creating or programming Rifts. Every other creation policy below only narrows this; with it False no token or nesting setting can permit creation.

• Writes the allow_rift_creation property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_creation_token_required(enabled: bool = True) → NexusConfiguration

Fluent

Set whether Rift creation/programming requires a creation token.

Parameters:

enabled -- True to require creation_token_value during creation.

Contract:

• Demands a creation token. Setting this True without also setting a token value leaves creation unreachable rather than open - the requirement is checked, the value is not defaulted.

• Writes the creation_token_required property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_creation_token(token_value: str | None) → NexusConfiguration

Fluent

Set the process-wide creation token value for Nexus.

Parameters:

token_value -- Optional creation token string. None clears the token value.

Contract:

• CREDENTIAL MATERIAL. Accepts None explicitly to clear it. Treat the stored value as a secret: do not log it, print it, or copy it into tickets or documentation.

• Writes the creation_token_value property, declared as str or None. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_direct_rift_access(enabled: bool = True) → NexusConfiguration

Fluent

Set whether callers may retrieve live Rift objects directly from Nexus.

Parameters:

enabled -- True to allow direct live-Rift access under the remaining policy gates.

Contract:

• Whether callers may reach a Rift directly rather than through Nexus routing. Independent of the creation gates - a frame can permit access while refusing creation.

• Writes the allow_direct_rift_access property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_rift_access_token_required(enabled: bool = True) → NexusConfiguration

Fluent

Set whether direct live-Rift access requires a token.

Parameters:

enabled -- True to require rift_access_token_value for direct Rift retrieval.

Contract:

• Demands an access token on the read path. Independent of creation_token_required; the two protect different operations and neither implies the other.

• Writes the rift_access_token_required property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_rift_access_token(token_value: str | None) → NexusConfiguration

Fluent

Set the token value used for direct live-Rift access.

Parameters:

token_value -- Optional Rift-access token string. None clears the token.

Contract:

• CREDENTIAL MATERIAL. Accepts None explicitly to clear it. Treat the stored value as a secret: do not log it, print it, or copy it into tickets or documentation.

• Writes the rift_access_token_value property, declared as str or None. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_allow_external_rift_registration(enabled: bool = True) → NexusConfiguration

Fluent

Set whether Nexus may program externally created Rift shells.

Parameters:

enabled -- True to permit external Rift registration/programming.

Contract:

• Whether Rifts constructed outside this Nexus may register into it. This is the trust boundary for foreign objects entering the registry.

• Writes the allow_external_rift_registration property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_allow_nested_rift_creation(enabled: bool = True) → NexusConfiguration

Fluent

Set whether running Rifts may create nested Rifts.

Parameters:

enabled -- True to permit nested Rift creation flows.

Contract:

• Whether a Rift may itself create further Rifts. Leaving this False keeps the Rift topology one level deep and bounds fan-out.

• Writes the allow_nested_rift_creation property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_max_active_rift_count(count: int) → NexusConfiguration

Fluent

Set the cap on concurrently registered active Rifts.

Parameters:

count -- Maximum number of active Rifts. 0 means unlimited.

Contract:

• 0 MEANS UNLIMITED, not "none allowed". Validation requires >= 0, so there is no way to express a hard zero cap through this setter - use with_rift_creation_enabled(False) for that.

• Writes the max_active_rift_count property, declared as int. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_nexus_frame_mode(mode: NexusFrameMode | str) → NexusConfiguration

Fluent

Set the internal Nexus frame topology mode.

Parameters:

mode -- Frame-topology mode enum or string.

Contract:

• CROSS-FIELD RULE: single requires max_nexus_frame_count == 1. Selecting single without also setting that count to 1 makes validate() and therefore freeze() raise.

• Writes the nexus_frame_mode property, declared as NexusFrameMode. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_default_nexus_frame_name(frame_name: str) → NexusConfiguration

Fluent

Set the default Nexus-owned internal frame name.

Parameters:

frame_name -- Frame name used in single mode and as the base name in other modes.

Contract:

• MUST BE NON-EMPTY at validation. An empty string is accepted by set_property (it satisfies the declared str type) and only rejected later at freeze.

• Writes the default_nexus_frame_name property, declared as str. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_auto_create_nexus_frames(enabled: bool = True) → NexusConfiguration

Fluent

Set whether the runtime may auto-create internal Nexus frames when Rift activation later resolves them through Aether.

Parameters:

enabled -- True to auto-create required Nexus frames on engagement or state creation.

Contract:

• Whether a missing target frame is created on demand rather than refused. With it False, routing to an unknown frame is an error instead of a side effect.

• Writes the auto_create_nexus_frames property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_max_nexus_frame_count(count: int) → NexusConfiguration

Fluent

Set the cap on Nexus-assigned internal frames.

Parameters:

count -- Maximum number of internal Nexus frames allowed.

Contract:

• MUST BE >= 1; zero is rejected at validation. CROSS-FIELD RULE: it must be exactly 1 when nexus_frame_mode is single.

• Writes the max_nexus_frame_count property, declared as int. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_allowed_target_frame_names(frame_names: Sequence[str]) → NexusConfiguration

Fluent

Set the allow-list for targetable frames.

Parameters:

frame_names -- Sequence of permitted target frame names.

Contract:

• Stored as a TUPLE. A list is normalized on the way in, and every element must be a str or validation rejects the whole collection.

• Writes the allowed_target_frame_names property, declared as tuple[str, ...]. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_denied_target_frame_names(frame_names: Sequence[str]) → NexusConfiguration

Fluent

Set the deny-list for targetable frames.

Parameters:

frame_names -- Sequence of denied target frame names.

Contract:

• Stored as a TUPLE, normalized like the allow-list. Deny is evaluated as its own collection; this setter does not reconcile it against allowed_target_frame_names.

• Writes the denied_target_frame_names property, declared as tuple[str, ...]. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_target_frame_override(enabled: bool = True) → NexusConfiguration

Fluent

Set whether callers may override the allowed target-frame selection.

Parameters:

enabled -- True to allow per-Rift target-frame override requests.

Contract:

• Whether a caller may name a target frame that differs from the configured default.

• Writes the allow_target_frame_override property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_multiple_target_frames(enabled: bool = True) → NexusConfiguration

Fluent

Set whether Nexus may target multiple external frames across its Rifts.

Parameters:

enabled -- True to permit more than one distinct target frame.

Contract:

• CROSS-FIELD RULE: when False, max_target_frame_count MUST be 1. Turning this off without resetting that count to 1 makes validate() and therefore freeze() raise.

• Writes the allow_multiple_target_frames property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_max_target_frame_count(count: int) → NexusConfiguration

Fluent

Set the cap on distinct target frames Nexus may use.

Parameters:

count -- Maximum number of distinct target frames.

Contract:

• MUST BE >= 1; zero is rejected at validation. CROSS-FIELD RULE: it must be exactly 1 when allow_multiple_target_frames is False.

• Writes the max_target_frame_count property, declared as int. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_projection_refresh_gate(enabled: bool = True) → NexusConfiguration

Fluent

Set whether ACL-driven projection refresh uses the RiftGate drain barrier.

Parameters:

enabled -- True to block new entrants, wait for in-flight work to drain, refresh projections/viewers, then reopen gates.

Contract:

• Whether projection reads wait for a refresh to settle rather than returning immediately. The timeout and poll interval below only matter when this is enabled.

• Writes the projection_refresh_gate_enabled property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_projection_refresh_gate_timeout_seconds(timeout_seconds: int | float) → NexusConfiguration

Fluent

Set the timeout used while waiting for impacted Rift gates to drain.

Parameters:

timeout_seconds -- Positive timeout in seconds.

Contract:

• MUST BE > 0; zero and negatives are rejected at validation, so the gate can never be configured to give up instantly or wait forever.

• Writes the projection_refresh_gate_timeout_seconds property, declared as int or float. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_projection_refresh_gate_poll_interval_seconds(interval_seconds: int | float) → NexusConfiguration

Fluent

Set the poll interval used while waiting for impacted Rift gates to drain.

Parameters:

interval_seconds -- Positive poll interval in seconds.

Contract:

• MUST BE > 0. Nothing enforces that it is smaller than the timeout, so an interval larger than the timeout is accepted and yields a single poll attempt.

• Writes the projection_refresh_gate_poll_interval_seconds property, declared as int or float. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_default_space_type(space_type: RiftSpaceType | str) → NexusConfiguration

Fluent

Set the default room type for newly created Rifts.

Parameters:

space_type -- Default room-kind enum or string.

Contract:

• The space type new Rift spaces take when the caller does not name one. Accepts the enum or its string name; conversion is checked.

• Writes the default_space_type property, declared as RiftSpaceType. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_default_auto_activate_on_program(enabled: bool = True) → NexusConfiguration

Fluent

Set whether newly programmed Rifts activate automatically.

Parameters:

enabled -- True to mark new Rifts active during programming.

Contract:

• Whether a programmed Rift activates immediately rather than waiting for an explicit activation.

• Writes the default_auto_activate_on_program property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_default_auto_create_space(enabled: bool = True) → NexusConfiguration

Fluent

Set whether newly programmed Rifts auto-create an initial room.

Parameters:

enabled -- True to create the initial room automatically.

Contract:

• Whether a missing space is created on demand rather than refused.

• Writes the default_auto_create_space property, declared as bool. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

with_default_validation_mode(mode: RiftValidationMode | str) → NexusConfiguration

Fluent

Set the default validation posture for newly created Rifts.

Parameters:

mode -- Validation mode enum or string.

Contract:

• The default strictness applied to Rift contents. Accepts the enum or its string name; conversion is checked.

• Writes the default_validation_mode property, declared as RiftValidationMode. ALL enforcement lives in set_property: it rejects unknown keys, enforces the declared type, normalizes enum and frame-list values, and refuses any write once the configuration is frozen. This method adds no validation of its own.

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

• EVERY declared property is REQUIRED at freeze - validate() raises on the first missing key. Start from with_defaults() and override, rather than setting properties individually.

Threading:

Serialized by set_property under the configuration lock.

Lifecycle / Cleanup:

Guarded via set_property; refused after freeze.

Raises:

• RuntimeError -- If the configuration is already frozen.

• TypeError -- If the value does not satisfy the declared type.

Returns:

This configuration instance.

Return type:

NexusConfiguration

Topic reference · Full contents