On this page

Crystallizer
- Crystallizer

Crystallizer

Use md.Crystallizer from the public package namespace.

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

Public facade and singleton ownership root for crystallizer behavior.

Purpose:

Present one stable public surface over the crystallizer's three V3 subsystems while keeping their implementation objects private:

PersistenceSystem: the in-process record and checkpoint ledger.
AssetManagementSystem: cache, formation files, and external mesh.
CrystalLoaderSystem: admission planning and runtime unfolding.

The package-level crystal classes remain value carriers, and crystal_analysis remains a shared service; neither becomes another root owned by callers.

Usage:

Importing melder constructs the hosting Aether, so subsequent Crystallizer() calls return its hosted facade. Create and activate a configuration, activate this root, then use facade verbs for profiles, checkpoints, formations, impact analysis, or restore. Treat the three owned subsystem classes as implementation boundaries; construct and operate them only through this facade.

Contract:

Threading:: The class lock protects singleton publication. The instance lock serializes lifecycle and facade state transitions; owned subsystems apply their own narrower locking contracts.
Lifecycle / Cleanup:: Aether owns the singleton. Cleanup is terminal and orders borrowers before the record: loader, assets, persistence, then configuration. Singleton bookkeeping is reset only after child teardown completes.
Registration:: MELDER KERNEL - guarded, access=public. A process-wide singleton privately hosted by Aether; the user configures, activates, and drives it through its facade verbs but never registers it with bind() - the guard refuses that.
Subsystem Context:: The public facade and ownership ROOT of the crystallizer. It presents one stable surface over the three V3 subsystems it privately owns - PersistenceSystem (the in-process record + checkpoint ledger), AssetManagementSystem (cache, formation files, external mesh), and CrystalLoaderSystem (admission planning + runtime unfolding) - while the crystal-twin value carriers and the crystal_analysis service stay callable seams beneath it. Callers exchange names, ids, detached dicts, and crystal carriers here; the subsystem objects never escape as public state.
System Context:: Crystallization is the DGR's serialize-then-restore capability, and this root is where the design's key discipline lives: recording is PASSIVE - runtime owners push twins into emit(), the root never discovers or walks the live world - so an active crystallizer observes the world being built rather than snapshotting it, and a crystallizer-off world runs identically because inactive emit paths simply do nothing. Owning the three subsystems privately behind one facade (with a strict teardown order loader -> assets -> persistence -> configuration) is what keeps persistence a cohesive capability the rest of Melder uses through verbs, not a set of engines callers must wire together.

AGENT_ACCESS: public

AGENT_PURPOSE:: access: public. The persistence facade. Configure and activate it, then use the profile and checkpoint verbs (create_checkpoint, load_checkpoint, describe_profile, list_checkpoint_ids) plus analyze_impact(...). Every emit verb is a NO-OP while inactive.

cleanup() → None[source]

Tear down the crystallizer root and release singleton publication.

Contract:

Returns:: None.

Threading:: Serialized by the instance lock. Singleton publication is reset under the class lock after owned state has been released.
Lifecycle / Cleanup:: Called by the hosting Aether during root teardown. This method does not deactivate and preserve state; use deactivate() for that reversible lifecycle transition.

property id: str

Return the stable crystallizer root id.

Contract:

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

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: Stable root id.
Return type:: str

property configured: bool

Return whether a configuration is installed.

Contract:

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

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: True when crystallizer has an installed configuration.
Return type:: bool

property is_configured: bool

Alias for the configured-state flag.

Contract:

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

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

property activated: bool

Return whether the crystallizer root is active.

Contract:

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

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: True when configuration is installed and activated.
Return type:: bool

property is_activated: bool

Alias for the activated-state flag.

Contract:

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

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: True when the crystallizer root is active.
Return type:: bool

property configuration: CrystallizerConfiguration | None

Return the installed configuration, if any.

Contract:

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

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: Installed configuration.
Return type:: Optional[CrystallizerConfiguration]

create_configuration() → CrystallizerConfiguration[source]

Create a fresh crystallizer configuration object.

Contract:

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

