Skip to main content

Module tier

graphrefly_storage

Module tier 

Source
Expand description

Tier abstraction layer (Phase 14.6 — DS-14-storage Audit 4 + Q5 + Q8 locks, M4.B 2026-05-10).

Three-layer tier model (matching packages/pure-ts/src/extra/storage/tiers.ts):

  • Layer 1 — StorageBackend: generic bytes-level kv I/O.
  • Layer 2 — tier specializations parametric over T:
  • Layer 3 — high-level wiring (Graph::attach_storage, M4.E integration).

All sub-traits inherit BaseStorageTier, which carries the cadence knobs (debounce_ms, compact_every), transaction lifecycle (flush, rollback), and the dyn-safe bytes-level BaseStorageTier::list_by_prefix_bytes enumeration. Typed enumeration (decoding via the tier’s codec) lives on the typed sub-traits as free functions or default-impl helpers.

§Sync, NOT async (D143)

Every method returns directly (no Future). Memory / redb / std::fs backends are all sync-compatible; tokio-backed networking backends wrap their async surface at the adapter layer (e.g. tokio::Handle::block_on). See crate::backend module doc.

§debounce_ms semantics at M4.B (D144 — option (b))

The accessor BaseStorageTier::debounce_ms returns the configured window. The tier itself does NOT drive a timer. The Graph layer consumes this value at attach time (M4.E) and schedules flush() via its own reactive timer source (from_timer / from_cron). Until then, save always buffers and flush always commits — debounce has no automatic effect.

Traits§

AppendLogStorageTier
Append-log tier — bulk-friendly entry persistence with optional partitioning via key_of. Mirrors TS AppendLogStorageTier<T>.
BaseStorageTier
Common tier surface — cadence knobs + transaction lifecycle + bytes-level enumeration.
KvStorageTier
Key-value tier — typed records under arbitrary string keys with codec serialization at the storage boundary. Mirrors TS KvStorageTier<T>.
SnapshotStorageTier
Snapshot tier — writes a single record per save(snapshot) call. Mirrors TS SnapshotStorageTier<T>.

Type Aliases§

ListByPrefixIter
Boxed lazy iterator yielded by BaseStorageTier::list_by_prefix_bytes. Each item is either a (key, bytes) entry decoded from the backend or a surfaced StorageError (e.g. on first-yield if the backend doesn’t support enumeration — lazy-throw semantics from the TS impl).