Expand description
§grafeo-loro
Local-first, in-process, dual-store graph database with CRDT consensus (Loro) + execution (Grafeo). Issue #1 compliance: granular feature gates, WASM target support, trait-abstracted runtime, tree-as-graph adapter.
§Feature matrix (issue #1 item 7)
| Feature | Pulls | WASM-safe |
|---|---|---|
bridge | lorosurgeon, parking_lot | yes |
batcher | bridge + tokio (sync, time) | no |
compression | lz4_flex, zstd (C lib) | no* |
tree | bridge | yes |
storage | async-trait | yes |
grafeo | bridge + grafeo (native only) | no |
onnx | grafeo + ort (native only) | no |
webrtc | webrtc-rs (native only) | no |
telemetry | opentelemetry, tracing | yes |
wasm | wasm-bindgen, js-sys, web-sys | required |
parallel | rayon | no |
serde | serde, serde_json | yes |
full | all native features | no |
* compression uses zstd which binds to a C library; do NOT enable
it in WASM builds. Use lz4_flex only via a future compression-lz4
sub-feature, or disable compression entirely in the browser.
§Issue #4: OfflineOpQueue + EpochTracker (WASM-accessible)
Issue #4 factored OfflineOpQueue, LineageEpoch, EpochMismatchError,
and the new standalone EpochTracker out of src/bridge/sync_engine.rs
into src/bridge/queue.rs. The new module is gated only by
feature = "bridge" — no batcher (tokio), no grafeo (native
ONNX/ort), no telemetry (opentelemetry native). Browser consumers on
wasm32-unknown-unknown can name these types directly via
grafeo_loro::OfflineOpQueue / grafeo_loro::EpochTracker.
§bridge queue + epoch tracker sub-API
| Type | Feature gate | Purpose |
|---|---|---|
OfflineOpQueue | bridge | Cap-bounded FIFO of serialized LoroOps |
LineageEpoch | bridge | u64 type alias for the epoch counter |
EpochMismatchError | bridge | Error raised on remote/local epoch drift |
EpochTracker | bridge | Standalone Arc<AtomicU64> epoch store |
§Onde’s recommended feature set
grafeo-loro = { version = "0.4", default-features = false, features = ["bridge", "batcher", "compression", "tree"] }§Minimal WASM smoke test
grafeo-loro = { version = "0.4", default-features = false, features = ["bridge", "tree", "wasm"] }§MSRV
Rust 1.80+ (verified via cargo msrv against the dep tree).
§Issue #3 sub-issue → feature mapping
Issue #3 (“Browser WASM consumers Support”) has 10 sub-issues. Their feature gates are:
| Sub-issue | Topic | Feature gate |
|---|---|---|
| #1 | WASM target compile + binary size | wasm + bridge,tree,compression |
| #2 | Trait-abstracted runtime (Mailbox) | bridge (trait); batcher (Tokio impl) |
| #3 | LoroDoc ownership API | bridge,storage,grafeo,batcher |
| #4 | Merge semantics | (no feature — use doc.import()) |
| #5 | Offline op-queue + lineage epoch | bridge (factored out in issue #4) |
| #6 | FTS + SAB + shadow commits | fts, sab, shadow |
| #7 | Graph invariants (cycle, root) | bridge,tree |
| #8 | Presence (ephemeral overlay) | bridge (always available with bridge) |
| #9 | Storage backend trait | storage |
| #10 | Observability hooks | observability |
§No merge / awareness / persistence feature
If you saw a feature flag named merge, awareness, or persistence
in a downstream consumer’s Cargo.toml, it was invented — grafeo-loro
has never declared these. Enabling them now produces a compile_error!
pointing at the correct alternative:
| Invented name | Correct alternative |
|---|---|
merge | doc.import(other.export(loro::ExportFormat::Snapshot)) |
awareness | presence module (always available with bridge) |
persistence | storage feature (StorageBackend trait + InMemoryStorage) |
§WASM binary size
With the full WASM-safe feature set (bridge,tree,compression,wasm,serde, fts,sab,shadow,observability) and opt-level="z" + lto=true +
codegen-units=1 + strip=true, the raw .wasm (before wasm-opt -Oz)
is approximately 2.26 MB. After wasm-opt -Oz (configured in
[package.metadata.wasm-pack.profile.release]), it shrinks ~15-20%.
For size-constrained consumers (e.g. <1.8 MB budget), drop fts (inverted
index) and shadow (Git DAG shadow commits) first — they together add
~400 KB. The minimal smoke feature set bridge,tree,wasm produces a
~800 KB .wasm after wasm-opt -Oz.
Re-exports§
pub use config::CompressionType;pub use config::SsotMode;pub use error::GrafeoLoroError;pub use error::Result;