gabriel / muse public
__init__.py python
79 lines 3.6 KB
Raw
sha256:e8214e0062ef8ef0af999937df2731655b6082781fc22bc563f58db2f42b1de9 Merge 'bump/muse-v0.2.1' into 'dev' — proposal: chore: bump… Human 17 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 muse.core.crdts.aw_map import AWMap, AWMapDict, AWMapEntry
58 from muse.core.crdts.g_counter import GCounter, GCounterDict
59 from muse.core.crdts.lww_register import LWWRegister, LWWValue
60 from muse.core.crdts.or_set import ORSet, ORSetDict, ORSetEntry
61 from muse.core.crdts.rga import RGA, RGAElement
62 from muse.core.crdts.vclock import VClockDict, VectorClock
63
64 __all__ = [
65 "VectorClock",
66 "VClockDict",
67 "LWWRegister",
68 "LWWValue",
69 "ORSet",
70 "ORSetEntry",
71 "ORSetDict",
72 "RGA",
73 "RGAElement",
74 "AWMap",
75 "AWMapEntry",
76 "AWMapDict",
77 "GCounter",
78 "GCounterDict",
79 ]
File History 4 commits
sha256:e8214e0062ef8ef0af999937df2731655b6082781fc22bc563f58db2f42b1de9 Merge 'bump/muse-v0.2.1' into 'dev' — proposal: chore: bump… Human 17 days ago
sha256:8de4334a98c945aace420969d389ad678aa926d4ab4e886b2ac4c4241cb3bf2b revert: keep pyproject.toml in canonical PEP 440 form Sonnet 4.6 patch 75 days ago
sha256:a317886dc0496c4af7b285b3e41c86c4c34ea2e79afc63b8829aadb1ada7903f chore: bump version to 0.2.0rc15 to match musehub#113 fix release Sonnet 4.6 patch 75 days ago
sha256:f3b726b50f0aee3622bba751e0a67aa7ae4cf75a798477dbce581940b6a9cf70 feat: migrate invariants cache to .muse/cache/invariants.ms… Sonnet 4.6 patch 142 days ago