On this page

• RiftConfiguration
  • RiftConfiguration
    • RiftConfiguration.cleanup()
    • RiftConfiguration.frozen
    • RiftConfiguration.consumed
    • RiftConfiguration.set_property()
    • RiftConfiguration.get_property()
    • RiftConfiguration.space_type
    • RiftConfiguration.has_property()
    • RiftConfiguration.load_default_dictionary()
    • RiftConfiguration.validate()
    • RiftConfiguration.freeze()
    • RiftConfiguration.finalize()
    • RiftConfiguration.mark_consumed()
    • RiftConfiguration.build()
    • RiftConfiguration.with_defaults()
    • RiftConfiguration.with_space_type()
    • RiftConfiguration.with_space_name()
    • RiftConfiguration.with_auto_activate_on_program()
    • RiftConfiguration.with_validation_mode()

RiftConfiguration

Use md.RiftConfiguration from the public package namespace.

Implementation source

class RiftConfiguration

Internal

Per-Rift configuration object used by Nexus to build one live Rift.

Purpose:

Capture configurable runtime behavior for one Rift without making the live public Rift object itself the configuration root.

Contract:

• Mutable until frozen.

• Stores typed properties in one property bag.

• Provides fluent with_* helpers mirroring the Spellbook configuration style.

• Captures per-Rift runtime defaults only; process-wide governance lives in NexusConfiguration.

Registration:

MELDER KERNEL - guarded. Built through Nexus.create_rift_configuration and consumed at Rift creation.

Subsystem Context:

The per-Rift configuration object, sitting below process-wide NexusConfiguration. Its space_type is what programs the Rift's one primary room.

System Context:

The opening line states the design rule plainly: the live public Rift is NOT the configuration root. Keeping configuration in a separate mutable-then-frozen object means a Rift's runtime surface stays about live behaviour, and configuration cannot be mutated through the object callers hold. This is also where the process-wide/per-Rift boundary lands. Creation and access gates, frame topology, and budgets are governance and belong to NexusConfiguration; room posture and per-Rift defaults legitimately differ between Rifts and belong here.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Per-Rift settings, chiefly space_type which fixes the room posture for the Rift's life. Mutable until frozen. Build via Nexus.create_rift_configuration().

cleanup() → None

Internal

Idempotently cleanup the configuration and clear all state.

Contract:

• Marks the object cleaned and frozen.

• Clears the property bag and property registry.

Returns:

None.

property frozen: bool

Purpose:

Return whether further mutation is forbidden.

Returns:

True when the configuration is finalized.

Return type:

bool

property consumed: bool

Purpose:

Return whether this configuration has already been consumed by Rift creation.

Returns:

True when consumed.

Return type:

bool

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

Internal

Set one per-Rift configuration property before freeze().

Parameters:

• key -- Property name.

• value -- Property value.

Contract:

• Rejects mutation after freeze().

• Normalizes enum-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 per-Rift configuration property value.

Parameters:

key -- Property name.

Returns:

Stored property value.

Return type:

object

Raises:

KeyError -- If the property has not been set.

property space_type: RiftSpaceType

Return the typed top-level room kind for this configuration.

Returns:

Stored room kind used when programming the primary Rift space.

Return type:

RiftSpaceType

Raises:

TypeError -- If the stored space_type payload is not a RiftSpaceType.

has_property(key: str) → bool

Internal

Return whether a property has been set.

Parameters:

key -- Property name.

Contract:

• Tests whether the key has been SET, not whether it is a legal key. An unknown key returns False rather than raising.

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

Return type:

bool

load_default_dictionary() → None

Internal

Load the standard default property set for one Rift.

Contract:

• Sets default room type, room naming posture, activation posture, validation mode, and room-event configuration defaults used when Nexus builds a Rift without overrides.

• Does not select or bind any target frames.

Returns:

None.

validate() → bool

Internal

Validate that every required per-Rift property is present.

Contract:

• Ensures every declared per-Rift property has a value before programming/build.

• Performs presence checks only; enum normalization already happens during set_property(...).

Returns:

True when the configuration is valid.

Return type:

bool

Raises:

ValueError -- If a required property is missing.

freeze() → None

Internal

Validate and freeze the configuration.

Contract:

• Calls validate() before setting the frozen state.

• Idempotent when already frozen.

Returns:

None.

Raises:

ValueError -- If validation fails.

finalize() → RiftConfiguration

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:

RiftConfiguration

mark_consumed() → None

Internal

Mark this configuration as consumed by successful Rift creation.

Contract:

• Consumed configurations are not reusable for another Rift.

• Does not imply cleanup.

Returns:

None.

build() → RiftConfiguration

Fluent alias for finalize().

Contract:

• Preserves the builder-style API used by Rift creation flows.

• Returns this same configuration instance after finalize/freeze.

Returns:

This configuration instance.

Return type:

RiftConfiguration

with_defaults() → RiftConfiguration

Fluent

Load the standard per-Rift defaults and return self.

Contract:

• Delegates to load_default_dictionary().

• Applies the default per-Rift property set in-place.

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

Returns:

This configuration instance.

Return type:

RiftConfiguration

with_space_type(space_type: RiftSpaceType | str) → RiftConfiguration

Fluent

Set the top-level room type for this Rift.

Parameters:

space_type -- Room-kind enum or string (static, capability, or codegen) used to instantiate the primary space during Rift creation.

Contract:

• Selects the PRIMARY space instantiated during rift creation. Accepts the enum or its string name (static, capability, codegen); conversion is checked, so an unrecognized name raises.

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

• 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:

RiftConfiguration

with_space_name(space_name: str | None) → RiftConfiguration

Fluent

Set the initial room name for this Rift, if any.

Parameters:

space_name -- Optional stable room name.

Contract:

• The one property whose declared type admits None, so passing None is a legal "unnamed space" rather than an error.

• MUTATES THIS OBJECT and returns self.

• 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:

RiftConfiguration

with_auto_activate_on_program(enabled: bool = True) → RiftConfiguration

Fluent

Set whether the Rift activates immediately when programmed.

Parameters:

enabled -- True to mark the Rift active during programming.

Contract:

• Decides whether programming a rift also activates it, rather than leaving activation as a separate explicit step.

• MUTATES THIS OBJECT and returns self.

• 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:

RiftConfiguration

with_validation_mode(mode: RiftValidationMode | str) → RiftConfiguration

Fluent

Set the validation posture for this Rift.

Parameters:

mode -- Validation mode enum or string.

Contract:

• Sets the strictness applied to rift contents. Accepts the enum or its string name; conversion is checked.

• MUTATES THIS OBJECT and returns self.

• 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:

RiftConfiguration

Topic reference · Full contents