Reviewing a two-file Python recovery protocol after a crash or lost acknowledgement

Илья Ваганов — Mon, 19 Oct 2026 17:16:16 +0000

AI disclosure — Fully Autonomous: this example and this draft were generated primarily by an AI coding
assistant for the repository owner. Validation so far is automated; independent
human review has not yet been received. This is an intentionally small counter
example, not a production persistence library or a complete AI agent.

The question is about a narrow recovery boundary: a write can become visible even
when its caller never receives an acknowledgement. Retrying by restoring the old
state would then lose a committed update. The example uses only generated integer
events, the Python standard library and disposable test directories.

Fixed revision:
https://github.com/DarkVoice087/agent-state-recovery-review/tree/8188f5054d7e8f3fcdefb6995c712dda59b50ec3
Implementation:
https://github.com/DarkVoice087/agent-state-recovery-review/blob/8188f5054d7e8f3fcdefb6995c712dda59b50ec3/state_store.py
Tests:
https://github.com/DarkVoice087/agent-state-recovery-review/blob/8188f5054d7e8f3fcdefb6995c712dda59b50ec3/tests/test_recovery.py

The protocol is:

Replay the journal and validate its checkpoint before preparing a new snapshot.
Acquire cooperative OS locks in trusted-file then bundle-file order.
Persist pending(old_hash, new_hash) in a separately configured trusted directory.
Flush/fsync a temporary bundle and replace the target in the same directory.
Confirm the new hash in the trusted file.
On recovery, accept only the authorized old/new bundle. Unknown data keeps the pending intent open and blocks the next dependent save. Missing trust never self-authorizes an existing bundle.

The useful review target is a counterexample, rather than a general approval:

Can any untested interruption or I/O-error window make recovery accept an unauthorized bundle, discard a visible committed prefix, or clear an unresolved intent? Please include the first write and a lost recovery-confirmation ACK.
Can a stale cooperating writer or the Windows/POSIX lock behavior break the prefix-extension check? What minimal additional negative test would expose it?
Are the documented process-crash guarantees too strong on either OS? Which additional filesystem/OS guarantees would be needed for a power-loss claim?

Nine unittest methods pass, including eight actual child-process crash points,
an independent 200-event prefix check, corrupt/rolled-back state, unknown data,
missing trust, lost acknowledgements, I/O failures and another process's lock.
CI passed on Windows/Ubuntu with Python 3.12/3.13:
https://github.com/DarkVoice087/agent-state-recovery-review/actions/runs/39203969671
Run: python -B -m unittest discover -v

Known limits: no power-loss certification, Windows directory fsync, ACL installer,
adversarial path-race certification, protection against an administrator rolling
back both files, multi-host coordination or exactly-once external side effects.
This is not evidence that custom JSON storage is preferable to SQLite; database
transactions and a separately protected rollback anchor solve different concerns.
The repository is public for review; a reuse license has not been selected.

Please reply with the fixed revision, OS/Python/filesystem if relevant, the failure
sequence, expected versus observed state, and a minimal synthetic reproduction or
test. The repository's review issue template can also be used:
https://github.com/DarkVoice087/agent-state-recovery-review/issues/new/choose
Synthetic inputs only; please do not attach production state or credentials.

DEV Community: Илья Ваганов

Reviewing a two-file Python recovery protocol after a crash or lost acknowledgement