A failed report is not an absent effect

The chapter’s hardest distinction is operation reported failed → effect did not happen. Those are two different facts, and a system that collapses them will retry an action that already took effect. The program’s fixture is a worker that appends a line to a file and then loses its connection.

Run it

git clone https://github.com/ernanhughes/codeai.git
cd codeai
git checkout c1707f793abbd6042dce7d00b6dde34f2dbf33cc
PYTHONPATH=src python examples/applied_ai/ch22_action_recovery.py

CodeAI has no runtime dependencies, so nothing needs installing. Python 3.11 or later. No model is called and nothing leaves the machine.

Expected outcome

The report says failed, the effect is unknown, and the record says so:

reported status : failed
effect state    : unknown   <- not 'nothing happened'
next operation  : reconcile_effect
retry is unsafe : True
open effects    : ['append-one-line']

A person then reads the target and records what they found. The verdict is appended beside the action’s history, and the original report is not rewritten:

reconciled as   : observed (reconciliation:effect_confirmed)
reported status : failed   <- still what it was
adapter calls   : 1

Why the ordering makes it decidable

The program prints its own reduction of the rule. The ordering is what makes the state decidable: action.execution_started is committed before the adapter runs, so an interruption on either side of the effect leaves a different record.

The ordering is what makes that decidable: action.execution_started is
committed before the adapter runs, so an interruption on either side of the
effect leaves a different record. Reconciliation then adds later evidence
without editing what was written at the time, and "still unknown" stays a
legitimate answer.

And the reconciliation itself — a person reads the target, and the verdict is added without touching what was written:

        # A person reads the target and records what they found. The action's
        # own history is not touched; the verdict is appended beside it.
        lines = target.read_text(encoding="utf-8").splitlines()
        verdict = (
            ReconciliationVerdict.EFFECT_CONFIRMED
            if lines
            else ReconciliationVerdict.NO_EFFECT_CONFIRMED
        )

Mechanism and limitations

Documented: the two dimensions and the ordering rule are in the program’s docstring in examples/applied_ai/ch22_action_recovery.py; the state projection is project_action_state in src/codeai/actions.py, and the runtime’s execution path is Runtime.execute_action in src/codeai/runtime.py.

Observed: the run above. The failed report and the unknown effect were both recorded; the record reported the retry as unsafe and opened the effect for a person; after reconciliation the effect was observed while the reported status stayed failed; and the adapter was called once, so nothing was retried.

Not shown. “Still unknown” stays a legitimate answer, and this run does not show that case — it shows the case where a person read the target. The reconciliation here is a human reading one file, which is a bounded act, not a general recovery mechanism. Deletion is retraction, not erasure, and the durable backend keeps a tombstone. The effect state is a projection over the recorded markers, so an effect that happened entirely outside the observed scope is invisible to it.

Canonical source and the CodeAI action module .