Raises:: RuntimeError -- If the object has been cleaned.
Returns:: New mutable config object.
Return type:: CrystallizerConfiguration

create_configuration_builder() → CrystallizerConfigurationBuilder[source]

Create a fresh fluent builder for crystallizer configuration assembly.

Purpose:: Close the last hole in the configuration ladder. Aether and MutationResearch both expose this factory and CrystallizerConfigurationBuilder has always existed and been exported from the package root - the crystallizer just never published a door to it, so callers had to import the builder class themselves while the other two roots handed it over.

Contract:

Threading:: Unsynchronized read of a plain flag; a snapshot only.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The returned builder is the caller's to own; this root does not retain or clean it.

Raises:: RuntimeError -- If the crystallizer has been cleaned.
Returns:: New builder instance.
Return type:: CrystallizerConfigurationBuilder

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

Install one configuration on the crystallizer root.

Contract:

Parameters:

configuration -- Configuration object to install.

Returns:

None.

Raises:

TypeError -- If the supplied object is not a crystallizer configuration.
RuntimeError -- If crystallizer is already active.

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

Activate the crystallizer root using one activated configuration.

Contract:

Parameters:: configuration -- Optional configuration to install before activation.
Returns:: None.
Raises:: RuntimeError -- If no configuration is installed or the configuration has not itself been activated.

deactivate() → None[source]

Deactivate the crystallizer root without dropping configuration.

Contract:: Stops activated-only facade operations and future recording while preserving the installed configuration and all subsystem state. Existing profiles, checkpoints, cache files, and formation files are not deleted.

Returns:: None.

Threading:: Serialized by the instance lock.
Lifecycle / Cleanup:: Reversible through activate(). This is not teardown and does not clean any owned object.

get_spell_crystal(spell_id: str) → SpellCrystal[source]

Return the recorded custody crystal for one spell (active profile).

Purpose:: The runtime custody lookup: loaders (seed/unseed) and MutationResearch fetch a spell's crystal through this facade - the persistence model stays in the depths. Fetch fresh per use; the record cleans displaced crystals on re-emission, so long-lived references go stale by design.

Contract:

Parameters:

spell_id -- The spell's SHA256 identity.

Returns:

The currently recorded crystal for the spell.

Return type:

SpellCrystal

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If the active profile records no crystal for spell_id.

describe_mutation_research_record() → dict[str, object] | None[source]

Return the recorded MutationResearch twin payload (active profile).

Purpose:: The MR hydration read facade: at activation the MR root pulls the recorded composition to rebuild its research registry from the record. Detached dict only - the persistence model stays in the depths.

Contract:

Returns:: The recorded twin's describe() payload (carrying configuration_payload and composition_payload), or None when the active profile has never recorded the MR twin.
Return type:: Optional[Dict[str, object]]
Raises:: RuntimeError -- If crystallizer is cleaned or not yet active.

analyze_impact(module_name: str | None = None, spell_id: str | None = None) → dict[str, object][source]

Answer blast-radius questions over the recorded custody surface.

Purpose:: The S3 impact facade: "which spells does this module reach?", "what does changing this spell touch?", or - with no arguments - the full source-drift report ("what will my uncommitted edits break?"). Read-only over the record; the live runtime is never inspected.

Contract:

Parameters:

module_name -- Optional canonical module name at the blast center.
spell_id -- Optional spell SHA256 custody identity.

Returns:

The detached impact view.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
ValueError -- If both module_name and spell_id are supplied.

capture_index_graft(index_id: str) → dict[str, object][source]

Capture one spell_index's graft record from the active profile.

Purpose:: The graft lane's capture half (owner ruling: the graft unit is the INDEX - all members, custody, selection). The record is a versioned, JSON-safe dict; store it wherever you like (mesh handlers, formations, plain files) and hand it to graft_index against any live conjured book.

Contract:

Parameters:

index_id -- The recorded index identity.

Returns:

The versioned graft record.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If no index twin is recorded under index_id.

graft_index(graft_record: dict[str, object], host_spellbook: Any, skip_resident: bool = False, merge_into_index: Any | None = None, adopt_recorded_selection: bool = False) → dict[str, object][source]

