On this page

• CrystallizerConfiguration
  • CrystallizerConfiguration
    • CrystallizerConfiguration.cleanup()
    • CrystallizerConfiguration.id
    • CrystallizerConfiguration.frozen
    • CrystallizerConfiguration.activated
    • CrystallizerConfiguration.set_property()
    • CrystallizerConfiguration.get_property()
    • CrystallizerConfiguration.retain_user_sources
    • CrystallizerConfiguration.site_package_dependency_descent
    • CrystallizerConfiguration.remove_inactive_synthmodules
    • CrystallizerConfiguration.checkpoint_interval_minutes
    • CrystallizerConfiguration.max_persistence_crystals
    • CrystallizerConfiguration.auto_flush_checkpoints
    • CrystallizerConfiguration.with_auto_flush_checkpoints()
    • CrystallizerConfiguration.restore_parallel_enabled
    • CrystallizerConfiguration.restore_scheduler_workers
    • CrystallizerConfiguration.restore_scheduler_barrier_timeout_milliseconds
    • CrystallizerConfiguration.has_property()
    • CrystallizerConfiguration.validate()
    • CrystallizerConfiguration.freeze()
    • CrystallizerConfiguration.finalize()
    • CrystallizerConfiguration.activate()
    • CrystallizerConfiguration.with_defaults()
    • CrystallizerConfiguration.load_recorded_dictionary()
    • CrystallizerConfiguration.with_checkpoint_interval_minutes()
    • CrystallizerConfiguration.with_max_persistence_crystals()
    • CrystallizerConfiguration.with_retain_user_sources()
    • CrystallizerConfiguration.with_user_source_root_paths()
    • CrystallizerConfiguration.user_source_root_paths

CrystallizerConfiguration

Use md.CrystallizerConfiguration from the public package namespace.

Implementation source

class CrystallizerConfiguration

Authoring surface for crystallizer capture and durability policy.

Purpose:

Tell the public Crystallizer how to recognize user-owned modules, how much source custody to retain, when to seal checkpoints, how much in-process/local history to keep, and whether automatic seals should be shipped to durable assets. These are world-recording decisions, so they belong here rather than on individual SpellCrystal objects.

Guidance:

Start with with_defaults() unless restoring recorded policy. Override only deployment-specific decisions, then call activate() and pass the result to Crystallizer.activate(...). Common choices are:

• with_user_source_root_paths(...): classify application source roots.

• with_retain_user_sources(True): permit fresh-host source rebuilding.

• with_auto_flush_checkpoints(True): ship cadence seals to assets.

• with_max_persistence_crystals(...): bound rolling history.

Source retention can preserve sensitive or large code text; it is deliberately off by default. Root paths classify authority only?they do not modify sys.path, import modules, or grant filesystem access.

Contract:

• Mutable until freeze(), finalize(), or activate().

• with_defaults() produces a complete, valid baseline.

• finalize() freezes without marking the configuration active; activate() freezes and marks it ready for the crystallizer root.

• Recorded-policy reload uses a fresh instance and freezes it after applying recorded values over the compatibility defaults.

Threading:

One instance RLock serializes authoring and state transitions. Frozen instances are read-only and may be shared with the hosted root.

Lifecycle / Cleanup:

The caller owns the configuration until installation; the Crystallizer owns it afterwards and cleans it during root teardown. Callers must not independently clean an installed configuration because the live root continues to read policy from it.

Registration:

MELDER KERNEL - guarded (internal manifest). access=public because a user CONSTRUCTS one, sets policy fluently, and hands it to Crystallizer.activate(...). Guarding and being user-constructed are orthogonal: the guard only refuses it as a bind target (Melder never injects a configuration); the user still holds and drives it.

Subsystem Context:

The capture/durability POLICY surface of the crystallizer subsystem. It carries source-classification and checkpoint policy (world-recording decisions) so individual SpellCrystal objects do not; Crystallizer.activate(...) installs it, and the record/asset children read policy from it (retain_user_sources, checkpoint cadence, max rolling history, auto-flush). Paired with CrystallizerConfigurationBuilder (the ownership-wrapped authoring path).

System Context:

Crystallizer layer of the boot order (position 2, after Aether|AetherUtilitySystem). It is the world-recording contract that must be settled BEFORE the crystallizer activates: with_defaults() is complete easy mode (only user_source_root_paths is hard-required), and a recorded-policy reload freezes a fresh instance over compatibility defaults so a restored world records under the SAME policy that sealed it.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Capture and durability policy. with_defaults() is complete easy mode; only user_source_root_paths is hard-required. Set retain_user_sources for opt-in physical custody and checkpoint_interval_minutes for automatic cadence.

cleanup() → None

Idempotently clear configuration state.

Contract:

Terminal for this object. Marks it frozen/inactive, clears every policy value, and deletes identity/schema fields and the lock. It does not clean the crystallizer or remove persisted artifacts. Once installed, only the owning crystallizer should call cleanup; external cleanup would violate the live root's ownership contract.

Returns:

None.

Threading:

Serialized by the configuration lock; authoring must be quiescent.

Lifecycle / Cleanup:

The current owner?caller, builder, or crystallizer?cleans it when the policy object is no longer needed.

property id: str

Return the stable configuration id.

Contract:

• Identifies THIS CONFIGURATION OBJECT, not the crystallizer singleton 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 the configuration is sealed, meaning PROPERTY MUTATION IS CLOSED. It does not mean the policy is in force - that requires installing it on the crystallizer root.

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:

• Marks THIS POLICY OBJECT as ready, NOT the crystallizer. Activating a configuration does not activate the singleton; Crystallizer.activate( configuration) is the step that installs it.

• Activation implies frozen; frozen does NOT imply activated.

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 for the crystallizer root.

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.

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

Return one stored configuration property.

Parameters:

key -- Property name.

Returns:

Stored property value.

Return type:

object

Raises:

KeyError -- If the property has not been set.

property retain_user_sources: bool

Return whether user-owned module SOURCE TEXT is retained at seal.

Contract:

• Default FALSE (opt-in only; S2 physical custody): user code may be large or sensitive, so retention is a deliberate policy choice - False is byte-identical to the pre-S2 record at every surface.

• True: every module classified as user source retains text, SHA256, path, and package posture inside the SpellCrystal. On a fresh host, an absent file may rebuild through the synthetic module lane. Retained text never overrides a live file; drift is reported and the live file remains authoritative.

Returns:

The configured knob, default False.

Return type:

bool

property site_package_dependency_descent: bool

Return whether the analysis walk descends INTO installed packages.

Contract:

• Defaulted-optional (schema default False): when the key is absent, the walk records site-package modules as provenance-carrying LEAVES - distribution name/version and file identity still capture, but their source is never read and their dependencies never enqueue. Bind latency stays proportional to the USER world, not the installed one.

• True restores the pre-lane interior walk wholesale (module inventories of third-party packages re-enter the record).

• Site packages make no fingerprint claims either way (S1 law), so drift and restore surfaces are unaffected.

Returns:

The configured knob, default False.

Return type:

bool

property remove_inactive_synthmodules: bool

Return whether inactive spells' synthetic modules are unpublished.

Contract:

• Default False: parking changes recorded custody but leaves the synthetic root module published for maximum runtime continuity.

• True: parking may unpublish that root while retaining registry and custody state, making promotion reversible. A module with live published synthetic dependents stays resident under the reverse-edge safety check. Existing Python references remain live even after unpublication; this knob controls import visibility, not object destruction.

Returns:

The configured knob, default False.

Return type:

bool

property checkpoint_interval_minutes: int

Return the automatic-checkpoint cadence in minutes.

Contract:

• Default 60 (one hour): while the crystallizer is activated, the emit path seals a new PersistenceCrystal once at least this many minutes have passed since the previous automatic checkpoint. Cadence is activity-driven (checked at emit time), so a quiet world mints nothing - there is no background timer thread.

• Must be a positive int when set explicitly.

Returns:

The configured cadence, default 60.

Return type:

int

Raises:

ValueError -- If the stored value is not a positive int.

property max_persistence_crystals: int

Return the checkpoint-ledger retention cap.

Contract:

• Default 100: when a new PersistenceCrystal would exceed the cap, the oldest ledger entry by exact insertion order drops and cleans first. Local cache retention follows recorded checkpoint numbers, avoiding ambiguous same-millisecond ULID tails. External retention is a separate opt-in operation.

• Must be a positive int when set explicitly.

Returns:

The configured cap, default 100.

Return type:

int

Raises:

ValueError -- If the stored value is not a positive int.

property auto_flush_checkpoints: bool

Return whether automatic checkpoints also flush to the local cache.

