universal_storage_convergence library

Convergence kernel shared by Universal Storage mesh sync and ecsly world sync (ADR 0011).

Dual mode: every replica keeps an incrementally-folded state plus a pending op log. State is a projection; compaction is a deliberate transform.

Sub-star boundary: this package knows nothing about storage namespaces, worlds, actors, or transports. Consumers choose merge strategies from what is exposed here; they never hand-roll ordering, version vectors, or fold rules.

Classes

CompositeMergeStrategy

Composes several fold semantics into one strategy via key-prefix dispatch (ADR 0030 §1): the strategy is constructed from an ordered lane map (key prefix → sub-strategy) and folds each op through the lane whose prefix longest-matches the op's payload key.

ConvergenceDoc

Dual-mode convergence document: an incrementally-folded state plus a pending op log used to ship deltas to lagging replicas (ADR 0011 §1).

Hlc

Hybrid logical clock timestamp (ADR 0011 §2).

LwwMapStrategy

Last-writer-wins map strategy: keys are independent LWW registers ordered by Hlc. Sufficient for settings, saves metadata, and structured JSON namespaces (ADR 0011 §2).

MergeStrategy

Fold semantics for one document type (ADR 0011 §2).

OpRecord

One immutable convergence event (ADR 0011 §2).

RgaTextStrategy

Sequence merge strategy (RGA family) for block text — the kernel obligation pulled forward by ADR 0029: streamed agent text must merge causally once a second peer connects.

Snapshot

Snapshot of a document's folded state at a version-vector watermark (ADR 0011 §1). Derived data: never the source of truth while ops for it still exist on any replica.

VersionVector

Per-actor high-water mark of observed HLCs (ADR 0011 §2).

Functions

hlcFromJson(Object? raw) → Hlc

hlcRestoreMonotonic({required Hlc persistedLast, required DateTime now}) → Hlc

Restores a persisted last-issued timestamp so monotonicity survives process restarts (ADR 0011 obligation).

hlcToJson(Hlc hlc) → Map<String, dynamic>

Serializes/derializes HLCs inside JSON payloads.

Exceptions / Errors

CompositeLaneMismatchError

Named error thrown when an op's payload key matches no lane of a CompositeMergeStrategy (ADR 0030 §1). The composite refuses the op loudly instead of silently dropping it — redelivery attempts the fold again, so the op is never lost without a named diagnostic.