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.

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 supported values 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.

Open a compatible checkpoint or create fresh running state.

Parameters:

• path – checkpoint JSON path, expanded and resolved before use.

• workflow – stable workflow identifier stored in and checked against the document.

• signature – a precomputed 64-character signature or JSON-like identity to fingerprint.

• boundary – safe work-unit label stored in and checked against the document.

• resume – read an existing file when true; a false value or absent file creates and atomically writes fresh state.

Raises:

• CheckpointMismatch – if an existing checkpoint has a different version, workflow, signature, or boundary.

• CheckpointError – if existing state cannot be decoded or fresh state cannot be written.

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

Return a collision-resistant artifact path for unit.

Parameters:

• unit – stable work-unit identity to hash into the filename.

• suffix – non-empty filename suffix, with or without its leading period; path separators, NUL, and dot-only values are refused.

Returns:

path below artifact_dir, which is created lazily after validation.

Raises:

ValueError – if suffix is empty or contains path syntax.

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.

Parameters:

meta – final workflow metadata to merge before completion.

Returns:

None after the completed status is durable.

Raises:

CheckpointError – if the checkpoint cannot be written.

flush() → None

Atomically persist the current document.

Returns:

None after replacement succeeds.

Raises:

CheckpointError – if the document cannot be written.

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.

Returns:

None after the completed unit is durable.

Raises:

• CheckpointError – if the checkpoint cannot be written; the in-memory document remains unchanged.

• spacr.cancellation.PipelineCancelled – after successful persistence when the active cancellation token requests a stop.

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

Persist workflow metadata or status without completing a unit.

Parameters:

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

• status – replacement status, or None to retain the current value.

Returns:

None after the update is durable.

Raises:

CheckpointError – if the checkpoint cannot be written; the in-memory document remains unchanged.

property artifact_dir: pathlib.Path

Directory holding large artifacts referenced by the JSON.

property completed: Dict[str, Any]

Detached copy of completed-unit payloads keyed by unit id.

property meta: Dict[str, Any]

Detached copy of workflow-specific state.

property status: str

Current checkpoint status.

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 supported values 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.

Raises:

ValueError – if distinct mapping keys normalize to the same string.