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#

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