graphrefly_storage/lib.rs
1//! `GraphReFly` storage tier dispatch + Node-side persistence.
2//!
3//! Implements the G.27 storage tier protocol: tiered N-way storage with
4//! per-tier transactions, debouncing, compaction, and codec
5//! parameterization. Phase 13.6's deferred ACID atomicity tightening
6//! lands here via [`redb`](https://docs.rs/redb), which provides
7//! pure-Rust ACID transactions without a C dependency.
8//!
9//! # Status (M4.D — 2026-05-11)
10//!
11//! - [`wal`] — WAL frame substrate + canonical-JSON SHA-256 checksum
12//! (DS-14-storage Q1 + Q5 locks).
13//! - [`error`] — [`StorageError`] / [`RestoreError`] / [`RestoreResult`].
14//! - [`codec`] — [`Codec`] trait + [`JsonCodec`] (canonical-JSON encoding,
15//! parity with TS `jsonCodec`).
16//! - [`backend`] — [`StorageBackend`] trait + [`MemoryBackend`] +
17//! [`memory_backend`] factory.
18//! - [`tier`] — [`BaseStorageTier`] + typed sub-traits ([`SnapshotStorageTier`],
19//! [`AppendLogStorageTier`], [`KvStorageTier`]).
20//! - [`memory`] — concrete generic structs `SnapshotStorage` / `AppendLogStorage`
21//! / `KvStorage` + factories `memory_snapshot` / `memory_append_log` /
22//! `memory_kv`.
23//! - [`file`] (feature `file`) — [`FileBackend`] + [`file_backend`] factory +
24//! atomic-rename `write` via `tempfile` + percent-encoded filenames
25//! (byte-identical to TS `fileBackend`).
26//! - [`redb`] (feature `redb-store`) — [`RedbBackend`] + [`redb_backend`]
27//! factory + ACID per-write transactions via [`redb::Database`]. Structurally
28//! closes F1 (pending retry-safety at tier level) + F3 (concurrent flush
29//! race).
30//!
31//! - [`graph_integration`] — Graph-level storage integration (M4.E2):
32//! `attach_snapshot_storage`, `restore_snapshot`, snapshot diff engine,
33//! `GraphCheckpointRecord`. Free functions (D170) because `graphrefly-graph`
34//! does not depend on this crate.
35
36#![warn(rust_2018_idioms, unreachable_pub)]
37#![warn(clippy::pedantic)]
38#![allow(clippy::module_name_repetitions, clippy::missing_errors_doc)]
39#![forbid(unsafe_code)]
40
41pub mod backend;
42pub mod codec;
43pub mod error;
44#[cfg(feature = "file")]
45pub mod file;
46pub mod graph_integration;
47pub mod memory;
48#[cfg(feature = "redb-store")]
49pub mod redb;
50pub mod tier;
51pub mod wal;
52
53pub use backend::{memory_backend, MemoryBackend, StorageBackend};
54pub use codec::{Codec, CodecError, JsonCodec};
55pub use error::{PhaseStat, RestoreError, RestoreResult, StorageError};
56#[cfg(feature = "file")]
57pub use file::{
58 file_append_log, file_append_log_default, file_backend, file_kv, file_kv_default,
59 file_snapshot, file_snapshot_default, FileBackend,
60};
61pub use graph_integration::{
62 attach_snapshot_storage, decompose_diff_to_frames, diff_snapshots, restore_snapshot,
63 AttachOptions, AttachTierPair, GraphCheckpointRecord, GraphSnapshotDiff, RestoreOptions,
64 StorageHandle, TornWritePolicy, ValueChange, SNAPSHOT_VERSION,
65};
66pub use memory::{
67 append_log_storage, kv_storage, memory_append_log, memory_kv, memory_snapshot,
68 snapshot_storage, AppendLogStorage, AppendLogStorageOptions, KvStorage, KvStorageOptions,
69 SnapshotStorage, SnapshotStorageOptions,
70};
71#[cfg(feature = "redb-store")]
72pub use redb::{
73 redb_append_log, redb_append_log_default, redb_backend, redb_kv, redb_kv_default,
74 redb_snapshot, redb_snapshot_default, RedbBackend,
75};
76pub use tier::{
77 AppendCursor, AppendLoadResult, AppendLogMode, AppendLogStorageTier, BaseStorageTier,
78 KvStorageTier, LoadEntriesOpts, SnapshotStorageTier,
79};
80pub use wal::{
81 graph_wal_prefix, verify_wal_frame_checksum, wal_frame_checksum, wal_frame_key, ChecksumError,
82 WALFrame, WalTag, REPLAY_ORDER, WAL_FRAME_SEQ_PAD, WAL_KEY_SEGMENT,
83};