On this page

• CrystallizerBootstrap
  • CrystallizerBootstrap
    • CrystallizerBootstrap.cleanup()
    • CrystallizerBootstrap.with_crystallizer_configuration()
    • CrystallizerBootstrap.with_external_persistence_manager()
    • CrystallizerBootstrap.with_profile()
    • CrystallizerBootstrap.with_pull_remote()
    • CrystallizerBootstrap.with_formation_reload()
    • CrystallizerBootstrap.with_preflight_gate()
    • CrystallizerBootstrap.bootstrap()

CrystallizerBootstrap

Use md.CrystallizerBootstrap from the public package namespace.

Implementation source

class CrystallizerBootstrap

Fluent pod-boot lane: from a fresh process to a rebuilt world.

Purpose:

Compose the restart sequence for a fresh process: activate the crystallizer, attach optional external assets, recover local and remote history, verify the selected profile's chain, and load its newest checkpoint. A process with no history is valid and starts an empty recording world.

Usage:

Choose this object for process/pod restart orchestration. Use direct Crystallizer facade verbs when the process is already configured and only one checkpoint, formation, or graft operation is needed. The builder is single-use because it transfers configuration ownership and may create a live world.

Remote history is written back through the normal flush lane so the local cache is repopulated. Consequently, attached write handlers must tolerate idempotent re-storage of an existing checkpoint id.

Contract:

• Composes ONLY Crystallizer facades (the crystallizer owns its internals; the bootstrap owns the ORDER).

• Single-use: bootstrap() consumes the builder.

• A fresh-ever pod is LEGAL: no history anywhere boots an empty recording world (restored_checkpoint_id None, no error).

• Remote-pulled checkpoints re-flush through the facade so the local cache holds them; remote write handlers may therefore receive the same checkpoint id again and must be upsert-safe.

• The chain verdict GATES the load: "broken" refuses loudly (bootstrapping a wrong world is worse than not booting); "truncated_prefix" boots and rides the report.

Threading:

Builder-thread confined; not shared.

Lifecycle / Cleanup:

Cleanup releases configurations that were never consumed. After bootstrap() begins, configuration ownership transfers downstream and cleanup never tears down the resulting crystallizer world.

Registration:

MELDER KERNEL - guarded (internal manifest). access=public: a deploy/pod constructs and drives it for restart orchestration; guarding only refuses it as a bind target (Melder never injects it) - it is still user-driven.

Subsystem Context:

The pod-restart lane of THE UNFOLD: a single-use fluent builder that composes ONLY Crystallizer facades in order - activate -> attach external assets -> reload local cache -> pull remote history + re-flush -> chain-verify gate -> load newest checkpoint -> report. The crystallizer owns its internals; the bootstrap owns the ORDER.

System Context:

Crystallizer layer (position 2), the entry point for bringing a fresh process back to a recorded world. A fresh-ever pod is LEGAL (no history boots an empty recording world, no error); the chain verdict GATES the load - "broken" refuses loudly because booting a wrong world is worse than not booting, while "truncated_prefix" boots and rides the report.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Fluent single-use pod-boot chain: activate, attach the external manager, reload cache, pull remote, verify the chain, restore the newest checkpoint. Use this to bring a fresh process back to a recorded world in one expression.

cleanup() → None

Release unconsumed configurations and mark the builder cleaned.

Contract:

• Idempotent and terminal; unconsumed configurations clean before builder fields are deleted.

• Configurations consumed by bootstrap() transferred downstream and are not cleaned here.

• Does not deactivate or clean the crystallizer world produced by a successful bootstrap.

Threading:

Must run on the builder thread after fluent/bootstrap activity has stopped.

Lifecycle / Cleanup:

Safe in finally on both successful and failed boot chains; the consumed flag determines whether configuration ownership moved.

Returns:

None.

with_crystallizer_configuration(configuration: CrystallizerConfiguration) → CrystallizerBootstrap

Supply the crystallizer configuration and return self.

Contract:

• Omitting this uses CrystallizerConfiguration().with_defaults() at bootstrap() time. To boot the RECORDED policy, reload it first (CrystallizerConfiguration().load_recorded_dictionary on the head checkpoint's crystallizer payload) and pass it here.

Parameters:

configuration -- The (possibly reloaded) crystallizer configuration; ownership transfers to this builder until consumed.

Returns:

This builder (fluent).

Return type:

CrystallizerBootstrap

Raises:

RuntimeError -- If the builder has been cleaned or consumed.

with_external_persistence_manager(manager_configuration: ExternalPersistenceManagerConfiguration) → CrystallizerBootstrap

Supply an external transport configuration and return self.

Guidance:

Use the generic mesh handlers for complete checkpoint/formation/ graft support. A checkpoint-only legacy handler trio is valid, but remote formation reload is then skipped because that capability is absent.

Parameters:

manager_configuration -- Handler-bearing configuration; ownership transfers to this builder until bootstrap consumes it.

Returns:

This builder (fluent).

Return type:

CrystallizerBootstrap

Raises:

RuntimeError -- If the builder has been cleaned or consumed.

with_profile(profile_name: str) → CrystallizerBootstrap

Pick the profile to rebuild and return self.

Parameters:

profile_name -- Profile whose history boots (default "default").

Returns:

This builder (fluent).

Return type:

CrystallizerBootstrap

Raises:

• RuntimeError -- If the builder has been cleaned or consumed.

• ValueError -- If profile_name is empty.

with_pull_remote(enabled: bool) → CrystallizerBootstrap

Set whether bootstrap pulls remote history, and return self.

Parameters:

enabled -- False skips the remote pull even when a manager is attached (local-cache-only boot).

Returns:

This builder (fluent).

Return type:

CrystallizerBootstrap

Raises:

• RuntimeError -- If the builder has been cleaned or consumed.

• TypeError -- If enabled is not a bool.

with_formation_reload(enabled: bool) → CrystallizerBootstrap

Set whether bootstrap pulls remote FORMATIONS, and return self.

Purpose:

Mesh-aware boot (asset CRUD completion, 2026-07-11): a pod that rebuilds from the user's DB gets its named formation slices back beside the checkpoint history, so the restore-a-slice verbs work immediately after boot.

Contract:

• Runs only when a manager is attached AND its configuration carries the generic fetch + list-units lanes; legacy-only managers (upload/download/list trio) have no formation transport, so the step SKIPS silently (report key None) rather than tripping the generic lanes' loud-refusal.

• Tolerates a mesh with no formations (empty summary).

• Default is True, mirroring with_pull_remote's posture.

Parameters:

enabled -- False skips the formation pull even when a manager is attached.

Returns:

This builder (fluent).

Return type:

CrystallizerBootstrap

Raises:

• RuntimeError -- If the builder has been cleaned or consumed.

• TypeError -- If enabled is not a bool.

with_preflight_gate(enabled: bool) → CrystallizerBootstrap

Accepted no-op knob: blocker refusal is standard admission now.

Purpose:

Preserve compatibility with older fluent chains. Every mediated load now refuses folded blocker verdicts before replay regardless of this value.

Guidance:

Omit this method in new code. It communicates no current policy and exists only so previously authored bootstrap chains remain valid.

Parameters:

enabled -- Accepted and recorded; admission refuses blockers regardless.

Returns:

This builder (fluent).

Return type:

CrystallizerBootstrap

Raises:

• RuntimeError -- If the builder has been cleaned or consumed.

• TypeError -- If enabled is not a bool.

bootstrap() → Dict[str, object]

Run the pod-boot flow and return the bootstrap report.

Contract (the ORDER is the product):

1. Activate the crystallizer (supplied or defaults-lane configuration; the persistence system comes up with it).

2. Attach the external manager when configured.

3. Reload the profile's LOCAL cache (empty tolerated).

4. Pull the profile's REMOTE history when enabled and a manager is attached; re-flush pulled ids so the local cache holds them.

5. Pull the profile's REMOTE formations (mesh-aware boot; default-on when the attached manager carries the generic fetch+list lanes - legacy-only managers skip silently; with_formation_reload(False) also skips) so slice restores work on the rebuilt pod.

6. Verify the chain: "broken" REFUSES loudly; anything else rides the report.

7. Load the profile's most recent checkpoint by exact ledger insertion order; a history-less process boots an empty world (restored_checkpoint_id is None).

Returns:

{"activated": True,

"profile_name": str, "cache_reload": summary | None, "remote_reload": summary | None, "formation_reload": summary | None, "chain_report": report | None, "restored_checkpoint_id": str | None, "restore_report": report | None}.

Return type:

Dict[str, object]

Raises:

• RuntimeError -- If cleaned, already consumed, chain verification is broken, folded admission finds blockers, or replay fails.

• ValueError/TypeError/KeyError -- Propagated from configuration activation, transport setup, or selected profile/history operations.

Topic reference · Full contents