spacr.checkpoint

Atomic, signature-checked checkpoints for long spaCR workflows.

The workflow modules decide what a safe unit is: a field for conversion and image processing, a trial (plus its completed adaptive round) for UMAP, and a job/plate for Batch. This module only supplies the small persistence contract they share:

• checkpoint JSON is written to a temporary sibling and atomically replaced;

• a resume is refused when the workflow signature differs;

• completed units carry JSON payloads and optional NumPy artifacts;

• every write records the boundary and update time, making a checkpoint inspectable without importing the workflow that produced it.

It deliberately imports only the standard library. Mask and Measure consult resume state before loading torch/Cellpose, so checkpoint infrastructure must never make those imports heavier.

Attributes

CHECKPOINT_VERSION

Exceptions

CheckpointError	Base class for a checkpoint that cannot be read or written safely.
CheckpointMismatch	Raised when resume settings/input identity differ from the checkpoint.

Classes

CheckpointStore

One atomic checkpoint document plus optional array artifacts.

Functions

fingerprint(→ str)	Return a SHA-256 digest of deterministic JSON for value.
json_safe(→ Any)	Return value in a deterministic JSON-compatible form.

Module Contents

exception spacr.checkpoint.CheckpointError

Bases: spacr.errors.ConfigurationError

Base class for a checkpoint that cannot be read or written safely.

Initialize self. See help(type(self)) for accurate signature.

exception spacr.checkpoint.CheckpointMismatch

Bases: CheckpointError

Raised when resume settings/input identity differ from the checkpoint.

Initialize self. See help(type(self)) for accurate signature.

class spacr.checkpoint.CheckpointStore(path: os.PathLike | str, *, workflow: str, signature: Any, boundary: str, resume: bool = False)

One atomic checkpoint document plus optional array artifacts.

Parameters:

• path – JSON checkpoint path.

• workflow – stable workflow identifier, e.g. "umap_search".

• signature – digest or JSON-like identity of inputs and material settings. Non-digest values are passed through fingerprint().

• boundary – human-readable unit such as "field" or "trial".

• resume – load compatible state when True; otherwise start a fresh document at the same path.

Raises:

• CheckpointMismatch – when resume is requested for a checkpoint from a different workflow/signature.

• CheckpointError – when the document is corrupt or inaccessible.

artifact_path(unit: str, suffix: str = '.npy') → pathlib.Path

Return a collision-resistant artifact path for unit.

The directory is created lazily. unit itself is not used as a filename; its digest prevents paths/settings from becoming filesystem syntax.

finish(*, meta: Mapping[str, Any] | None = None) → None

Mark the workflow complete while retaining its inspectable state.

flush() → None

Atomically persist the current document.

mark(unit: str, payload: Mapping[str, Any] | None = None, *, meta: Mapping[str, Any] | None = None) → None

Record one completed safe unit and atomically persist it.

Parameters:

• unit – stable unit id.

• payload – JSON-like result metadata for the unit.

• meta – workflow state to merge into the document metadata.

update(*, meta: Mapping[str, Any] | None = None, status: str | None = None) → None

Persist workflow metadata or status without completing a unit.

property artifact_dir: pathlib.Path

Directory holding large artifacts referenced by the JSON.

boundary = ''

property completed: Dict[str, Any]

Copy of completed-unit payloads keyed by unit id.

property meta: Dict[str, Any]

Copy of workflow-specific state.

path

resumed = False

signature = ''

property status: str

Current checkpoint status.

workflow = ''

spacr.checkpoint.fingerprint(value: Any) → str

Return a SHA-256 digest of deterministic JSON for value.

Parameters:

value – settings, input identity, or another JSON-like structure.

Returns:

lowercase hexadecimal SHA-256 digest.

spacr.checkpoint.json_safe(value: Any) → Any

Return value in a deterministic JSON-compatible form.

Paths, sets, tuples, NumPy scalars and other scalar-like objects are normalised without importing NumPy. Unknown objects fall back to their string representation; workflow signatures should still prefer explicit primitives for scientifically meaningful settings.

Parameters:

value – object to normalise.

Returns:

JSON-compatible value with mapping keys sorted as strings.

spacr.checkpoint.CHECKPOINT_VERSION = 1