On this page

• MutationResearchConfiguration
  • MutationResearchConfiguration
    • MutationResearchConfiguration.cleanup()
    • MutationResearchConfiguration.id
    • MutationResearchConfiguration.frozen
    • MutationResearchConfiguration.activated
    • MutationResearchConfiguration.set_property()
    • MutationResearchConfiguration.get_property()
    • MutationResearchConfiguration.has_property()
    • MutationResearchConfiguration.validate()
    • MutationResearchConfiguration.freeze()
    • MutationResearchConfiguration.finalize()
    • MutationResearchConfiguration.activate()
    • MutationResearchConfiguration.describe_configuration_payload()
    • MutationResearchConfiguration.load_recorded_dictionary()
    • MutationResearchConfiguration.with_defaults()
    • MutationResearchConfiguration.with_unrestricted_module_mutations()
    • MutationResearchConfiguration.with_lane_type_enforcement()

MutationResearchConfiguration

Use md.MutationResearchConfiguration from the public package namespace.

Implementation source

class MutationResearchConfiguration

Mutable-to-frozen configuration surface for the mutation-research root.

Purpose:

Hold mutation-research-wide policy inputs before the Aether-owned mutation-research root is activated.

Contract:

• mutable until frozen

• validates required properties before freeze/activation

• activation is explicit and implies successful validation/freeze

• thread-safe mutations are serialized with the instance lock

Registration:

MELDER KERNEL - guarded. Obtained through MutationResearch.create_configuration(), not registered.

Subsystem Context:

The policy surface of the mutation-research root, paired with MutationResearchConfigurationBuilder for fluent assembly. It follows the same mutable-then-frozen shape as the Aether, Spellbook, and crystallizer configurations, so all four read alike.

System Context:

Activation is this object's EMISSION MOMENT, which makes ordering load-bearing: config activation necessarily precedes root activation, so it must carry the recorded composition forward into its twin. Without that, replace-on-emit would wipe the record moments before hydration reads it. lane_type_enforcement also lives here, propagating to every research set at activation, hydration, and set creation.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Research-root policy. with_defaults() covers it; set lane_type_enforcement to gate cross-type lane joins. activate() is its emission moment.

cleanup() → None

Idempotently clear configuration state.

Contract:

• IDEMPOTENT under double-checked locking.

• MARKS THE CONFIGURATION FROZEN AND DEACTIVATED as it tears down, so a cleaned configuration can never be observed as live mid-teardown.

• Clears and then deletes the property bag and type table; the object is unusable afterwards.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

None.

property id: str

Return the stable configuration id.

Contract:

• Identifies THIS CONFIGURATION OBJECT, not the mutation-research system it configures. Assigned at construction and stable for its life.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

Stable configuration id.

Return type:

str

property frozen: bool

Return whether the configuration is frozen.

Contract:

• True once freeze() has sealed the values, meaning SETTERS ARE REFUSED. It does NOT mean the configuration is in use - that is activated.

• Also set True by cleanup(), so a cleaned configuration reads 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:

True when property mutation is closed.

Return type:

bool

property activated: bool

Return whether the configuration has been activated.

Contract:

• True only after activate(). Activation implies frozen, but FROZEN DOES NOT IMPLY ACTIVATED - finalize() freezes without activating.

• Reset to False by cleanup().

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when the config is validated, frozen, and marked ready.

Return type:

bool

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

Set one configuration property before freeze/activation.

Parameters:

• key -- Property name.

• value -- Candidate property value.

Contract:

• Refuses after freeze, checked TWICE - once before taking the lock and again inside it - so a concurrent freeze cannot slip a write through.

• Rejects unknown keys with ValueError and wrong types with TypeError, both validated against the declared type table.

• The only two accepted keys are unrestricted_module_mutations and lane_type_enforcement, both bools.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

None.

get_property(key: str) → object

Return one stored configuration property.

Parameters:

key -- Property name.

Contract:

• RAISES KeyError for a property that was never set - it is a raw bag lookup, not a defaulted getter. Use has_property(...) first, or seed the configuration before reading.

