core.checkpointed_effect module

Run an external presentation effect behind a durable tool-slot barrier.

This helper is intentionally independent of any platform adapter. Callers choose a stable checkpoint round/slot and describe the effect with a stable name and arguments. The checkpoint then provides the fenced ownership, lease renewal, exact result replay, and fail-closed ambiguity semantics.

exception core.checkpointed_effect.CheckpointedEffectAmbiguous

Bases: TurnCheckpointError

A prior non-replay-safe effect may have happened; never run it again.

async core.checkpointed_effect.run_checkpointed_effect(checkpoint, *, round_index, slot_index, effect_name, arguments, runner, replay_safe=False)

Run runner once behind a durable, fenced checkpoint slot.

round_index, slot_index, effect_name, and arguments are the stable logical identity supplied by the caller. Reusing a slot with a different name, arguments, or replay policy is rejected by the checkpoint.

A completed replay returns the exact canonical value stored in Redis and does not invoke runner. A busy owner raises TurnCheckpointBusy; an ambiguous effect raises CheckpointedEffectAmbiguous. Runner exceptions and cancellation deliberately leave the slot EXECUTING so recovery can apply the configured replay-safety policy.

Return type:

TypeVar(_T)

Parameters: