Resolve an AMBIGUOUS effect

An AMBIGUOUS effect is one whose executor raised something other than NotExecuted, timed out, or never returned. CTRLRun will not guess, so a person asks the remote and records the answer with ctrlrun resolve. This guide makes one, finds it, resolves it both ways, and shows what the evidence says afterwards. Prerequisites: pip install ctrlrun, an empty directory. The remote is a stand-in that commits and then loses the reply.

Make an ambiguous effect

runnable

schema: ctrlrun.policy/v2

actions:
  stripe.refund:
    effect: "refund:{payment_id}"
    decision: allow
  dns.update_record:
    effect: "dns:{zone}:{name}"
    decision: allow

runnable

import ctrlrun


@ctrlrun.protect("stripe.refund", effect="refund:{payment_id}")
def refund(payment_id: str, amount: int) -> dict:
    raise TimeoutError("no response from api.stripe.com after 30s")  # after the money moved


@ctrlrun.protect("dns.update_record", effect="dns:{zone}:{name}")
def update_record(zone: str, name: str, value: str) -> dict:
    raise ConnectionResetError("connection reset by peer")


with ctrlrun.context(agent="ops-agent"):
    for call in (
        lambda: refund(payment_id="txn_7", amount=50000),
        lambda: update_record(zone="example.com", name="api", value="203.0.113.7"),
    ):
        try:
            call()
        except (TimeoutError, ConnectionResetError) as lost:
            print("the executor saw:", lost)

Find it

runnable

ctrlrun effects --state ambiguous

refund:txn_7          ambiguous  …
dns:example.com:api   ambiguous  …

A retry of either is refused with AmbiguousEffect until the record moves. A worker that died mid-call ends here too, when its lease lapses; nothing sweeps and nothing releases.

Ask the remote, then say what happened

Look in the Stripe dashboard, or query the DNS zone. Then record the answer. Exactly one of the two flags, and only for an effect that is AMBIGUOUS:

runnable

ctrlrun resolve refund:txn_7 --committed
ctrlrun resolve dns:example.com:api --failed
ctrlrun effects

--committed means the remote did it: a retry is now refused as a duplicate. --failed means it provably did not: a retry is now permitted. Neither undoes anything.

Read who resolved it

The resolution is an EFFECT_RESOLVED event carrying resolved_by, and ctrlrun inspect <action_id> shows it in the action’s history:

runnable

ctrlrun inspect "$(ctrlrun receipts --last 2 --json | head -1 | python -c 'import json,sys; print(json.loads(sys.stdin.readline())["action_id"])')"

A retry after a resolution is a new action with its own receipt; it is never attributed to the resolver.

When to reach for a hook instead

If the remote can be asked programmatically, a reconcile hook asks it for you and moves the record the same way, with the same rule that it moves only in the direction the answer points: Reconcile automatically.

If it didn’t work

resolve exits 1 with is not ambiguous: the effect already has a known outcome. A committed effect cannot be moved back to failed, or the other way.
resolve exits 1 with nobody reserved: the key is misspelled, or the effect belongs to another store; check --store-url or $CTRLRUN_STATE.
exactly one of --committed and --failed: pass one flag.

Outcomes and AMBIGUOUS: why there is a third outcome.
Reconcile automatically.
Get started · Why.

Start

Get started

Production

MCP

Concepts

Guides

Cookbook

Compare

FAQ

More

Resolve an AMBIGUOUS effect

When to reach for a hook instead

If it didn’t work

Next

​When to reach for a hook instead

​If it didn’t work

​Next

When to reach for a hook instead

If it didn’t work

Next