Re-integrate one captured index into a LIVE host book.

Purpose:: The graft lane's restore half: the selected member binds ACTIVE (bind creates the fresh index and selects it), parked members ride bind_inactive onto it - normal verbs only, existing indexes never mutated. Blast-radius due diligence is one call away: analyze_impact BEFORE grafting into a world you care about.

Contract:

Parameters:

graft_record -- The versioned record from capture_index_graft.
host_spellbook -- The live, CONJURED book receiving the graft (live-object facade per the create_spell_crystal precedent).
skip_resident -- True skips members already resident in the host frame (shortfall each); False refuses the whole graft on the first resident member (default - the conservative overlap rule).
merge_into_index -- MERGE MODE (slice 3, 2026-07-11): a LIVE SpellIndex in the host frame; members park onto IT via the public bind_inactive verb instead of minting a fresh index. Fresh-index-only remains the default.
adopt_recorded_selection -- Merge-mode only: notch the record's selected member active on the target after grafting (public notch verb; honest shortfall when the selection did not graft).

Returns:

The runner's detached report ({status, recorded/live index ids, merged_into_existing, selection_adopted, members_bound, members_parked, skipped_resident, shortfalls}).

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned/not active, the host is unconjured, or a resident member is met without skip_resident.
ValueError -- If the record is not a spell_index graft, was written by a newer record major, or its selected member cannot anchor.

emit_spell_crystal(crystal: SpellCrystal, active: bool = True) → None[source]

Record one custody crystal into the active profile's locations.

Purpose:: The bind-seam emission verb: active binds record active; staged (bind_inactive) binds record inactive - mirroring the spellbook's own active/parked split.

Contract:

Parameters:

crystal -- The custody crystal to record.
active -- Which record location receives it (default active).

Returns:

None.

Raises:

RuntimeError -- If the crystallizer has been cleaned.

emit_spell_removed(spell_id: str) → None[source]

Evict one removed spell's custody from the record.

Purpose:: Called by the spellbook's true-removal seam (cleanup_and_remove_spell). Custody leaves both record locations so restore never rebuilds a shed spell. The module world is NOT touched here: the spell's own cleanup path owns its teardown.

Contract:

Parameters:: spell_id -- The removed spell's SHA256 identity.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

emit_spellbook_removed(spellbook_id: str) → None[source]

Evict one dead spellbook's ENTIRE record subtree.

Purpose:: Called by Spellbook._cleanup_components at true book death (root-conduit teardown and direct cleanup both land there). The book twin, its conduit twin(s), and all its spell custody leave the record so restore never rebuilds a dead book's world. Lesser conduits share the root's book and never trigger this.

Contract:

Parameters:: spellbook_id -- The dead spellbook's identity.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

create_contract_crystal(contract: Contract) → ContractCrystal[source]

Build one relationship twin from a live ward Contract.

Purpose:: Project the contract's full truth - both conduit endpoints and both sides' spell Details and lineage subscriptions - into detached plain data. Callers emit the result so replace-on-emit keeps exactly one snapshot per contract.

Contract:

Parameters:: contract -- The live Contract to snapshot.
Returns:: Detached relationship snapshot.
Return type:: ContractCrystal
Raises:: RuntimeError -- If the crystallizer has been cleaned or is not activated.

emit_cluster_removed(cluster_id: str) → None[source]

Evict one deleted cluster's twin from the record.

Contract:

Parameters:: cluster_id -- The deleted cluster's record-local ULID key.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

emit_contract_removed(contract_id: str) → None[source]

Evict one severed contract's relationship twin from the record.

Contract:

Parameters:: contract_id -- The severed contract's record-local ULID key.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

create_spell_index_crystal(spell_index: SpellIndex, spellbook_id: str) → SpellIndexCrystal[source]

Build one membership twin from a live SpellIndex.

Purpose:: Snapshot the index's grouping truth (owner edge, selection, full member set) for the record; callers emit the result so replace-on-emit keeps exactly one snapshot per index.

Contract:

Parameters:

spell_index -- The live index to snapshot.
spellbook_id -- The owning spellbook's identity.

Returns:

Detached membership snapshot.

