__init__.py
python
sha256:1c4b3e3a9a1f300774c3ee662b572a698d5fd405bf765a71e6011a2e9c3eaaaa
feat: Muse — version control for the agent era
Human
73 days ago
| 1 | """CRDT primitive library for Muse's convergent multi-agent write semantics. |
| 2 | |
| 3 | This package provides six foundational Conflict-free Replicated Data Types |
| 4 | (CRDTs) that plugin authors can use to give their domains convergent merge |
| 5 | semantics. With CRDTs, ``join`` always succeeds — no conflict state ever |
| 6 | exists — making them ideal for high-throughput multi-agent scenarios where |
| 7 | finding a merge base is expensive or impossible. |
| 8 | |
| 9 | Available primitives |
| 10 | -------------------- |
| 11 | |
| 12 | +------------------+------------------------------------+-------------------------------+ |
| 13 | | Class | Module | Use when… | |
| 14 | +==================+====================================+===============================+ |
| 15 | | :class:`VectorClock` | :mod:`~muse.core.crdts.vclock` | Causal ordering between agents| |
| 16 | +------------------+------------------------------------+-------------------------------+ |
| 17 | | :class:`LWWRegister` | :mod:`~muse.core.crdts.lww_register` | Scalar values; last write wins| |
| 18 | +------------------+------------------------------------+-------------------------------+ |
| 19 | | :class:`ORSet` | :mod:`~muse.core.crdts.or_set` | Unordered sets; adds win | |
| 20 | +------------------+------------------------------------+-------------------------------+ |
| 21 | | :class:`RGA` | :mod:`~muse.core.crdts.rga` | Ordered sequences (collab edit)| |
| 22 | +------------------+------------------------------------+-------------------------------+ |
| 23 | | :class:`AWMap` | :mod:`~muse.core.crdts.aw_map` | Key-value maps; adds win | |
| 24 | +------------------+------------------------------------+-------------------------------+ |
| 25 | | :class:`GCounter`| :mod:`~muse.core.crdts.g_counter` | Monotone counters | |
| 26 | +------------------+------------------------------------+-------------------------------+ |
| 27 | |
| 28 | All primitives satisfy the three CRDT lattice laws: |
| 29 | |
| 30 | 1. **Commutativity**: ``join(a, b) == join(b, a)`` |
| 31 | 2. **Associativity**: ``join(join(a, b), c) == join(a, join(b, c))`` |
| 32 | 3. **Idempotency**: ``join(a, a) == a`` |
| 33 | |
| 34 | These three properties guarantee convergence regardless of message order or |
| 35 | delivery count — any two replicas that have received the same set of writes |
| 36 | (in any order) will produce the same state. |
| 37 | |
| 38 | Choosing the right primitive |
| 39 | ----------------------------- |
| 40 | |
| 41 | - Use :class:`LWWRegister` for scalar config values (tempo, key, metadata). |
| 42 | - Use :class:`ORSet` for unordered sets of objects (annotations, tags). |
| 43 | - Use :class:`RGA` for ordered sequences (note lists, event streams). |
| 44 | - Use :class:`AWMap` for mappings (file manifests, dimension configs). |
| 45 | - Use :class:`GCounter` for monotonically increasing totals (commit counts). |
| 46 | - Use :class:`VectorClock` for causal tracking across all of the above. |
| 47 | |
| 48 | Plugin integration |
| 49 | ------------------ |
| 50 | |
| 51 | Plugins opt into CRDT semantics by implementing the :class:`CRDTPlugin` |
| 52 | protocol declared in :mod:`muse.domain`. The core engine detects the protocol |
| 53 | at merge time and calls :meth:`CRDTPlugin.join` instead of the three-way merge |
| 54 | path. See :mod:`muse.domain` for the full ``CRDTPlugin`` contract. |
| 55 | """ |
| 56 | |
| 57 | from __future__ import annotations |
| 58 | |
| 59 | from muse.core.crdts.aw_map import AWMap, AWMapDict, AWMapEntry |
| 60 | from muse.core.crdts.g_counter import GCounter, GCounterDict |
| 61 | from muse.core.crdts.lww_register import LWWRegister, LWWValue |
| 62 | from muse.core.crdts.or_set import ORSet, ORSetDict, ORSetEntry |
| 63 | from muse.core.crdts.rga import RGA, RGAElement |
| 64 | from muse.core.crdts.vclock import VClockDict, VectorClock |
| 65 | |
| 66 | __all__ = [ |
| 67 | "VectorClock", |
| 68 | "VClockDict", |
| 69 | "LWWRegister", |
| 70 | "LWWValue", |
| 71 | "ORSet", |
| 72 | "ORSetEntry", |
| 73 | "ORSetDict", |
| 74 | "RGA", |
| 75 | "RGAElement", |
| 76 | "AWMap", |
| 77 | "AWMapEntry", |
| 78 | "AWMapDict", |
| 79 | "GCounter", |
| 80 | "GCounterDict", |
| 81 | ] |
File History
1 commit
sha256:1c4b3e3a9a1f300774c3ee662b572a698d5fd405bf765a71e6011a2e9c3eaaaa
feat: Muse — version control for the agent era
Human
73 days ago