# atomic-json-store Public Source Note - 2026-09-06

This source note supports the Greyforge Chronicle "atomic-json-store: Local State That Survives a Crash."

Chronicle URL: https://greyforge.tech/chronicles/atomic-json-store-crash-safe-local-state

OpenForge URL: https://greyforge.tech/open-source

GitHub repository: https://github.com/GreyforgeLabs/atomic-json-store

GitHub release: https://github.com/GreyforgeLabs/atomic-json-store/releases/tag/v1.0.0

## Public Claims

- `atomic-json-store` is a Python library and command-line tool with no dependencies beyond the standard library, for Python 3.11 and newer.
- Writes serialize the document first, write a temporary file in the target directory, fsync it, and publish it with `os.replace`. The directory is fsynced on POSIX.
- Read-modify-write cycles are serialized by an advisory lock on a sidecar file (`flock` on POSIX). Locks are re-entrant per thread and time out.
- Documents carry a `schema_version`. Older files are upgraded through registered migrations; newer files are refused; plain JSON files are treated as version 0.
- Corrupt files raise by default or can be quarantined beside the store.
- New files are created with mode 0600; existing modes are preserved.

## Validation Summary

Before publication, the release path passed:

- Ruff check and format check
- pytest (53 tests, including a six-process locked increment test and a concurrent reader consistency test)
- Package build and Twine check through the tagged release workflow
- OpenForge readiness status with zero scrub findings

## Limits Stated in the Repository

- Atomicity depends on `os.replace` being atomic on the target filesystem; network filesystems vary.
- Locking is advisory. Programs that ignore the lock file can still race.
- Windows locking is exclusive-only and is not covered by CI.
- The whole document is read and written on every operation.

## Privacy Boundary

The private tool that motivated the library is not published and is not needed to evaluate the claims. The repository, its tests, and the v1.0.0 release are sufficient.