(pkg-persistence)=
# `rath.persistence`

Cross-plane atomic writes, root layout compatibility, and retention/garbage
collection for OpenRath's `.openrath/` data root.

## Source

| Module | Purpose |
| --- | --- |
| `rath.persistence.atomic` | Atomic text/JSON replacement helpers. |
| `rath.persistence.manifest` | Root layout and plane schema versions. |
| `rath.persistence.gc` | Dry-run-first retention across persisted planes. |

## Atomic writes

```python
from rath.persistence import atomic_write_json, atomic_write_text

atomic_write_text(path, "ready\n")
atomic_write_json(path, {"ready": True}, mode=0o600)
```

The helpers write a temporary sibling and replace the destination with
`os.replace`. A process-local, path-keyed lock serializes writers in the same
process; Windows sharing violations receive bounded retries.

This is not a cross-process transaction and does not replace the append/FileLock
protocol used by Session JSONL persistence.

## Root layout manifest

`.openrath/manifest.json` records `layout_version` plus schema versions for the
config, backend, and memory planes. It does not describe Session JSONL.

| API | Behavior |
| --- | --- |
| `ensure_manifest(root)` | Creates or refreshes the current manifest. |
| `check_manifest(root)` | Rejects a layout version newer than this install. Missing legacy manifests are accepted. |
| `LAYOUT_VERSION` | Current overall on-disk layout version. |
| `ManifestVersionError` | Raised for a newer unsupported layout. |

ConfigStore load/save is the automatic wiring point in v1.3.0. Other users of
the data root may call the public helpers explicitly.

```{admonition} Two different manifests
:class: important

`.openrath/manifest.json` is an on-disk compatibility record.
`flow.ResourceManifest` is a compile-time Workflow resource snapshot. They are
unrelated despite sharing the word “manifest.”
```

## Garbage collection

```python
from datetime import timedelta

from rath.persistence import gc

preview = gc(older_than=timedelta(days=30))
deleted = gc(older_than=timedelta(days=30), dry_run=False)
```

`dry_run=True` is the default. `GCReport` contains `sessions`,
`local_sandboxes`, `remote_sandboxes`, `memory_stores`, `memory_commits`, and
`dry_run`.

Deletion is confined to the resolved OpenRath data root. Pruning a remote
sandbox deletes the local registry record; it does not terminate the remote
container.

## Autodoc

```{eval-rst}
.. autofunction:: rath.persistence.atomic_write_text

.. autofunction:: rath.persistence.atomic_write_json

.. autofunction:: rath.persistence.gc

.. autoclass:: rath.persistence.GCReport
   :members:

.. autofunction:: rath.persistence.ensure_manifest

.. autofunction:: rath.persistence.check_manifest

.. autoexception:: rath.persistence.ManifestVersionError
```

[← API Reference](index.md)