meshlogd 0.1.0__tar.gz

meshlogd-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python build / cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# meshlog runtime data (append-only field logs) and Reticulum state
+*.jsonl
+.reticulum/
+
+# tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store

meshlogd-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kevin Hoffman
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

meshlogd-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: meshlogd
+Version: 0.1.0
+Summary: Event-sourced, eventually-consistent dataset that converges over a partition-prone Reticulum (LoRa) mesh.
+Project-URL: Homepage, https://meshlogd.org
+Project-URL: Source, https://github.com/meshlogd/meshlogd
+Project-URL: Issues, https://github.com/meshlogd/meshlogd/issues
+Author-email: Kevin Hoffman <alothien+meshlogd@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: anti-entropy,crdt,event-sourcing,eventually-consistent,gossip,lora,mesh,offline-first,radio,reticulum
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: radio
+Requires-Dist: rns>=0.7; extra == 'radio'
+Description-Content-Type: text/markdown
+
+# meshlog
+
+An **event-sourced, eventually-consistent dataset** that converges over a
+frequently-partitioning, low-bandwidth mesh. Built for the "trusted
+collaborators, no internet, private radio" case: a base camp and field teams
+(humanitarian assessment, SAR, expeditions) collecting a shared dataset with no
+server and no connectivity, reconciling whenever radios come into range.
+
+The transport is [Reticulum](https://reticulum.network) on real hardware
+(LoRa/packet radio/anything), but the engine is transport-agnostic and ships
+with an in-memory transport so you can run, test, and watch it converge with no
+radios at all.
+
+## Install
+
+```bash
+pip install meshlogd            # core engine (stdlib-only)
+pip install "meshlogd[radio]"   # + Reticulum, for the real LoRa/packet-radio transport
+```
+
+> **Naming:** the distribution and daemon command are **`meshlogd`**; the importable
+> library is **`meshlog`** (`import meshlog`) — the trailing `d` follows the Unix
+> daemon convention (cf. `ssh`/`sshd`), like how `pyyaml` installs but imports as `yaml`.
+
+## The idea in one breath
+
+KoboToolbox already solves offline *data entry* but syncs to a central server
+over the internet. meshlog replaces that central sync with **peer-to-peer
+anti-entropy gossip over a radio mesh**, so the shared dataset converges with no
+server and no internet. Kobo (or any form UI) owns the forms; meshlog owns the
+replication layer Kobo doesn't have.
+
+## Why event sourcing makes this easy
+
+The whole database is a **grow-only set of immutable, per-author events**. That
+single decision hands you the hard distributed-systems properties almost for
+free:
+
+- **Merging is set union.** Union is commutative, associative, and idempotent,
+  so the dataset is a CRDT: it converges regardless of the order or grouping in
+  which events arrive across a partitioning network.
+- **Per-author contiguous feeds** (the Secure-Scuttlebutt trick) collapse "what
+  do you have?" down to one integer per author — a **high-water-mark frontier**.
+  That digest is tiny enough to ride inside a Reticulum *announce*.
+- **Hash-chained feeds** make history tamper-evident (we're trusted-collaborator,
+  so we want integrity — just not anonymity).
+- **The materialized view is a pure fold** over the event set, so two nodes with
+  the same events compute byte-identical state. Conflicts on mutable scalar
+  fields resolve by **Last-Writer-Wins keyed on a Hybrid Logical Clock**, not
+  wall time and not arrival order — so concurrent edits from two islands pick the
+  same winner everywhere.
+
+## Anti-entropy protocol (the entire thing)
+
+```
+when two peers can talk:
+    each sends its FRONTIER  = {author: high_water_seq}
+    on receiving a peer's frontier:
+        push the slice of every feed above the peer's marks   (chunked)
+    ingest is idempotent + gap-buffering, so overlaps/reorders are harmless
+```
+
+Multi-hop convergence is automatic: a node relays *every* author's events it
+holds, not just its own, so A's events reach C through B even if A and C never
+meet. That's the store-and-forward property, achieved without special-casing it.
+
+## Layout
+
+```
+meshlog/
+  hlc.py            Hybrid Logical Clock
+  event.py          immutable, hash-chained, content-addressed Event
+  feedstore.py      append-only per-author log; frontier + delta computation
+  reducer.py        deterministic fold -> materialized records (Kobo-style)
+  transport.py      Transport interface + in-memory SimTransport (partitions)
+  node.py           Node + the anti-entropy protocol
+  rns_transport.py  real Reticulum transport (Link + Resource + announce)
+demo_sim.py         base camp + 4 teams converge across staged partitions
+test_convergence.py 200 randomized partition trials + fold-determinism check
+meshlog/cli.py      CLI to run a node over a live Reticulum mesh (the `meshlogd` command)
+```
+
+## Run it (no radios needed)
+
+```bash
+python -m demo_sim          # scripted scenario, prints the converged dataset
+python -m test_convergence  # 200 randomized partition/merge trials
+```
+
+The demo islands three groups, has each collect independently, stages a
+conflicting concurrent edit, then heals the network in stages and verifies every
+node ends with identical frontiers, identical views, and the same LWW winner.
+
+## Run it for real (over Reticulum)
+
+```bash
+pip install "meshlogd[radio]"          # pulls in Reticulum (rns)
+# Machine A:
+meshlogd --name base   --data base.jsonl   --create R-100 site_assessment
+# Machine B (same LAN to start; add a LoRa interface in ~/.reticulum/config later):
+meshlogd --name team_a --data team_a.jsonl --create R-200 water_point
+# type `view` at either prompt to watch the dataset converge
+```
+
+## Verification status
+
+- `feedstore`, `reducer`, `hlc`, `node`, `transport`, the demo, and the 200
+  randomized trials **run and pass** as committed.
+- `rns_transport.py` / `meshlog/cli.py` are written against the Reticulum 1.3.x API
+  (Identity, Destination, Link, Resource, Packet, announce handlers) and are
+  faithful to the docs/examples, but have **not** been exercised on a live mesh
+  here. Stand up two instances to validate end-to-end before field use.
+
+## Deliberately left as extension points
+
+- **Attachments / blobs.** Events carry a content hash + size; the bytes are not
+  inlined. Add a content-addressed blob store and transfer blobs lazily over RNS
+  Resources, *after* structured events, so photos never starve assessment data on
+  a slow link.
+- **Signatures.** `Event.is_authentic()` currently checks the content hash. With
+  RNS you already hold each author's Ed25519 key — sign the event id and verify
+  on ingest to close the trusted-but-verify loop.
+- **Wire codec.** Prototype uses JSON for readability. Swap `_encode/_decode` for
+  MessagePack or CBOR to cut bytes on the radio.
+- **Compaction / snapshots.** Grow-only logs grow. Add periodic signed snapshots
+  + feed truncation once a quorum has acknowledged a watermark.
+- **Kobo bridge.** Poll the KoboToolbox/ODK submission API (or read KoboCollect
+  instances) and translate each submission into `record.create` + `field.set`
+  events. That's the actual on-ramp to the HHI use case.
+
+## Reading list (steal from these)
+
+- **Secure Scuttlebutt** — append-only per-author feeds + gossip replication for
+  intermittent offline networks. This design is a close cousin.
+- **CRDTs** — why union-based / LWW-register merges converge.
+- **Kulkarni et al. 2014, Hybrid Logical Clocks** — the clock used here.
+- **Reticulum manual**, Understanding + API Reference chapters — Link, Resource,
+  and the announce mechanism.

meshlogd-0.1.0/README.md

@@ -0,0 +1,138 @@
+# meshlog
+
+An **event-sourced, eventually-consistent dataset** that converges over a
+frequently-partitioning, low-bandwidth mesh. Built for the "trusted
+collaborators, no internet, private radio" case: a base camp and field teams
+(humanitarian assessment, SAR, expeditions) collecting a shared dataset with no
+server and no connectivity, reconciling whenever radios come into range.
+
+The transport is [Reticulum](https://reticulum.network) on real hardware
+(LoRa/packet radio/anything), but the engine is transport-agnostic and ships
+with an in-memory transport so you can run, test, and watch it converge with no
+radios at all.
+
+## Install
+
+```bash
+pip install meshlogd            # core engine (stdlib-only)
+pip install "meshlogd[radio]"   # + Reticulum, for the real LoRa/packet-radio transport
+```
+
+> **Naming:** the distribution and daemon command are **`meshlogd`**; the importable
+> library is **`meshlog`** (`import meshlog`) — the trailing `d` follows the Unix
+> daemon convention (cf. `ssh`/`sshd`), like how `pyyaml` installs but imports as `yaml`.
+
+## The idea in one breath
+
+KoboToolbox already solves offline *data entry* but syncs to a central server
+over the internet. meshlog replaces that central sync with **peer-to-peer
+anti-entropy gossip over a radio mesh**, so the shared dataset converges with no
+server and no internet. Kobo (or any form UI) owns the forms; meshlog owns the
+replication layer Kobo doesn't have.
+
+## Why event sourcing makes this easy
+
+The whole database is a **grow-only set of immutable, per-author events**. That
+single decision hands you the hard distributed-systems properties almost for
+free:
+
+- **Merging is set union.** Union is commutative, associative, and idempotent,
+  so the dataset is a CRDT: it converges regardless of the order or grouping in
+  which events arrive across a partitioning network.
+- **Per-author contiguous feeds** (the Secure-Scuttlebutt trick) collapse "what
+  do you have?" down to one integer per author — a **high-water-mark frontier**.
+  That digest is tiny enough to ride inside a Reticulum *announce*.
+- **Hash-chained feeds** make history tamper-evident (we're trusted-collaborator,
+  so we want integrity — just not anonymity).
+- **The materialized view is a pure fold** over the event set, so two nodes with
+  the same events compute byte-identical state. Conflicts on mutable scalar
+  fields resolve by **Last-Writer-Wins keyed on a Hybrid Logical Clock**, not
+  wall time and not arrival order — so concurrent edits from two islands pick the
+  same winner everywhere.
+
+## Anti-entropy protocol (the entire thing)
+
+```
+when two peers can talk:
+    each sends its FRONTIER  = {author: high_water_seq}
+    on receiving a peer's frontier:
+        push the slice of every feed above the peer's marks   (chunked)
+    ingest is idempotent + gap-buffering, so overlaps/reorders are harmless
+```
+
+Multi-hop convergence is automatic: a node relays *every* author's events it
+holds, not just its own, so A's events reach C through B even if A and C never
+meet. That's the store-and-forward property, achieved without special-casing it.
+
+## Layout
+
+```
+meshlog/
+  hlc.py            Hybrid Logical Clock
+  event.py          immutable, hash-chained, content-addressed Event
+  feedstore.py      append-only per-author log; frontier + delta computation
+  reducer.py        deterministic fold -> materialized records (Kobo-style)
+  transport.py      Transport interface + in-memory SimTransport (partitions)
+  node.py           Node + the anti-entropy protocol
+  rns_transport.py  real Reticulum transport (Link + Resource + announce)
+demo_sim.py         base camp + 4 teams converge across staged partitions
+test_convergence.py 200 randomized partition trials + fold-determinism check
+meshlog/cli.py      CLI to run a node over a live Reticulum mesh (the `meshlogd` command)
+```
+
+## Run it (no radios needed)
+
+```bash
+python -m demo_sim          # scripted scenario, prints the converged dataset
+python -m test_convergence  # 200 randomized partition/merge trials
+```
+
+The demo islands three groups, has each collect independently, stages a
+conflicting concurrent edit, then heals the network in stages and verifies every
+node ends with identical frontiers, identical views, and the same LWW winner.
+
+## Run it for real (over Reticulum)
+
+```bash
+pip install "meshlogd[radio]"          # pulls in Reticulum (rns)
+# Machine A:
+meshlogd --name base   --data base.jsonl   --create R-100 site_assessment
+# Machine B (same LAN to start; add a LoRa interface in ~/.reticulum/config later):
+meshlogd --name team_a --data team_a.jsonl --create R-200 water_point
+# type `view` at either prompt to watch the dataset converge
+```
+
+## Verification status
+
+- `feedstore`, `reducer`, `hlc`, `node`, `transport`, the demo, and the 200
+  randomized trials **run and pass** as committed.
+- `rns_transport.py` / `meshlog/cli.py` are written against the Reticulum 1.3.x API
+  (Identity, Destination, Link, Resource, Packet, announce handlers) and are
+  faithful to the docs/examples, but have **not** been exercised on a live mesh
+  here. Stand up two instances to validate end-to-end before field use.
+
+## Deliberately left as extension points
+
+- **Attachments / blobs.** Events carry a content hash + size; the bytes are not
+  inlined. Add a content-addressed blob store and transfer blobs lazily over RNS
+  Resources, *after* structured events, so photos never starve assessment data on
+  a slow link.
+- **Signatures.** `Event.is_authentic()` currently checks the content hash. With
+  RNS you already hold each author's Ed25519 key — sign the event id and verify
+  on ingest to close the trusted-but-verify loop.
+- **Wire codec.** Prototype uses JSON for readability. Swap `_encode/_decode` for
+  MessagePack or CBOR to cut bytes on the radio.
+- **Compaction / snapshots.** Grow-only logs grow. Add periodic signed snapshots
+  + feed truncation once a quorum has acknowledged a watermark.
+- **Kobo bridge.** Poll the KoboToolbox/ODK submission API (or read KoboCollect
+  instances) and translate each submission into `record.create` + `field.set`
+  events. That's the actual on-ramp to the HHI use case.
+
+## Reading list (steal from these)
+
+- **Secure Scuttlebutt** — append-only per-author feeds + gossip replication for
+  intermittent offline networks. This design is a close cousin.
+- **CRDTs** — why union-based / LWW-register merges converge.
+- **Kulkarni et al. 2014, Hybrid Logical Clocks** — the clock used here.
+- **Reticulum manual**, Understanding + API Reference chapters — Link, Resource,
+  and the announce mechanism.

meshlogd-0.1.0/demo_sim.py

@@ -0,0 +1,151 @@
+"""Scenario demo: a shared assessment dataset converging across a partitioning mesh.
+
+Five nodes -- a base camp and four field teams -- collect KoboToolbox-style
+assessment records while the network is islanded, then reconcile as partitions
+heal. We also stage a *concurrent conflicting edit* to the same field from two
+separated islands, and show that last-writer-wins resolves to the same winner on
+every node once they converge.
+
+Run:  python -m demo_sim     (from the project root)
+"""
+from __future__ import annotations
+
+import json
+
+from meshlog import Node
+from meshlog.hlc import HLC
+from meshlog.transport import SimNetwork, SimTransport
+
+
+def make_clock(start_ms: int):
+    """A controllable physical clock so the demo is deterministic and we can
+    stage 'team B edits later than team A' precisely."""
+    state = {"t": start_ms}
+
+    def phys():
+        state["t"] += 1
+        return state["t"]
+
+    return phys, state
+
+
+def settle(nodes, rounds=6):
+    """Run gossip rounds until quiet. With a fixed partition, a couple of rounds
+    suffice; we run extra for good measure."""
+    for _ in range(rounds):
+        for n in nodes.values():
+            n.gossip_round()
+
+
+def frontiers_equal(nodes) -> bool:
+    fs = [json.dumps(n.frontier(), sort_keys=True) for n in nodes.values()]
+    return len(set(fs)) == 1
+
+
+def views_equal(nodes) -> bool:
+    vs = [json.dumps(n.view(), sort_keys=True) for n in nodes.values()]
+    return len(set(vs)) == 1
+
+
+def report(label, nodes):
+    print(f"\n--- {label} ---")
+    for name, n in nodes.items():
+        print(f"  {name:6s}  events held: {n.store.event_count():2d}   "
+              f"records: {len(n.view()):2d}")
+
+
+def main():
+    net = SimNetwork()
+    names = ["base", "team_a", "team_b", "team_c", "team_d"]
+
+    # Give each node its own controllable clock, staggered so HLC ties are
+    # meaningful and team_b's later edit deterministically wins the conflict.
+    nodes: dict[str, Node] = {}
+    for i, name in enumerate(names):
+        phys, _ = make_clock(1_000_000 + i)  # distinct starting points
+        t = SimTransport(name, net)
+        nodes[name] = Node(name, t, hlc=HLC(_phys=phys))
+
+    print("=" * 64)
+    print("meshlog convergence demo: base camp + 4 field teams")
+    print("=" * 64)
+
+    # ---------------------------------------------------------------
+    # Phase 1: TOTAL PARTITION. Three islands, each collecting data.
+    #   island 1: base
+    #   island 2: team_a, team_b
+    #   island 3: team_c, team_d
+    # ---------------------------------------------------------------
+    net.set_partitions([{"base"}, {"team_a", "team_b"}, {"team_c", "team_d"}])
+
+    nodes["base"].create_record("R-100", "site_assessment")
+    nodes["base"].set_field("R-100", "site_name", "North Ridge Camp")
+    nodes["base"].set_field("R-100", "status", "OPENED")
+
+    nodes["team_a"].create_record("R-200", "water_point")
+    nodes["team_a"].set_field("R-200", "location", "well by the river")
+    nodes["team_a"].set_field("R-200", "functional", True)
+    nodes["team_b"].create_record("R-201", "shelter_count")
+    nodes["team_b"].set_field("R-201", "tents", 48)
+
+    nodes["team_c"].create_record("R-300", "medical_need")
+    nodes["team_c"].set_field("R-300", "triage", "yellow")
+    nodes["team_d"].add_note("R-300", "team_d corroborates: 2 cases need evac")
+
+    # Staged CONFLICT: both base and team_a set R-100.status while partitioned.
+    # team_a's clock is later, so its value must win everywhere after merge.
+    nodes["base"].set_field("R-100", "status", "OPENED")        # earlier
+    nodes["team_a"].set_field("R-100", "status", "AT_CAPACITY") # later -> winner
+
+    # Gossip *within* each island only (partitions block cross-island traffic).
+    settle(nodes)
+    report("Phase 1: total partition (3 islands collect independently)", nodes)
+    print("  frontiers identical across all nodes? ", frontiers_equal(nodes))
+
+    # ---------------------------------------------------------------
+    # Phase 2: PARTIAL HEAL. Base reconnects with island 2.
+    # ---------------------------------------------------------------
+    net.set_partitions([{"base", "team_a", "team_b"}, {"team_c", "team_d"}])
+    settle(nodes)
+    report("Phase 2: base + team_a + team_b merged (team_c/d still islanded)", nodes)
+
+    # ---------------------------------------------------------------
+    # Phase 3: FULL HEAL. Everyone reachable; converge.
+    # ---------------------------------------------------------------
+    net.set_partitions([{"base", "team_a", "team_b", "team_c", "team_d"}])
+    settle(nodes)
+    report("Phase 3: full heal", nodes)
+
+    # ---------------------------------------------------------------
+    # Verify convergence.
+    # ---------------------------------------------------------------
+    print("\n" + "=" * 64)
+    ok_front = frontiers_equal(nodes)
+    ok_views = views_equal(nodes)
+    print(f"  all frontiers identical?      {ok_front}")
+    print(f"  all materialized views equal? {ok_views}")
+
+    winner = nodes["base"].view()["R-100"]["fields"]["status"]
+    print(f"  conflict R-100.status resolved to: {winner!r} "
+          f"(expected 'AT_CAPACITY', team_b's later HLC wins)")
+    same_winner = all(
+        n.view()["R-100"]["fields"]["status"] == winner for n in nodes.values()
+    )
+    print(f"  every node agrees on the winner? {same_winner}")
+
+    print("\n  Final converged dataset (from base camp's view):")
+    print(json.dumps(nodes["base"].view(), indent=2, sort_keys=True))
+
+    print("\n" + "=" * 64)
+    if ok_front and ok_views and same_winner and winner == "AT_CAPACITY":
+        print("  RESULT: ALL NODES CONVERGED  [PASS]")
+    else:
+        print("  RESULT: divergence detected   [FAIL]")
+        raise SystemExit(1)
+    print(f"  network carried {net.messages_sent} messages, "
+          f"{net.bytes_sent} bytes total")
+    print("=" * 64)
+
+
+if __name__ == "__main__":
+    main()