Keep the report, the observation and the effect apart

Four workers report the same thing — SUCCEEDED — and the record says four different things, none of them on the worker’s say-so. The chapter’s claim is that “the agent said done” is three questions, not one: what the actor said, what the runtime could read, and what a declared check against a bound target supports.

Run it

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

CodeAI has no runtime dependencies, so nothing needs installing; PYTHONPATH=src is enough. On PowerShell, set it first with $env:PYTHONPATH = "src". Python 3.11 or later. No model is called and nothing leaves the machine.

Expected outcome

The diligent worker and the busy worker both produced the same effect state, and the verification told them apart:

diligent worker : report=succeeded observation=changed     effect=observed next=none
                  verification: PASS
busy worker     : report=succeeded observation=changed     effect=observed next=none
                  verification: FAIL  <- same effect state, different answer

The other two failed differently. Nothing was observed, so the effect is unknown and a person is needed:

idle worker     : report=succeeded observation=unchanged   effect=unknown  next=reconcile_effect
                  open effects awaiting a person: ['a-idle']
unwatched worker: report=succeeded observation=unavailable effect=reported next=none

And the run states the point in one line:

every worker reported SUCCEEDED; the record did not take any of their words for it

The reduction a chapter can print

The program’s own docstring carries the rule the runtime implements:

    before = observe()
    record(execution_started, state_hash_before=before)
    result = adapter.execute(request)
    after  = observe()

    if   before is None or after is None:  effect = REPORTED   # nobody looked
    elif after != before:                  effect = OBSERVED   # something moved
    else:                                  effect = UNKNOWN    # report and reading disagree

OBSERVED is deliberately weaker than it sounds. It means the scope the runtime can see is not what it was; it does not mean the intended change was made. Only a declared check against a bound target separates the diligent worker from the busy one, and that check is what the run reports as PASS and FAIL.

Mechanism and limitations

Documented: the three dimensions — result status, state observation and effect state — and the reduction above are in the program’s own docstring in examples/applied_ai/ch19_effect_observation.py, and the runtime’s own reporting path is src/codeai/runtime.py (Runtime._current_state_hash, Runtime.execute_action).

Observed: the run above. Four workers, one report, four different records. The diligent and busy workers reached the same effect=observed and were separated only by the declared check. The idle worker left an open effect for a person. The unwatched worker had no observation at all, so its effect is reported and nothing was claimed.

Not shown. The check is a declared criterion over one bound target, not a judgement that the work was right: FAIL means the criterion was not met. The effect state is derived from a state hash of the scope the runtime can see, so a change outside that scope is invisible to it, and a change inside it that was not wanted reads the same as one that was. The unwatched case shows the boundary of the instrument rather than a failure of the worker. Nothing here measures whether any of this helped a person.

Canonical source and the CodeAI runtime .