On this page

• ExternalPersistenceManagerConfiguration
  • ExternalPersistenceManagerConfiguration
    • ExternalPersistenceManagerConfiguration.cleanup()
    • ExternalPersistenceManagerConfiguration.id
    • ExternalPersistenceManagerConfiguration.frozen
    • ExternalPersistenceManagerConfiguration.upload_handler
    • ExternalPersistenceManagerConfiguration.download_handler
    • ExternalPersistenceManagerConfiguration.list_handler
    • ExternalPersistenceManagerConfiguration.upload_on_flush
    • ExternalPersistenceManagerConfiguration.strict_uploads
    • ExternalPersistenceManagerConfiguration.store_handler
    • ExternalPersistenceManagerConfiguration.fetch_handler
    • ExternalPersistenceManagerConfiguration.list_units_handler
    • ExternalPersistenceManagerConfiguration.delete_handler
    • ExternalPersistenceManagerConfiguration.stream_emissions
    • ExternalPersistenceManagerConfiguration.with_store_handler()
    • ExternalPersistenceManagerConfiguration.with_fetch_handler()
    • ExternalPersistenceManagerConfiguration.with_list_units_handler()
    • ExternalPersistenceManagerConfiguration.with_delete_handler()
    • ExternalPersistenceManagerConfiguration.with_stream_emissions()
    • ExternalPersistenceManagerConfiguration.with_upload_handler()
    • ExternalPersistenceManagerConfiguration.with_download_handler()
    • ExternalPersistenceManagerConfiguration.with_list_handler()
    • ExternalPersistenceManagerConfiguration.with_upload_on_flush()
    • ExternalPersistenceManagerConfiguration.with_strict_uploads()
    • ExternalPersistenceManagerConfiguration.validate()
    • ExternalPersistenceManagerConfiguration.freeze()
    • ExternalPersistenceManagerConfiguration.describe_presence()

ExternalPersistenceManagerConfiguration

Use md.ExternalPersistenceManagerConfiguration from the public package namespace.

Implementation source

class ExternalPersistenceManagerConfiguration

Handler configuration for the optional external persistence mesh.

Purpose:

Connect crystallizer assets to storage chosen by the application. New integrations should normally provide the generic store/fetch/list/delete handlers, which carry checkpoints, formations, grafts, and emission events. The legacy upload/download/list trio remains available for checkpoint-only integrations. Deployments that do not need custom storage code can register the first-party SqliteMeshAdapter handlers.

Guidance:

Callables belong in this separate configuration because executable code cannot be serialized into a world record. Author the handlers, choose failure/streaming posture, then pass the configuration to Crystallizer.configure_external_persistence_manager(...); that facade freezes it if necessary and transfers ownership to the asset system. A read-only configuration must explicitly disable upload-on-flush.

Contract:

• Records expose handler presence flags, never callable objects.

• Authoring is fluent and mutation closes at freeze().

• Generic and legacy checkpoint handlers may coexist; legacy handlers take the checkpoint-specific path while generic handlers carry the rest of the mesh and provide fallback checkpoint transport.

• Storage credentials, connection lifetime, transactions, and handler synchronization remain application responsibilities.

Threading:

An RLock serializes authoring. Frozen instances are effectively immutable, but the eventual handler callables must provide any synchronization required by their storage client.

Lifecycle / Cleanup:

Caller-owned until attached through the crystallizer facade, after which the asset-owned manager owns and eventually cleans it. Cleanup drops callable references but never invokes them or deletes remote data.

Registration:

MELDER KERNEL - guarded (internal manifest). access=public: the user authors it (registering the mesh callables) and hands it to the crystallizer facade; guarding only refuses it as a bind target.

Subsystem Context:

The handler-configuration surface for BYTES AT REST's external mesh: it registers the generic store/fetch/list/delete callables (and the legacy checkpoint trio) that ExternalPersistenceManager transports over. Callables live here - separate from the world record - because executable code cannot be serialized into a record.

System Context:

Crystallizer layer (position 2). Records expose handler PRESENCE flags, never callable objects (callables-first law), so a recorded world stays code-free and portable. The facade freezes this configuration and transfers ownership to the asset system, and a read-only configuration must explicitly disable upload-on-flush.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Registers the mesh callables: with_store_handler / with_fetch_handler / with_list_units_handler / with_delete_handler / with_stream_emissions. Read-only configs must disable upload_on_flush explicitly.

cleanup() → None

Release owned fields and mark the configuration cleaned.

Contract:

• Idempotent and terminal; drops every handler reference, knob, identity field, and the authoring lock.

• Does not call user handlers and does not mutate external storage.

Threading:

Authoring and handler installation must be quiescent before cleanup.

Lifecycle / Cleanup:

Performed by the current owner: caller before attachment or the external manager after ownership transfer.

Returns:

None.

property id: str

Return the stable configuration id.

Contract:

• Identifies THIS CONFIGURATION OBJECT, not the persistence manager it configures. Assigned at construction and stable for its life.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

