Recovery API — Vega SDK Reference

Import

python

from vega_capability_sdk import (
    ExecutionSafetyClass,
    ProviderProbeResult,
    ProviderProbeStatus,
    RecoveryCapableProvider,
)

The same names are exported from vega_capability_sdk.recovery andvega_capability_sdk.contracts.

ExecutionSafetyClass

StrEnum that describes an Action's recovery safety.

Term	Meaning
pure	Execution has no external side effects.
idempotent	Repeating execution has the same intended effect.
retry_safe	Retrying is safe under the Provider's stated contract.
status_query_required	Recovery requires an external status query.
non_idempotent	Repeating execution can produce additional effects.
human_confirmation_required	Recovery requires human confirmation.

ProviderProbeStatus

StrEnum values: active, succeeded, failed,cancelled, not_found, unknown, and unavailable.

ProviderProbeResult

python

@dataclass(frozen=True, slots=True)
class ProviderProbeResult:
    status: ProviderProbeStatus
    execution_id: str
    external_ref: str | None = None
    result: Mapping[str, Any] | None = None
    error: Mapping[str, Any] | None = None
    supports_reattach: bool = False
    supports_cancel_after_restart: bool = False
    raw: Mapping[str, Any] = {}

    def to_dict(self) -> dict[str, Any]: ...
    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> ProviderProbeResult: ...

Provider-observed fact about an interrupted execution. execution_id must be non-blank;result, error, and raw are deeply frozen JSON-compatible data.

Term	Meaning
status	Required. Provider-observed ProviderProbeStatus.
execution_id	Required. Execution being probed; must not be blank.
external_ref	Optional. Provider/backend correlation reference.
result	Optional. JSON-compatible successful result facts.
error	Optional. JSON-compatible failure facts.
supports_reattach	Whether this observed operation can be reattached; defaults to False.
supports_cancel_after_restart	Whether it can be cancelled after restart; defaults to False.
raw	Additional observation data; defaults to an empty mapping.

Validation Rules

succeeded cannot include error.
failed cannot include a successful result.
not_found, unknown, and unavailable cannot include result or error.

to_dict() returns enum values as strings and thaws JSON mappings.from_dict() reconstructs the result, defaulting omitted support flags to Falseand omitted raw to an empty mapping. It raises KeyError when required fields are missing, ValueError for unknown status or invalid combinations, and TypeErrorfor non-JSON data.

RecoveryCapableProvider

Runtime-checkable structural protocol for a Provider that can report restart-time facts.

python

class RecoveryCapableProvider(Protocol):
    async def probe_execution(
        self, execution_id: str, external_ref: str | None
    ) -> ProviderProbeResult: ...

    @property
    def supports_status_query(self) -> bool: ...
    @property
    def supports_reattach(self) -> bool: ...
    @property
    def supports_resume(self) -> bool: ...
    @property
    def supports_cancel_after_restart(self) -> bool: ...
    @property
    def execution_safety_class(self) -> ExecutionSafetyClass: ...

probe_execution reports an observation. It does not define an SDK retry, reattachment, or replay mechanism.

Example

python

class RecoverableProvider(BaseCapabilityProvider):
    @property
    def supports_status_query(self) -> bool:
        return True

    @property
    def supports_reattach(self) -> bool:
        return False

    @property
    def supports_resume(self) -> bool:
        return False

    @property
    def supports_cancel_after_restart(self) -> bool:
        return True

    @property
    def execution_safety_class(self) -> ExecutionSafetyClass:
        return ExecutionSafetyClass.STATUS_QUERY_REQUIRED

    async def probe_execution(self, execution_id, external_ref):
        state = await self._backend.status(external_ref)
        return ProviderProbeResult(
            status=ProviderProbeStatus.ACTIVE,
            execution_id=execution_id,
            external_ref=external_ref,
            supports_cancel_after_restart=True,
            raw={"backend_state": state},
        )

A probe should report facts and avoid starting, replaying, or mutating the underlying operation.