protect

Bind a function to an action name: every call becomes a decided, recorded Action.

ctrlrun.protect — function, defined at src/ctrlrun/control.py:4939

from ctrlrun import protect

def protect(name: str, *, effect: str | None = None, resource: str | None = None, wait: bool = False, lease: timedelta | None = None, reconcile: Callable[[str], ReconcileOutcome] | None = None, reconcile_eagerly: bool = False, control: Control | None = None, preconditions: Callable[[Action], Mapping[str, Any]] | None = None, task: str | None = None, hop: str | None = None, scope: Callable[[Action], Mapping[str, Any]] | None = None) -> Callable[[Callable[P, R]], Callable[P, R]]

Bind a function to an action name: every call becomes a decided, recorded Action.

The wrapped function is the executor (SPEC-v0.1 §5.5), and it is invoked with the action’s canonical arguments, never with the caller’s own objects (§2.2).

effect and resource are templates over the call’s arguments (§5.1). Their syntax is checked here, at decoration time, so a typo fails at import rather than mid-agent-run.

lease is how long this action’s reservation is held (§5.3 E3), for work that takes longer than the Control’s default; it overrides that default and nothing else. Expiry means what it always meant: past the lease the effect is AMBIGUOUS, never released.

reconcile asks the remote what happened to an effect whose outcome is unknown (SPEC-v0.2 §2). With reconcile_eagerly, it also runs immediately after this call produces an AMBIGUOUS outcome, rather than only when one blocks a later attempt.

preconditions reads the state an approval depends on, and is Control.execute’s keyword (SPEC-v0.7 §6.2): called with the Action when the approval is requested and again on the presenting pass, before the store call that consumes it, with a refusal where the two fingerprints differ or only one exists. The recheck narrows the window a human’s approval leaves open; it does not close it (§6.7). Not callable is refused here, at decoration time.

Next

• Python API index.
• Get started · Why.