Durability and Recovery

The store accepts mutations in memory. Every five seconds it writes one checkpoint containing all document state, deletion parent links, and tombstones to STRATA_DATA_DIR/store.dets. Shelf writes a temporary file, closes it, and atomically renames it over the previous checkpoint.

Crash contract

apply, create, and delete run in one store-owner turn. A successful mutation result means accepted in memory, not persisted. A checkpoint contains all changes through a complete owner turn. It cannot contain a new child without its parent link, or a removed child with the old parent state.

A process crash before checkpoint replacement recovers the previous complete checkpoint. A crash after replacement recovers the new complete checkpoint. Unflushed accepted changes can be lost. A flush that times out has an unknown outcome: it can still finish. Reconnect alone does not prove persistence.

Shelf's rename protects against partial replacement on a process crash. Strata does not promise an fsync-backed host-power-loss guarantee. Filesystem damage, disk loss, and storage that does not support atomic rename are outside this contract. DETS has a 2 GB file limit. A flush serializes the whole store; this can delay other store operations.

store.flush returns persistence errors to the caller. Periodic flush errors are written to stderr and retried on the next interval. A failed flush does not roll back accepted memory state. store.close attempts a final checkpoint and close; on failure it reports the error rather than claiming success.

The top-level server lifecycle is described in Operations.

Upgrade from two files

On first use, the store imports documents.dets and parents.dets together and saves store.dets before serving requests. Both legacy files must exist, or neither. Invalid ORMaps and missing deletion parents stop startup; records are not silently skipped. The import cannot repair a half-written legacy backup. Keep the original backup until the imported data has been inspected.

After the first checkpoint, store.dets is authoritative. Legacy files are not updated. Do not downgrade using them: they are stale.

Backup and restore

1. Stop new writes and wait for in-flight calls to finish.
2. Call store.close and require success before stopping the store owner.
3. Copy the complete data directory after the owner exits.
4. To restore, stop the server and keep its current directory as a backup.
5. Restore the saved directory, then start the server and inspect /admin.

Do not assume that waiting five seconds proves a successful flush. Inspect flush results. Only one store owner can open a data directory.

Tombstones

Each tombstone records a deleted ID and its former deletion parent. The same checkpoint saves subtree removal, parent changes, and tombstones. After a successful flush, restart preserves rejection of stale deltas and creates. An unflushed delete can be lost with the rest of its owner turn.

Tombstones have no expiry or garbage collection. Deleted IDs cannot be reused. Allocate a new ID for a replacement document. A repeat delete must name the recorded deletion parent, including after restart. A repeat delete inside a deleted subtree does not recreate that subtree.

Legacy files and version-1 checkpoints lack deletion history. Import cannot recover IDs deleted before this storage format. Restoring an older backup also restores its older deletion history.

The storage format can change before 1.0. See Compatibility and Upgrades.