Contract:

• Default False: cadence seals remain in the in-process ledger until a caller explicitly flushes them.

• True: every automatic seal runs the normal asset flush?local atomic cache write first, followed by the optional external mesh write when a manager is attached and uploads are enabled.

Returns:

The configured knob, default False.

Return type:

bool

with_auto_flush_checkpoints(enabled: bool) → CrystallizerConfiguration

Set whether automatic checkpoints also flush to the local cache.

Parameters:

enabled -- True = every cadence seal ships its cached-item to disk.

Contract:

• COERCES with bool(...) rather than type-checking, so any truthy value is accepted and silently converted. That is looser than the strict isinstance setters elsewhere in this class.

• True makes every cadence seal ship its cached item to disk, trading throughput for durability.

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

CrystallizerConfiguration

property restore_parallel_enabled: bool

Return whether checkpoint restore runs the parallel driver.

Contract:

• Default True (owner ruling 2026-07-19: parallel IS the driver): the loader owns a PhaseScheduler pool and the RestoreEngine executes graph-derived levels as phases.

• False selects the sequential fallback driver - the canon single-thread stage chain, byte-identical to the pre-parallel engine. The same knob is the rollback lane.

Returns:

The configured driver selector, default True.

Return type:

bool

property restore_scheduler_workers: int

Return the restore scheduler's worker-thread count.

Contract:

• Default 4: the loader-owned PhaseScheduler pool width for per-entity replay units inside each plan level.

• Must be a positive int when set explicitly.

Returns:

The configured worker count, default 4.

Return type:

int

Raises:

ValueError -- If the stored value is not a positive int.

property restore_scheduler_barrier_timeout_milliseconds: int

Return the restore scheduler's per-phase barrier timeout.

Contract:

• Default 60000 (one minute): restore units import and bind real code, so spellbook-scale phase timeouts would abort large-world loads.

• Must be a positive int (milliseconds) when set explicitly.

Returns:

The configured barrier timeout in ms, default 60000.

Return type:

int

Raises:

ValueError -- If the stored value is not a positive int.

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 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 crystallizer policy bag is complete and coherent.

Contract:

• user_source_root_paths is the only hard-required property.

• retain_user_sources (False), remove_inactive_synthmodules (False), checkpoint_interval_minutes (60), max_persistence_crystals (100), auto_flush_checkpoints (False), restore_parallel_enabled (True), restore_scheduler_workers (4), and restore_scheduler_barrier_timeout_milliseconds (60000) carry defaults and are only semantically checked when set explicitly.

Returns:

True when the configuration is valid.

Return type:

bool

Raises:

ValueError -- If a required property is missing or semantically invalid.

freeze() → None

Validate and freeze the configuration without activating it.

Contract:

Idempotent. After success, all authoring methods refuse mutation; the configuration is suitable for inspection or later activation.

Returns:

None.

finalize() → CrystallizerConfiguration

Validate and freeze the configuration, then return it.

Guidance:

Choose this when another owner should decide when activation occurs. Use activate() when the next step is installation on the live crystallizer root.

Contract:

• freeze() plus return self: seals WITHOUT marking the policy ready.

• Choose it when a DIFFERENT owner will decide when activation happens; choose activate() when installation on the crystallizer root is the next step.

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

CrystallizerConfiguration

activate() → CrystallizerConfiguration

Validate, freeze, and mark the configuration active.

Guidance:

This is the normal final authoring step before Crystallizer.activate(configuration). It changes only this policy object's readiness; it does not activate the singleton by itself.

Contract:

• Freezes and marks this policy object ready. UNLIKE the Aether and mutation-research configurations, it EMITS NOTHING - there is no activation record here, because this object configures the recorder itself.

• It does NOT activate the crystallizer singleton; that is a separate Crystallizer.activate(configuration) call.

• Safe to call more than once: freeze is idempotent and the flag is a plain set with no side effect attached.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

This activated configuration instance.

Return type:

CrystallizerConfiguration

with_defaults() → CrystallizerConfiguration

Load the complete default crystallizer policy set (easy mode).

Purpose:

One-call default posture, mirroring the AethericFrame configuration builder style: chain it, then activate(). CrystallizerConfiguration().with_defaults().activate() is a fully valid configuration.

Contract:

• user_source_root_paths: resolved current working directory.

• retain_user_sources: False (fingerprints/paths, no source text).