Return type:

SpellIndexCrystal

Raises:

RuntimeError -- If the crystallizer has been cleaned or is not activated.

emit_spell_index_removed(index_id: str) → None[source]

Evict one destroyed index's membership twin from the record.

Contract:

Parameters:: index_id -- The destroyed index's record-local ULID key.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

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

Evict one dead frame's twin (+ leftover book subtrees).

Purpose:: Called by AethericFrame.cleanup after its teardown cascade: the frame genuinely leaves the live world (Aether detaches it), so its twin leaves the record. Books normally evicted themselves during the cascade; the profile's by-frame net covers the rest.

Contract:

Parameters:: frame_name -- The dead frame's canonical name.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

emit_nexus_state(state: RecordedUnitState) → None[source]

Record a Nexus lifecycle flip (enabled / disabled / cleaned).

Purpose:: Nexus disable keeps its installed configuration, so the twin is RETAINED and this switch carries the truth (owner model: state-switch, not eviction, for MR/Nexus; Aether/Crystallizer are skipped - the record dies with them).

Contract:

Parameters:: state -- The new recorded state.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

emit_mutation_research_state(state: RecordedUnitState) → None[source]

Record a MutationResearch lifecycle flip (enabled/disabled/cleaned).

Contract:

Parameters:: state -- The new recorded state.
Returns:: None.
Raises:: RuntimeError -- If the crystallizer has been cleaned.

emit_spell_activity(spell_id: str, active: bool) → None[source]

Mirror one runtime park/promote flip into the record and, when configured, into the live module world.

Purpose:

Called by the spellbook's park/promote seams. The record flip is unconditional (crystal moves between active/inactive locations). The module-world reaction is knob-gated:

promote (active=True): the spell's synthetic root module is re-published if it is registered (self-healing; a no-op when it never left sys.modules).
park (active=False): when remove_inactive_synthmodules is True, the synthetic root module is UNPUBLISHED (depth-2: reversible; registry + custody retained; captured references survive as ghosts per the hot-swap law).

Physical-authority spells never touch the module world here.

Contract:

Parameters:

spell_id -- The spell whose activity flipped.
active -- True = promoted to active; False = parked inactive.

Returns:

None.

Raises:

RuntimeError -- If the crystallizer has been cleaned.

emit(twin: Cleanable) → None[source]

Record one emitted twin into the active persistence profile.

Purpose:: The single sink entry of the EMIT model: structural units push their twins here at configuration lock-in and at the pivotal runtime points; the crystallizer passively records into the ACTIVE profile. The sink never reaches into emitters.

Contract:

Parameters:

twin -- One twin from the persistence crystal family.

Returns:

None.

Raises:

RuntimeError -- If the crystallizer has been cleaned.
TypeError -- If the twin type is unsupported (raised by the profile).

create_spell_crystal(spell: Spell, spellbook_id: str | None = None) → SpellCrystal[source]

Build one SpellCrystal using the installed crystallizer policy.

Purpose:: Capture one live spell's bind identity and module-world analysis into the carrier used by persistence and restore.
Contract:: SpellCrystal invokes a single-use CrystalAnalyzer, retains only its value-only CrystalAnalysisResult, and never owns the analyzer or strategy machinery. User-source text is retained only when the installed policy enables it; bind-time fingerprints are recorded independently of that opt-in.

Parameters:

spell -- Live spell whose module world should be crystallized.
spellbook_id -- Optional owning-spellbook identity recorded on the crystal as its parent edge inside a persistence profile.

Returns:

Loader-facing manifest for the given spell.

Return type:

SpellCrystal

Raises:

RuntimeError -- If crystallizer is not yet active.

property active_profile_name: str

Return the name of the persistence profile emissions currently target.

Contract:

Returns:: Active profile name ("default" unless switched).
Return type:: str
Raises:: RuntimeError -- If crystallizer is cleaned or not yet active.

create_profile(profile_name: str, activate: bool = True) → None[source]

Create one new persistence profile and (by default) switch to it.

Purpose:: Facade over the buried persistence model: users and agents create worlds by name only; PersistenceProfile objects never escape the depths.

