# Persistence Foundations

OpenRath persists state across several planes: config and credentials, Session
JSONL, sandbox identities, local memory metadata, and memory commit archives.
v1.3.0 adds common atomic replacement, a root layout manifest, and one GC entry
point without replacing each plane's specialized format.

## Boundaries

| Concern | Mechanism |
| --- | --- |
| Config, credentials, registry JSON | Temp sibling + `os.replace`, with a process-local path lock. |
| Session transcript | Append-only JSONL, trailer/partial markers, and its existing writer lock. |
| Layout compatibility | `.openrath/manifest.json` for config/backend/memory schema versions. |
| Retention | `rath.persistence.gc(...)`, which previews by default. |

Atomic replacement prevents a partial JSON document from becoming the visible
destination. It is not a multi-file transaction, a distributed lock, or a
replacement for database concurrency control.

## Data-root lifecycle

```text
ConfigStore.load -> check root manifest -> merge credentials -> validate config
ConfigStore.save -> split credentials -> atomic writes -> refresh root manifest
gc(dry_run=True) -> enumerate old artifacts across planes -> return GCReport
gc(dry_run=False) -> call plane-specific prune helpers -> trim memory commits
```

The manifest check is tolerant of fresh and legacy roots with no manifest. It
only rejects a layout explicitly written by a newer OpenRath version.

Remote sandbox GC removes registry metadata only. Operational teardown of the
actual remote sandbox remains a backend/service concern.

## Source and tests

| Area | Source | Tests |
| --- | --- | --- |
| Atomic writes | `src/rath/persistence/atomic.py` | `tests/persistence/test_atomic_json.py` |
| Root manifest | `src/rath/persistence/manifest.py` | `tests/persistence/test_manifest.py` |
| GC | `src/rath/persistence/gc.py` | `tests/persistence/test_gc.py` |
| Credential split | `src/rath/config/credentials.py`, `store.py` | `tests/config/test_credentials_split.py` |

[← Developer Notes](index.md)