• Returns the stored value BY REFERENCE without re-validating its type.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

Stored property value.

Return type:

object

has_property(key: str) → bool

Return whether one property is currently defined.

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, so this cannot be used to validate a property name against the schema.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when the property has been set.

Return type:

bool

validate() → bool

Validate that the mutation-research policy bag is complete and coherent.

Contract:

• COMPLETENESS ONLY: it requires every declared key to be present and applies no cross-field rules, because the two properties are independent.

• NEVER RETURNS False - a missing key raises ValueError. The bool return is convention, which makes freeze's if not self.validate() branch unreachable.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when the configuration is valid.

Return type:

bool

freeze() → None

Validate and freeze the configuration.

Contract:

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

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

• Seals values only; it does NOT activate and records nothing.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

None.

finalize() → MutationResearchConfiguration

Validate and freeze the configuration, then return it.

Contract:

• freeze() plus return self - nothing more. Seals WITHOUT activating and WITHOUT recording.

• Idempotent, inheriting freeze's early return.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This configuration instance.

Return type:

MutationResearchConfiguration

activate() → MutationResearchConfiguration

Validate, freeze, and mark the configuration as activated.

Contract:

• Freezes, marks ACTIVE, then EMITS a crystallizer record when recording is on. That emission is the side effect finalize() does not have.

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

• Emission is skipped entirely pre-boot, when the crystallizer singleton is not yet initialized, and when it is not activated - so a missing record does not imply a failed activation.

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:

MutationResearchConfiguration

describe_configuration_payload() → Dict[str, object]

Return the value-coerced configuration surface for recording.

Purpose:

The shared twin-payload builder: configuration activation and the root's composition re-emissions both record the SAME value-typed property mapping, so the persisted configuration surface can never drift between emission seams.

Contract:

• Plain values (str/int/float/bool/None) pass through; anything else records as its string form (records carry values only).

Returns:

Detached property name -> recorded value mapping.

Return type:

Dict[str, object]

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 counterpart to with_defaults (owner reload-lane law; MR's original exclusion from the directive is obsolete now that the skeleton is a real subsystem). A sealed world's research posture rebuilds from its recorded values - never from present-day defaults - and the lane loads and seals in one motion.

Contract:

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

• A recorded value the property system refuses is skipped and returned under "rejected" as "key: reason" (documented best-effort collection for the caller's shortfall reporting). The registry's single bool key needs no type coercion (JSON round-trips bools natively).

• SEALS VIA activate() on return (freeze + activated): the config's activation is its emission factor, so the reload re-records into the fresh active profile mid-replay - the Nexus-precedent re-recording covenant; replace-on-emit means the root's later composition re-emission supersedes this twin in the same profile.

Parameters:

recorded_properties -- Property name -> recorded value mapping (one sealed MutationResearchCrystal configuration_payload, as built by describe_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 freeze.

with_defaults() → MutationResearchConfiguration

Apply the default mutation-research posture.

Contract:

• Unrestricted module mutation is disabled by default.

• Lane-type enforcement is disabled by default (the vocabulary is always available; the join policy gate is opt-in).

Returns:

This configuration instance.

Return type:

MutationResearchConfiguration

with_unrestricted_module_mutations(enabled: bool) → MutationResearchConfiguration

Set the unrestricted-module-mutations posture.

Parameters:

enabled -- Whether unrestricted module mutation mode is enabled.

Contract:

• FLUENT WRAPPER over set_property("unrestricted_module_mutations", ...); it delegates and returns self, adding no validation of its own.

• MUTATES THIS OBJECT rather than producing a variant.

• Refused once frozen.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This configuration instance.

Return type:

MutationResearchConfiguration

with_lane_type_enforcement(enabled: bool) → MutationResearchConfiguration

Set the lane-type-enforcement posture.

Purpose:

When enabled, joining two lanes of DIFFERENT types (e.g. experiment -> production) requires the explicit force=True supersede; the lane-type vocabulary itself is always available.

Parameters:

enabled -- Whether type-mixing joins require force.

Returns:

This configuration instance.

Return type:

MutationResearchConfiguration

Topic reference · Full contents