Contract:

Parameters:

profile_name -- New profile name; must not collide with an existing profile.
activate -- When True (default), the new profile becomes the emission target immediately (owner model: create and default to it).

Returns:

None.

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
ValueError -- If profile_name is empty or already exists.

set_active_profile(profile_name: str) → None[source]

Switch the emission target to one existing persistence profile.

Contract:

Parameters:

profile_name -- Name of an existing profile to activate.

Returns:

None.

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If no profile exists under profile_name.

describe_profile(profile_name: str | None = None) → dict[str, object][source]

Return a detached structural summary of one persistence profile.

Contract:

Parameters:

profile_name -- Profile to describe; None means the active profile.

Returns:

Profile summary (name, per-level twin counts, emission sequence).

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If profile_name names no existing profile.

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

Return the names of all persistence profiles.

Contract:

Returns:: Sorted, detached profile-name list.
Return type:: List[str]
Raises:: RuntimeError -- If crystallizer is cleaned or not yet active.

clear_profile(profile_name: str) → None[source]

Reset one persistence profile's recorded content to empty.

Purpose:: The generalized clear_bootstrap: clearing "default" resets the default bootstrap record.

Contract:

Parameters:

profile_name -- Name of an existing profile to clear.

Returns:

None.

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If no profile exists under profile_name.

delete_profile(profile_name: str) → None[source]

Delete one NAMED persistence profile ("default" is never deletable).

Contract:

Parameters:

profile_name -- Name of the named profile to delete.

Returns:

None.

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
ValueError -- If asked to delete the default profile.
KeyError -- If no profile exists under profile_name.

create_checkpoint(profile_name: str | None = None, description: str | None = None) → str[source]

Snapshot one persistence profile and return the checkpoint's ULID id.

Contract:

Parameters:

profile_name -- Profile to checkpoint; None means the active profile.
description -- Optional caller note stored on the checkpoint record.

Returns:

The new checkpoint's ULID id.

Return type:

str

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If profile_name names no existing profile.

describe_checkpoint(checkpoint_id: str) → dict[str, object][source]

Return a detached copy of one checkpoint's metadata record.

Contract:

Parameters:

checkpoint_id -- ULID identity returned by create_checkpoint.

Returns:

Detached checkpoint record.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If no checkpoint exists under checkpoint_id.

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

Return all checkpoint ids in exact ledger creation order.

Contract:

Returns:: Chronologically sorted, detached checkpoint-id list.
Return type:: List[str]
Raises:: RuntimeError -- If crystallizer is cleaned or not yet active.

describe_record() → dict[str, object][source]

Return the whole record's one-shot operational summary (profiles + twin counts + ledger + cache, in one call).

Contract:

Returns:: The persistence system's describe() payload, enriched with the asset system's cached checkpoint count (disk truth moved custody in S3; the facade payload stays complete).
Return type:: Dict[str, object]
Raises:: RuntimeError -- If the crystallizer has been cleaned or is not activated.

checkpoint_replay_data(checkpoint_id: str) → dict[str, object][source]

Return one checkpoint's detached replay inputs (journal window + captured payloads) - the restore engine's read surface.

Contract:

Parameters:

checkpoint_id -- ULID identity returned by create_checkpoint.

Returns:

{"journal": [[sequence, kind, key], ...],: "payloads": {kind: {key: payload}}}.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If the crystallizer has been cleaned or is not activated.
KeyError -- If no checkpoint exists under checkpoint_id.

flush_checkpoint(checkpoint_id: str | None = None) → list[str][source]

Flush sealed checkpoint(s) into the local crystallizer cache.

Contract:

Parameters:

checkpoint_id -- One ledger ULID, or None to flush the whole ledger.

Returns:

The flushed checkpoint ids.

Return type:

List[str]

Raises:

RuntimeError -- If the crystallizer has been cleaned or is not activated.
KeyError -- If checkpoint_id names no ledger crystal.

reload_cached_checkpoint(checkpoint_id: str) → dict[str, object][source]

Reload one cached checkpoint back into the ledger (history recovery; world restore remains load_checkpoint).

Contract:

Parameters:

checkpoint_id -- ULID of a previously flushed checkpoint.

Returns:

The (re)loaded checkpoint's describe() summary.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If the crystallizer has been cleaned or is not activated.
KeyError -- If no cached item exists for checkpoint_id.

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

Return every checkpoint id present in the local cache.

Contract:

Returns:: Sorted cached checkpoint ids.
Return type:: List[str]
Raises:: RuntimeError -- If the crystallizer has been cleaned or is not activated.

verify_checkpoint_chain(profile_name: str | None = None) → dict[str, object][source]

Report one profile's checkpoint-chain fold-safety (read-only).

Purpose:: Answer BEFORE a restore whether the retained chain is safe to fold: "intact", "truncated_prefix" (head history dropped), or "broken" (number/window damage with evidence rows).

Contract:

Parameters:

profile_name -- Profile to audit; None means the active profile.

Returns:

The detached chain-integrity report.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If profile_name names no existing profile.

reload_profile_from_cache(profile_name: str) → dict[str, object][source]

Reload EVERY cached checkpoint of one profile into the ledger.

Purpose:: Facade over PersistenceSystem.reload_profile_from_cache: a profile's cache folder IS its portable form - copy the folder, reload it here, then load_checkpoint unfolds the chain.

Contract:

Parameters:

profile_name -- Profile whose cached checkpoints should reload.

Returns:

{"profile_name", "inserted", "skipped_existing"}.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If the profile has no cached checkpoints.

save_formation(formation_name: str, conduit_id: str | None = None, frame_name: str | None = None, profile_name: str | None = None, description: str = '') → str[source]

Capture and store one user-named formation.

Purpose:: Facade over PersistenceSystem.save_formation: keep a conduit formation you like (its spellbook rides along) or a whole frame subtree, under your own name, durable in the cache.

Contract:

Parameters:

formation_name -- The user's filesystem-safe name.
conduit_id -- Conduit-scope anchor (exactly one scope required).
frame_name -- Frame-scope anchor.
profile_name -- Profile to capture from; None means the active profile.
description -- Optional user note.

Returns:

Absolute path of the stored formation file.

Return type:

str

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
ValueError/KeyError -- Per the system verb's contract.

restore_formation(formation_name: str, profile_name: str | None = None, target_frame_name: str | None = None, skip_existing: bool = False) → dict[str, object][source]

Rebuild one stored formation directly (scoped restore).

Purpose:: Facade over PersistenceSystem.restore_formation: reload JUST the formation - not the world - with the engine's normal all-or-nothing and shortfall semantics. S1 load-scope maturity: formations COMPOSE into live worlds - optionally retargeted onto another frame, optionally skipping host name collisions instead of refusing on them.

Contract:

Parameters:

formation_name -- The stored formation's name.
profile_name -- Profile whose formation store is read; None = active.
target_frame_name -- Optional frame the formation should compose into instead of its recorded frame (the rewrite happens in the detached window; the stored record is never mutated).
skip_existing -- When True, host name-collision blockers downgrade to "skipped_existing" in the admission view and the engine runs its skip lanes (a taken conduit name builds unnamed with a shortfall; an existing cluster is reused and recorded members join it).

Returns:

The detached restore report (+ "admission": view carrying the additive "host" findings key).

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active, admission refused the load (host-collision or preflight blockers), or the replay failed (torn down; cause chained).
KeyError -- If the formation does not exist.
ValueError -- If a retarget hits a multi-frame window or an invalid target name.

list_formations(profile_name: str | None = None) → list[str][source]

Return the targeted profile's stored formation names.

Contract:

Parameters:: profile_name -- Profile to list; None means the active profile.
Returns:: Sorted formation names.
Return type:: List[str]
Raises:: RuntimeError -- If crystallizer is cleaned or not yet active.

analyze_formation(formation_name: str, profile_name: str | None = None) → dict[str, object][source]

Pre-flight one stored formation's bootload viability.

Purpose:: Run the complete default PersistenceAnalyzer strategy set over the stored formation before the user trusts a restore. The set covers topology, hydration, configuration, frame/cluster posture, synthetic and retained-source integrity, mutation-research composition, and live source drift.
Contract:: Analysis is read-only over the stored payload bundle. It does not execute admission, claim the LoadGate, or replay any runtime unit.

Parameters:

formation_name -- The stored formation's name.
profile_name -- Profile whose formation store is read; None = active.

Returns:

{"findings", "counts", "verdict"} analyzer report.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If the formation does not exist.

analyze_checkpoint(checkpoint_id: str) → dict[str, object][source]

Pre-flight one sealed checkpoint's bootload viability.

Purpose:: Run the complete default PersistenceAnalyzer strategy set over this checkpoint's captured window.
Contract:: This method analyzes the named checkpoint window only; it does not fold the target's complete profile chain and does not replay any runtime unit. load_checkpoint() owns chain detachment, folded preflight, blocker refusal, and execution.

Parameters:

checkpoint_id -- One ledger checkpoint's ULID.

Returns:

{"findings", "counts", "verdict"} analyzer report.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active.
KeyError -- If no checkpoint exists under the id.

configure_external_persistence_manager(manager_configuration: ExternalPersistenceManagerConfiguration) → None[source]

Attach an external transport at the configuration step.

Purpose:: Attach optional durability beyond the built-in local cache. An integration may register generic mesh callables or use a provider such as SqliteMeshAdapter; this verb builds the asset-owned manager while credentials, connection policy, and remote-store operation remain application responsibilities.
Guidance:: Prefer the generic store/fetch/list/delete handlers for new code because they carry checkpoints, formations, grafts, and emission events. The legacy upload/download/list trio remains supported for checkpoint-only integrations.

Contract:

Parameters:

manager_configuration -- The handler-bearing configuration (ownership transfers to the built manager).

Returns:

None.

Raises:

RuntimeError -- If the crystallizer has been cleaned.
TypeError/ValueError -- Propagated from the manager's construction contract.

describe_external_persistence_manager() → dict[str, object][source]

Return the attached manager's record-safe presence description.

Contract:

Returns:: Presence flags + knobs + failure diagnostics; an {"attached": False} stub when no manager is configured.
Return type:: Dict[str, object]
Raises:: RuntimeError -- If the crystallizer has been cleaned.

reload_profile_from_external(profile_name: str) → dict[str, object][source]

Download and insert EVERY remote checkpoint of one profile.

Purpose:: The remote import lane: the manager downloads the profile's stored cached items (list + per-id download through the user's callables) and the persistence system inserts them insert-if-absent - then load_checkpoint unfolds as usual.

Contract:

Parameters:

profile_name -- Profile whose remote history should reload.

Returns:

{"profile_name", "inserted", "skipped_existing"}.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If cleaned, not yet active, no manager is attached, or download/list handlers are missing.
ValueError -- If the remote lists an id it cannot return.

reload_formations_from_external(profile_name: str | None = None) → dict[str, object][source]

Download and store EVERY remote formation of one profile.

Purpose:: The formation half of the remote import lane (external_mesh 2026-07-12): the manager lists + fetches through the user's generic callables, the local formation store inserts-if- absent, and restore_formation reads them as usual afterwards.

Contract:

Parameters:

profile_name -- Profile whose remote formations reload; None = active.

Returns:

{"profile_name", "inserted", "skipped_existing"}.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If cleaned, not yet active, no manager is attached, or the generic fetch/list lanes are missing.
ValueError -- If the remote lists a formation it cannot return.

apply_external_retention(profile_name: str | None = None, max_checkpoints: int | None = None) → list[str][source]

Trim the remote checkpoint history to one retention cap.

Purpose:: Melder-driven remote retention (owner ruling 2026-07-12, opt-in via the delete handler): mirrors the local FIFO - the newest max_checkpoints survive, everything older deletes through the user's callable.

Contract:

Parameters:

profile_name -- Profile to trim; None = active.
max_checkpoints -- Survivor cap; None = the crystallizer configuration's max_persistence_crystals (the same knob the local FIFO honors).

Returns:

The deleted checkpoint ids, oldest first.

Return type:

List[str]

Raises:

RuntimeError -- If cleaned, not yet active, no manager is attached, or the list-units/delete lanes are missing.
ValueError -- If the resolved cap is not a positive int.

delete_cached_checkpoint(checkpoint_id: str) → str[source]

Evict one checkpoint cached-item from the local cache by id.

Purpose:: Facade of the asset system's single-item delete (asset CRUD completion, 2026-07-11): the FIFO cap trims by age; this removes one specific cached snapshot.

Contract:

Parameters:

checkpoint_id -- ULID identity of a previously flushed checkpoint.

Returns:

The deleted file's path.

Return type:

str

Raises:

RuntimeError -- If cleaned or not yet active.
KeyError -- If no cached item exists for checkpoint_id.

delete_formation(formation_name: str, profile_name: str | None = None, include_remote: bool = False) → dict[str, object][source]

Delete one stored formation locally and, optionally, remotely.

Contract:

Parameters:

formation_name -- The user-chosen formation name to delete.
profile_name -- Owning profile; None = the active profile.
include_remote -- When True, also delete the remote copy (STRICT leg via the user's delete handler).

Returns:

{"deleted_local_path", "remote_deleted"}.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If cleaned, not active, or include_remote is set without a manager/delete lane.
KeyError -- If the local formation file does not exist.

store_index_graft_external(graft_record: dict[str, object], profile_name: str | None = None) → str[source]

Ship one captured spell-index graft through the generic mesh.

Purpose:: First-class graft lane (asset CRUD completion): the record ships under kind "index_graft" keyed by its own index_id, so capture -> store -> fetch -> graft_index round-trips without the user naming a kind.

Contract:

Parameters:

graft_record -- The dict from capture_index_graft(...), unmodified.
profile_name -- Recording profile; None = the active profile.

Returns:

The unit id the record shipped under (its index_id).

Return type:

str

Raises:

RuntimeError -- If cleaned, not active, or no store lane.
ValueError -- If the record carries no "index_id".

fetch_index_graft_external(index_id: str) → dict[str, object][source]

Fetch one graft record back from the user's store, version-gated.

Contract:

Parameters:

index_id -- The captured index id the graft shipped under.

Returns:

The graft record, ready for graft_index.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If cleaned, not active, or no fetch lane.
ValueError -- If the record's version MAJOR is newer than this melder reads (the reader-gate law).
KeyError -- If the remote store has no such graft.

list_index_grafts_external(profile_name: str | None = None) → list[str][source]

List one profile's stored graft ids through the generic lane.

Contract:

Parameters:: profile_name -- Profile to list; None = the active profile.
Returns:: Unit ids (captured index ids) the store reports.
Return type:: List[str]
Raises:: RuntimeError -- If cleaned, not active, or no list lane.

describe_external_interface() → dict[str, object][source]

Emit the mesh interface contract joined with live presence.

Purpose:: The owner's "emit the table and the shape" verb: the static kind/shape/signature table (MeshInterfaceContract) plus this world's live handler presence, so users build storage and register callables from the emitted contract alone.

Contract:

Returns:: The stamped contract dict plus "live_manager" (the attached manager's presence flags, or None when nothing is attached).
Return type:: Dict[str, object]
Raises:: RuntimeError -- If cleaned or not yet active.

load_checkpoint(checkpoint_id: str) → dict[str, object][source]

Unfold one checkpoint's world into the live runtime (boot verb).

Purpose:: Public seat of the restore engine: folds the target's profile chain and replays it through the public runtime verbs in canon order (all-or-nothing; shortfalls reported, never silently under-built).
Contract:: The owned loader builds a world-scoped LoadPlan, claims Aether's load authority for the replay span, refuses blocker verdicts before activation, and always releases authority. Successful payloads include the additive, detached admission view alongside the restore report.

Parameters:

checkpoint_id -- ULID identity of the checkpoint to load.

Returns:

The detached RestoreReport payload (status, built counts, shortfall entries, identity translation map).

Return type:

Dict[str, object]

Raises:

RuntimeError -- If crystallizer is cleaned or not yet active, or a replay stage failed (after teardown; original error chained).
KeyError -- If no checkpoint exists under checkpoint_id.

Topic reference · Full contents