ULID minted at construction.

Return type:

str

property frozen: bool

Return whether the configuration has been sealed.

Contract:

• True once the configuration has been sealed; frozen means SETTERS ARE REFUSED. It says nothing about whether any handler lane is attached.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True after freeze().

Return type:

bool

property upload_handler: Callable[[...], Any] | None

Return the attached upload callable, if any.

Contract:

• None means THE LANE IS NOT ATTACHED, not that it failed. With it None, no upload is attempted at all.

• Returns the caller-supplied callable BY REFERENCE; the configuration neither wraps nor validates it beyond attachment.

• Handlers are BORROWED - cleaning this configuration does not clean or close them.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The handler or None (lane not attached).

Return type:

Optional[Callable]

property download_handler: Callable[[...], Any] | None

Return the attached download callable, if any.

Contract:

• None means THE LANE IS NOT ATTACHED, not that it failed. With it None, remote download is unavailable and callers fall back to local state.

• Returns the caller-supplied callable BY REFERENCE; the configuration neither wraps nor validates it beyond attachment.

• Handlers are BORROWED - cleaning this configuration does not clean or close them.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The handler or None (lane not attached).

Return type:

Optional[Callable]

property list_handler: Callable[[...], Any] | None

Return the attached list callable, if any.

Contract:

• None means THE LANE IS NOT ATTACHED, not that it failed. With it None, remote listing is unavailable.

• Returns the caller-supplied callable BY REFERENCE; the configuration neither wraps nor validates it beyond attachment.

• Handlers are BORROWED - cleaning this configuration does not clean or close them.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The handler or None (lane not attached).

Return type:

Optional[Callable]

property upload_on_flush: bool

Return whether flushes also upload through the manager.

Contract:

• Controls WHEN uploads happen, not WHETHER they can. With no upload handler attached this flag has no effect.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when the flush path uploads (default).

Return type:

bool

property strict_uploads: bool

Return the upload failure posture.

Contract:

• THE FAILURE POSTURE, and it defaults to LENIENT (False): upload failures are logged and execution continues. That default is deliberate - the local seal/cache lane must never die because a remote is unreachable.

• Setting it True makes upload failures RAISE, which couples local progress to remote availability. Choose it only when a missed upload must be treated as a hard error.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

True when upload failures raise; False when they log and continue (default - the local seal/cache lane must never die on a remote).

Return type:

bool

property store_handler: Callable[[...], Any] | None

Return the generic mesh store callable (None = lane not attached).

Contract:

• None means THE LANE IS NOT ATTACHED, not that it failed. With it None, remote store is unavailable.

• Returns the caller-supplied callable BY REFERENCE; the configuration neither wraps nor validates it beyond attachment.

• Handlers are BORROWED - cleaning this configuration does not clean or close them.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The handler or None.

Return type:

Optional[Callable]

property fetch_handler: Callable[[...], Any] | None

Return the generic mesh fetch callable (None = lane not attached).

Contract:

• None means THE LANE IS NOT ATTACHED, not that it failed. With it None, remote fetch is unavailable.

• Returns the caller-supplied callable BY REFERENCE; the configuration neither wraps nor validates it beyond attachment.

• Handlers are BORROWED - cleaning this configuration does not clean or close them.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The handler or None.

Return type:

Optional[Callable]

property list_units_handler: Callable[[...], Any] | None

Return the generic unit-listing callable (None = not attached).

Contract:

• None means THE LANE IS NOT ATTACHED, not that it failed. With it None, remote unit enumeration is unavailable.

• Returns the caller-supplied callable BY REFERENCE; the configuration neither wraps nor validates it beyond attachment.

• Handlers are BORROWED - cleaning this configuration does not clean or close them.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The handler or None.

Return type:

Optional[Callable]

property delete_handler: Callable[[...], Any] | None

Return the remote delete callable (None = retention not attached).

Contract:

• None means THE LANE IS NOT ATTACHED, not that it failed. With it None, remote deletion is unavailable and nothing is removed remotely.

• Returns the caller-supplied callable BY REFERENCE; the configuration neither wraps nor validates it beyond attachment.

• Handlers are BORROWED - cleaning this configuration does not clean or close them.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The handler or None.

Return type:

Optional[Callable]

property stream_emissions: bool

Return whether every crystallizer emission streams remote.

Contract:

• Selects streaming rather than batched emission. It changes delivery shape only; it does not decide whether emissions occur.

Threading:

Unsynchronized read of a slot fixed at construction.

Lifecycle / Cleanup:

Guarded by check_cleaned(); raises after cleanup rather than returning a stale value.

Raises:

RuntimeError -- If the configuration has been cleaned.

Returns:

The opt-in tap flag, default False.

Return type:

bool

with_store_handler(handler: Callable[[...], Any]) → ExternalPersistenceManagerConfiguration

Attach the generic mesh store callable and return self.

Contract:

• Signature: handler(kind: str, profile_name: str, unit_id: str, payload: Dict[str, object]) -> None. Kinds today: "checkpoint" (via the legacy bridge), "formation", "emission" (the opt-in tap). One callable, one table with a kind column, any DB stack - melder never imports it.

Parameters:

handler -- The user's store callable.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If handler is not callable.

with_fetch_handler(handler: Callable[[...], Any]) → ExternalPersistenceManagerConfiguration

Attach the generic mesh fetch callable and return self.

Contract:

• Signature: handler(kind: str, unit_id: str) -> Optional[Dict[str, object]] (the stored payload, or None when the unit is unknown remotely).

Parameters:

handler -- The user's fetch callable.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If handler is not callable.

with_list_units_handler(handler: Callable[[...], Any]) → ExternalPersistenceManagerConfiguration

Attach the generic unit-listing callable and return self.

Contract:

• Signature: handler(kind: str, profile_name: str) -> Iterable[str] (the stored unit ids of that kind/profile).

Parameters:

handler -- The user's listing callable.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If handler is not callable.

with_delete_handler(handler: Callable[[...], Any]) → ExternalPersistenceManagerConfiguration

Attach the remote delete callable and return self (retention opt-in; the 2026-07-07 "remote retention is the DB owner's business" default stands unless this lane is attached).

Contract:

• Signature: handler(kind: str, unit_id: str) -> None.

Parameters:

handler -- The user's delete callable.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If handler is not callable.

with_stream_emissions(enabled: bool) → ExternalPersistenceManagerConfiguration

Set the opt-in emission tap and return self.

Contract:

• True streams EVERY crystallizer emission through the store handler as a delta row (kind="emission"; lenient+counted - a dying DB never blocks the record). Chatty by nature: one bind can emit several twins; the choice is per-deployment.

Parameters:

enabled -- Whether the tap is on.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

RuntimeError -- If cleaned or already frozen.

with_upload_handler(handler: Callable[[...], Any]) → ExternalPersistenceManagerConfiguration

Attach the upload callable and return self.

Contract:

• Signature: handler(profile_name: str, checkpoint_id: str, cached_item: Dict[str, object]) -> None. The cached item is the JSON-safe to_cached_item form - implement with any DB stack (psycopg, sqlite3, boto3, ...); melder never imports it.

Parameters:

handler -- The user's upload callable.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If handler is not callable.

with_download_handler(handler: Callable[[...], Any]) → ExternalPersistenceManagerConfiguration

Attach the download callable and return self.

Contract:

• Signature: handler(checkpoint_id: str) -> Optional[Dict[str, object]] (the stored cached-item form, or None when the id is unknown remotely).

Parameters:

handler -- The user's download callable.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If handler is not callable.

with_list_handler(handler: Callable[[...], Any]) → ExternalPersistenceManagerConfiguration

Attach the list callable and return self.

Contract:

• Signature: handler(profile_name: str) -> Iterable[str] containing remotely stored checkpoint ids for the profile. The manager returns lexical ULID order; this is timestamp ordered but does not prove exact ordering inside one millisecond.

Parameters:

handler -- The user's list callable.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If handler is not callable.

with_upload_on_flush(enabled: bool) → ExternalPersistenceManagerConfiguration

Set whether flushes also upload, and return self.

Parameters:

enabled -- True routes every flushed item through the upload handler.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If enabled is not a bool.

with_strict_uploads(enabled: bool) → ExternalPersistenceManagerConfiguration

Set the upload failure posture, and return self.

Parameters:

enabled -- True makes write-handler failures raise; False counts the failure and continues (default), preserving local custody.

Returns:

This instance (fluent).

Return type:

ExternalPersistenceManagerConfiguration

Raises:

• RuntimeError -- If cleaned or already frozen.

• TypeError -- If enabled is not a bool.

validate() → bool

Validate the attached handlers and knobs.

Returns:

True when valid.

Return type:

bool

Raises:

ValueError -- If upload_on_flush is enabled with no WRITE lane attached (a knob pointing at nothing is a misconfiguration, not a no-op). Since the generic mesh lane (external_mesh 2026-07-12), the store handler satisfies the flush knob - the legacy bridge ships checkpoints through it. Read-only configurations (fetch/list only) must disable the knob explicitly.

freeze() → None

Validate and seal the configuration.

Purpose:

Close handler authoring before ownership transfers to the live manager. Most callers can let the crystallizer facade invoke this automatically during attachment.

Contract:

• Idempotent when already frozen.

• NO twin emission here: this configuration carries live callables and records as presence flags only through the manager's description surface.

Returns:

None.

Raises:

ValueError -- If validation fails.

describe_presence() → Dict[str, object]

Return the record-safe presence description of this configuration.

Contract:

• Callables appear as PRESENCE FLAGS only (record law); knobs appear as their plain values.

Returns:

Plain-value presence payload.

Return type:

Dict[str, object]

Topic reference · Full contents