• remove_inactive_synthmodules: False (keep imports resident).

• checkpoint_interval_minutes: 60 activity-driven minutes.

• max_persistence_crystals: 100-entry rolling ledger/cache cap.

• auto_flush_checkpoints: False (manual durability flush).

• restore_scheduler_workers: 4 (loader-owned PhaseScheduler pool size for parallel restore phases).

• restore_scheduler_barrier_timeout_milliseconds: 60000 (generous per-level barrier bound: restore units import and bind real code, so short spellbook-style timeouts would abort legitimate large-world loads).

• restore_parallel_enabled: True (owner ruling 2026-07-19: parallel is THE restore driver; False selects the sequential fallback driver).

• site_package_dependency_descent: False (analysis walks stop AT installed third-party packages; provenance still captures).

Returns:

This configuration instance.

Return type:

CrystallizerConfiguration

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 cache-boot counterpart to with_defaults. When a world reboots from cached checkpoints, the crystallizer's own policy (source roots, retention, cadence, flush posture) is part of the recorded truth - it reloads from the CrystallizerCrystal payload, never from present-day defaults, and the lane loads and freezes 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.

• user_source_root_paths recorded as a list (the emission scalar filter's collection form) re-tuples on the way in.

• A recorded value the property system refuses is skipped and returned under "rejected" as "key: reason" (documented best-effort collection for the caller's reporting).

• LOADS AND FREEZES in one motion: the returned state is sealed. The freeze emits nothing; the crystallizer twin emits at Crystallizer.activate, the configured moment.

Parameters:

recorded_properties -- Property name -> recorded value mapping (one sealed, JSON-safe CrystallizerCrystal 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_checkpoint_interval_minutes(minutes: int) → CrystallizerConfiguration

Set the automatic-checkpoint cadence in minutes.

Parameters:

minutes -- Positive minute count between automatic checkpoints (1 = every minute, 60 = hourly).

Returns:

This configuration instance.

Return type:

CrystallizerConfiguration

Raises:

ValueError -- If minutes is a bool, not an int, or not positive.

with_max_persistence_crystals(max_crystals: int) → CrystallizerConfiguration

Set the checkpoint-ledger retention cap.

Parameters:

max_crystals -- Positive maximum ledger size; the oldest crystal drops out when a new checkpoint would exceed it.

Returns:

This configuration instance.

Return type:

CrystallizerConfiguration

Raises:

ValueError -- If max_crystals is a bool, not an int, or not positive.

with_retain_user_sources(retain: bool) → CrystallizerConfiguration

Set the opt-in user-source TEXT retention policy (S2 custody).

Parameters:

retain -- True retains user-owned module source text inside sealed SpellCrystals for fresh-pod rebuilds; False (default) records paths and fingerprints only.

Contract:

• OPT-IN CUSTODY DECISION, and it defaults to FALSE for good reason: when True, USER-OWNED MODULE SOURCE TEXT IS RETAINED INSIDE SEALED CRYSTALS. With it False only paths and fingerprints are recorded.

• Enable it only when fresh-pod rebuilds genuinely require the source, and only when the crystal store is a trusted location - it changes what a crystal CONTAINS, not merely what it references.

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

CrystallizerConfiguration

with_user_source_root_paths(root_paths: Sequence[str | Path]) → CrystallizerConfiguration

Set the user-owned source roots used for module classification.

Purpose:

Distinguish application code from site packages and unknown/binary authority during crystal analysis. Inputs resolve to absolute, deduplicated Path values at authoring time.

Contract:

This policy does not require the roots to exist immediately, does not add them to sys.path, and does not read their contents. It is a classification boundary consumed later by analysis.

Parameters:

root_paths -- Sequence of filesystem roots that should count as user-owned source authority during crystal dependency classification.

Returns:

This configuration instance.

Return type:

CrystallizerConfiguration

property user_source_root_paths: Tuple[Path, ...]

Return the normalized user-source root tuple.

Contract:

• DEFENSIVE READ: the value must remain a tuple of Path entries, and a drifted element raises TypeError rather than being returned. That guards against direct tampering with the property bag.

• Returns NORMALIZED, resolved paths rather than the raw strings that may have been supplied.

Threading:

State transitions are applied under the configuration lock.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

Configured source roots as resolved paths.

Return type:

Tuple[Path, ...]

Topic reference · Full contents