meshlogd 0.1.0__py3-none-any.whl

meshlog/__init__.py

@@ -0,0 +1,21 @@
+"""meshlog -- an event-sourced, eventually-consistent dataset that converges over
+a frequently-partitioning, low-bandwidth mesh (Reticulum on real hardware).
+
+Public surface:
+    Node, Event, FeedStore, HLC, materialize
+    SimNetwork, SimTransport  (in-memory transport for demo/tests)
+"""
+
+__version__ = "0.1.0"
+
+from .event import Event
+from .feedstore import FeedStore
+from .hlc import HLC
+from .node import Node
+from .reducer import materialize
+from .transport import SimNetwork, SimTransport, Transport
+
+__all__ = [
+    "Node", "Event", "FeedStore", "HLC", "materialize",
+    "SimNetwork", "SimTransport", "Transport",
+]

meshlog/cli.py

@@ -0,0 +1,101 @@
+"""Run a meshlog node over a real Reticulum mesh.
+
+Start two of these on machines that share any Reticulum interface (same LAN via
+AutoInterface to begin with; add an RNode/LoRa interface later in your
+~/.reticulum/config -- the application code does not change) and watch a shared
+dataset converge.
+
+Examples
+--------
+Terminal 1 (base camp):
+    python node_rns.py --name base --data ./base.jsonl \\
+        --create R-100 site_assessment --set R-100 status OPENED
+
+Terminal 2 (field team), on another machine:
+    python node_rns.py --name team_a --data ./team_a.jsonl \\
+        --create R-200 water_point --set R-200 functional true
+
+Each node periodically gossips; type `view` + Enter at any node to print its
+current materialized dataset, or `front` to print its frontier.
+
+NOTE: requires `pip install rns`. This script drives the real RNSTransport, which
+is faithful to the RNS API but should be validated on your own mesh.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import threading
+import time
+
+from .node import Node
+from .rns_transport import RNSTransport
+
+
+def coerce(value: str):
+    """Light type coercion so CLI values aren't all strings."""
+    low = value.lower()
+    if low in ("true", "false"):
+        return low == "true"
+    try:
+        return int(value)
+    except ValueError:
+        try:
+            return float(value)
+        except ValueError:
+            return value
+
+
+def gossip_loop(node: Node, interval: float):
+    while True:
+        node.gossip_round()
+        time.sleep(interval)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="meshlog node over Reticulum")
+    ap.add_argument("--name", help="author id; default = identity hash", default=None)
+    ap.add_argument("--data", help="append-only log file (jsonl)", default=None)
+    ap.add_argument("--identity", help="persistent identity file", default=None)
+    ap.add_argument("--configdir", help="Reticulum config dir", default=None)
+    ap.add_argument("--gossip-interval", type=float, default=10.0)
+    ap.add_argument("--create", nargs=2, action="append", metavar=("RID", "FORM"),
+                    default=[], help="create a record")
+    ap.add_argument("--set", nargs=3, action="append", metavar=("RID", "FIELD", "VALUE"),
+                    default=[], help="set a field")
+    ap.add_argument("--note", nargs=2, action="append", metavar=("RID", "TEXT"),
+                    default=[], help="add a note")
+    args = ap.parse_args()
+
+    transport = RNSTransport(configdir=args.configdir, identity_path=args.identity)
+    author = args.name or transport.node_id
+    node = Node(author, transport, persist_path=args.data)
+    transport.set_frontier_provider(node.frontier)
+
+    for rid, form in args.create:
+        node.create_record(rid, form)
+    for rid, field, value in args.set:
+        node.set_field(rid, field, coerce(value))
+    for rid, text in args.note:
+        node.add_note(rid, text)
+
+    threading.Thread(target=gossip_loop, args=(node, args.gossip_interval),
+                     daemon=True).start()
+
+    print(f"meshlog node '{author}' running over Reticulum.")
+    print("commands:  view | front | quit")
+    try:
+        while True:
+            cmd = input("> ").strip().lower()
+            if cmd == "view":
+                print(json.dumps(node.view(), indent=2, sort_keys=True))
+            elif cmd == "front":
+                print(json.dumps(node.frontier(), sort_keys=True))
+            elif cmd in ("quit", "exit"):
+                break
+    except (EOFError, KeyboardInterrupt):
+        pass
+
+
+if __name__ == "__main__":
+    main()

meshlog/event.py

@@ -0,0 +1,99 @@
+"""The Event: the only thing that ever crosses the wire or hits disk.
+
+Design choices that make the distributed-systems math easy:
+
+  * **Immutable.** An event is never edited. "Edits" are new events that
+    reference an earlier record. This is what gives us a free audit trail and,
+    more importantly, conflict-free merges: adding events to a set never
+    conflicts with adding other events.
+
+  * **Per-author feeds.** Every event carries (author, seq). For a given author,
+    seq is strictly contiguous: 1, 2, 3, ... This is the Secure-Scuttlebutt
+    trick. It collapses "what do you have?" from "enumerate a set" down to a
+    single integer per author (the high-water mark), which is what makes the
+    anti-entropy digest tiny enough to ride inside a Reticulum announce.
+
+  * **Hash-chained per feed.** Each event names the id of the previous event in
+    its own feed (``prev``). That makes a feed tamper-evident and lets a
+    receiver verify it is appending contiguous, authentic history rather than a
+    forged gap. (Trusted-collaborator model: we still want integrity, just not
+    anonymity.)
+
+  * **Content-addressed id.** ``id`` is a hash of the whole event. Receiving the
+    same event twice is trivially detected and ignored -> idempotent ingest.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+# Truncated hash length in bytes. 16 bytes = 128 bits is plenty for collision
+# resistance here and keeps ids compact on low-bandwidth links.
+_ID_BYTES = 16
+
+
+def _canonical(obj: Any) -> bytes:
+    """Deterministic byte encoding used for both hashing and the wire."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+@dataclass(frozen=True)
+class Event:
+    author: str            # stable node id (in RNS: identity hash hex)
+    seq: int               # per-author sequence, 1-based, contiguous
+    hlc: tuple[int, int]   # hybrid logical clock stamp (wall_ms, counter)
+    kind: str              # domain event type, e.g. "field.set"
+    payload: dict          # domain data
+    prev: str              # id of previous event in this author's feed ("" if seq==1)
+    id: str = field(default="")  # content hash; filled by from_parts()
+
+    # ---- construction -----------------------------------------------------
+    @staticmethod
+    def _hash_fields(author, seq, hlc, kind, payload, prev) -> str:
+        body = _canonical(
+            {
+                "author": author,
+                "seq": seq,
+                "hlc": list(hlc),
+                "kind": kind,
+                "payload": payload,
+                "prev": prev,
+            }
+        )
+        return hashlib.sha256(body).hexdigest()[: _ID_BYTES * 2]
+
+    @classmethod
+    def from_parts(cls, author, seq, hlc, kind, payload, prev) -> "Event":
+        ev_id = cls._hash_fields(author, seq, tuple(hlc), kind, payload, prev)
+        return cls(author, seq, tuple(hlc), kind, payload, prev, ev_id)
+
+    # ---- integrity --------------------------------------------------------
+    def recompute_id(self) -> str:
+        return self._hash_fields(
+            self.author, self.seq, self.hlc, self.kind, self.payload, self.prev
+        )
+
+    def is_authentic(self) -> bool:
+        """The id must match the content. (A full implementation would also
+        verify an Ed25519 signature by ``author``'s key here -- RNS Identity
+        gives us exactly that primitive; omitted in the prototype core to keep
+        it dependency-free.)"""
+        return self.id == self.recompute_id()
+
+    # ---- wire encoding ----------------------------------------------------
+    def to_wire(self) -> dict:
+        return {
+            "a": self.author,
+            "s": self.seq,
+            "h": list(self.hlc),
+            "k": self.kind,
+            "p": self.payload,
+            "v": self.prev,
+            "i": self.id,
+        }
+
+    @classmethod
+    def from_wire(cls, d: dict) -> "Event":
+        return cls(d["a"], d["s"], tuple(d["h"]), d["k"], d["p"], d["v"], d["i"])

meshlog/feedstore.py

@@ -0,0 +1,176 @@
+"""FeedStore: the append-only log, organised as one contiguous feed per author.
+
+This is the heart of the replication model. It enforces three invariants that
+together make merging safe over a constantly-partitioning network:
+
+  1. **Contiguity.** A feed accepts seq N only when it already holds 1..N-1.
+     Out-of-order arrivals are buffered until the gap fills. This guarantees
+     that a high-water mark (an integer per author) is a *complete* description
+     of what we hold for that author -- no holes.
+
+  2. **Idempotence.** Re-ingesting an event we already have is a no-op. So we can
+     push aggressively and overlap freely; duplicates cost a hash compare.
+
+  3. **Chain integrity.** seq N's ``prev`` must equal the id of seq N-1. A feed
+     that fails this is rejected rather than silently corrupting the merge.
+
+Because of (1)-(3), the global dataset is just the set-union of every node's
+feeds, and union is commutative, associative, and idempotent -> the database is
+a CRDT (a grow-only set of immutable events) and converges regardless of the
+order or grouping in which events arrive.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Iterable
+
+from .event import Event
+
+Frontier = dict[str, int]  # author -> highest contiguous seq held
+
+
+class FeedStore:
+    def __init__(self, persist_path: str | None = None):
+        self._feeds: dict[str, list[Event]] = {}     # author -> [seq1, seq2, ...]
+        self._ids: set[str] = set()                  # all event ids held
+        self._pending: dict[str, dict[int, Event]] = {}  # author -> {seq: event} buffer
+        self._persist_path = persist_path
+        if persist_path and os.path.exists(persist_path):
+            self._load()
+
+    # ---- queries ----------------------------------------------------------
+    def frontier(self) -> Frontier:
+        return {author: len(feed) for author, feed in self._feeds.items()}
+
+    def has(self, event_id: str) -> bool:
+        return event_id in self._ids
+
+    def all_events(self) -> list[Event]:
+        out: list[Event] = []
+        for feed in self._feeds.values():
+            out.extend(feed)
+        return out
+
+    def event_count(self) -> int:
+        return len(self._ids)
+
+    def last_id(self, author: str) -> str:
+        feed = self._feeds.get(author)
+        return feed[-1].id if feed else ""
+
+    def next_seq(self, author: str) -> int:
+        return len(self._feeds.get(author, [])) + 1
+
+    # ---- anti-entropy -----------------------------------------------------
+    def delta_for(self, remote: Frontier, limit: int | None = None) -> list[Event]:
+        """Events this store holds that ``remote`` is missing, given its frontier.
+
+        This is the entire "what to send" computation: for each author, ship the
+        slice of the feed above the remote's high-water mark. Note it naturally
+        relays *other* authors' events too (store-and-forward): if we hold A's
+        feed because we once met A, we'll offer it to C who never met A.
+        """
+        out: list[Event] = []
+        for author, feed in self._feeds.items():
+            have = remote.get(author, 0)
+            if len(feed) > have:
+                out.extend(feed[have:])
+        # Deterministic, dependency-friendly order: lower seqs first per author.
+        out.sort(key=lambda e: (e.author, e.seq))
+        if limit is not None:
+            out = out[:limit]
+        return out
+
+    # ---- mutation ---------------------------------------------------------
+    def append_local(self, event: Event) -> None:
+        """Append an event minted by *this* node. Assumes seq/prev already set
+        correctly by the Node (which owns the author identity and HLC)."""
+        feed = self._feeds.setdefault(event.author, [])
+        assert event.seq == len(feed) + 1, "local feed must stay contiguous"
+        feed.append(event)
+        self._ids.add(event.id)
+        self._persist(event)
+
+    def ingest(self, event: Event) -> bool:
+        """Accept a remote event. Returns True iff it advanced our state.
+
+        Handles duplicates, out-of-order arrivals (buffered), and chain
+        verification. Safe to call with anything; bad events are dropped.
+        """
+        if not event.is_authentic():
+            return False
+        if event.id in self._ids:
+            return False  # idempotent
+
+        feed = self._feeds.setdefault(event.author, [])
+        expected = len(feed) + 1
+
+        if event.seq < expected:
+            return False  # stale / already have a different copy of this slot
+        if event.seq > expected:
+            # Future event: buffer and wait for the gap to fill.
+            self._pending.setdefault(event.author, {})[event.seq] = event
+            return False
+
+        # event.seq == expected: verify chain link, then append.
+        prev_id = feed[-1].id if feed else ""
+        if event.prev != prev_id:
+            return False  # forged or forked history; reject
+        feed.append(event)
+        self._ids.add(event.id)
+        self._persist(event)
+
+        # Try to drain any buffered successors that are now contiguous.
+        self._drain(event.author)
+        return True
+
+    def ingest_many(self, events: Iterable[Event]) -> int:
+        """Ingest a batch (e.g. a received delta). Because a batch may arrive in
+        any order, we loop until no further progress is made."""
+        events = list(events)
+        applied = 0
+        progress = True
+        while progress:
+            progress = False
+            for ev in events:
+                if ev.id not in self._ids and self.ingest(ev):
+                    applied += 1
+                    progress = True
+        return applied
+
+    def _drain(self, author: str) -> None:
+        buf = self._pending.get(author)
+        if not buf:
+            return
+        feed = self._feeds[author]
+        while (nxt := buf.pop(len(feed) + 1, None)) is not None:
+            expected_prev = feed[-1].id if feed else ""
+            if nxt.prev != expected_prev:
+                # Forked history at this slot; stop draining this feed.
+                break
+            feed.append(nxt)
+            self._ids.add(nxt.id)
+            self._persist(nxt)
+
+    # ---- persistence (append-only jsonl; the log *is* the database) -------
+    def _persist(self, event: Event) -> None:
+        if not self._persist_path:
+            return
+        with open(self._persist_path, "a") as fh:
+            fh.write(json.dumps(event.to_wire()) + "\n")
+
+    def _load(self) -> None:
+        rows = []
+        with open(self._persist_path) as fh:
+            for line in fh:
+                line = line.strip()
+                if line:
+                    rows.append(Event.from_wire(json.loads(line)))
+        # Sort so feeds load contiguously, then ingest.
+        rows.sort(key=lambda e: (e.author, e.seq))
+        for ev in rows:
+            feed = self._feeds.setdefault(ev.author, [])
+            if ev.seq == len(feed) + 1 and ev.id not in self._ids:
+                feed.append(ev)
+                self._ids.add(ev.id)

meshlog/hlc.py

@@ -0,0 +1,64 @@
+"""Hybrid Logical Clocks (HLC).
+
+Why not wall-clock timestamps? In this network there is no NTP, devices drift,
+and a node may be offline for days. Ordering events by wall time alone would let
+a laggy clock silently win a last-writer-wins race. HLCs fuse physical time with
+a logical counter so that:
+
+  * timestamps stay close to real wall-clock time (good for humans/display), and
+  * causality is never violated: if event B is created after observing event A,
+    then hlc(B) > hlc(A), regardless of clock skew.
+
+Reference: Kulkarni et al., "Logical Physical Clocks and Consistent Snapshots
+in Globally Distributed Databases" (2014).
+
+An HLC stamp here is (wall_ms, counter). For a *total* order across authors we
+break ties with the author id at the call site (see reducer.total_order_key).
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+
+def _phys_now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+@dataclass
+class HLC:
+    """A per-node hybrid logical clock.
+
+    ``now()`` is called when the node *creates* a local event.
+    ``update()`` is called when the node *receives* a remote stamp, so that any
+    event it subsequently creates causally follows what it has seen.
+    """
+
+    wall: int = 0
+    counter: int = 0
+    # Injectable clock for deterministic tests; defaults to real time.
+    _phys: callable = _phys_now_ms
+
+    def now(self) -> tuple[int, int]:
+        pt = self._phys()
+        if pt > self.wall:
+            self.wall, self.counter = pt, 0
+        else:
+            # Physical clock didn't advance (or went backwards): bump logical.
+            self.counter += 1
+        return (self.wall, self.counter)
+
+    def update(self, remote: tuple[int, int]) -> tuple[int, int]:
+        r_wall, r_counter = remote
+        pt = self._phys()
+        new_wall = max(self.wall, r_wall, pt)
+        if new_wall == self.wall == r_wall:
+            self.counter = max(self.counter, r_counter) + 1
+        elif new_wall == self.wall:
+            self.counter += 1
+        elif new_wall == r_wall:
+            self.counter = r_counter + 1
+        else:  # new_wall == pt, a fresh physical tick beyond anything seen
+            self.counter = 0
+        self.wall = new_wall
+        return (self.wall, self.counter)

meshlog/node.py

@@ -0,0 +1,114 @@
+"""The Node and the anti-entropy protocol.
+
+Anti-entropy (a.k.a. gossip reconciliation) is deliberately tiny:
+
+  When two peers can talk, each sends the other its FRONTIER (the per-author
+  high-water-mark vector). On receiving a peer's frontier, a node computes the
+  slice of its log the peer is missing and PUSHES it. Ingest is idempotent and
+  gap-tolerant, so overlapping pushes and reordered batches are harmless.
+
+  message := {"t": "frontier", "f": {author: seq}}
+           | {"t": "events",   "e": [event_wire, ...]}
+
+That's the whole protocol. One frontier exchange per contact reconciles the pair
+completely; transitive (multi-hop) convergence happens because each node relays
+every author's events it holds, not just its own. Over a partitioning network,
+repeated pairwise contacts compose into global convergence -- which is exactly
+the store-and-forward property we want for "base camp + teams that never meet."
+
+Batching: deltas are chunked (``MAX_EVENTS_PER_MSG``) so a single message stays
+small on a low-bandwidth link. A real radio build would additionally send large
+batches as an RNS Resource rather than inline packets (see rns_transport.py).
+"""
+from __future__ import annotations
+
+import json
+
+from .event import Event
+from .feedstore import FeedStore, Frontier
+from .hlc import HLC
+from .reducer import materialize
+from .transport import Transport
+
+MAX_EVENTS_PER_MSG = 32
+
+
+class Node:
+    def __init__(self, author: str, transport: Transport,
+                 persist_path: str | None = None, hlc: HLC | None = None):
+        self.author = author
+        self.store = FeedStore(persist_path)
+        self.hlc = hlc or HLC()
+        self.transport = transport
+        transport.set_receive(self._on_message)
+
+    # ---- producing local events ------------------------------------------
+    def emit(self, kind: str, payload: dict) -> Event:
+        seq = self.store.next_seq(self.author)
+        ev = Event.from_parts(
+            author=self.author,
+            seq=seq,
+            hlc=self.hlc.now(),
+            kind=kind,
+            payload=payload,
+            prev=self.store.last_id(self.author),
+        )
+        self.store.append_local(ev)
+        return ev
+
+    # Convenience domain helpers (KoboToolbox-style records) ----------------
+    def create_record(self, record_id: str, form: str) -> Event:
+        return self.emit("record.create", {"record_id": record_id, "form": form, "by": self.author})
+
+    def set_field(self, record_id: str, field: str, value) -> Event:
+        return self.emit("field.set", {"record_id": record_id, "field": field, "value": value})
+
+    def add_note(self, record_id: str, text: str) -> Event:
+        return self.emit("note.add", {"record_id": record_id, "text": text})
+
+    def add_attachment(self, record_id: str, field: str, blob_hash: str, size: int, mime: str) -> Event:
+        return self.emit("attachment.add", {
+            "record_id": record_id, "field": field,
+            "blob_hash": blob_hash, "size": size, "mime": mime,
+        })
+
+    # ---- the materialized view -------------------------------------------
+    def view(self) -> dict:
+        return materialize(self.store.all_events())
+
+    def frontier(self) -> Frontier:
+        return self.store.frontier()
+
+    # ---- anti-entropy: initiate ------------------------------------------
+    def gossip_round(self) -> None:
+        """Offer our frontier to everyone currently reachable."""
+        msg = self._encode({"t": "frontier", "f": self.store.frontier()})
+        for peer in self.transport.reachable_peers():
+            self.transport.send(peer, msg)
+
+    # ---- anti-entropy: react ---------------------------------------------
+    def _on_message(self, src: str, raw: bytes) -> None:
+        msg = self._decode(raw)
+        if msg["t"] == "frontier":
+            # Peer told us what it has; push what it lacks, in bounded chunks.
+            delta = self.store.delta_for(msg["f"])
+            for i in range(0, len(delta), MAX_EVENTS_PER_MSG):
+                chunk = delta[i:i + MAX_EVENTS_PER_MSG]
+                self.transport.send(src, self._encode(
+                    {"t": "events", "e": [e.to_wire() for e in chunk]}
+                ))
+        elif msg["t"] == "events":
+            incoming = [Event.from_wire(d) for d in msg["e"]]
+            # Advance our HLC past anything we observe (causality).
+            for e in incoming:
+                self.hlc.update(e.hlc)
+            self.store.ingest_many(incoming)
+
+    # ---- wire codec (swap for msgpack/CBOR in production) -----------------
+    @staticmethod
+    def _encode(obj: dict) -> bytes:
+        return json.dumps(obj, separators=(",", ":")).encode("utf-8")
+
+    @staticmethod
+    def _decode(raw: bytes) -> dict:
+        return json.loads(raw.decode("utf-8"))

meshlog/reducer.py

@@ -0,0 +1,87 @@
+"""Reducer: fold the event set into the materialized view (the "current" data).
+
+The view is a pure function of the *set* of events. Two nodes holding the same
+set always compute byte-identical views, no matter what order events arrived in.
+That is the property that turns "everyone eventually holds the same events"
+(guaranteed by FeedStore + anti-entropy) into "everyone eventually shows the
+same data" (what the user actually cares about).
+
+Conflict handling:
+  * Most events are additive (notes, attachments) and never conflict.
+  * Mutable scalar fields use Last-Writer-Wins, but "last" is decided by the
+    event's HLC stamp -- NOT arrival order and NOT wall clock -- with the author
+    id as a deterministic tiebreaker. So concurrent edits from two partitions
+    resolve to the same winner on every node.
+
+Domain model here is a stand-in for KoboToolbox-style assessment records:
+  record.create    {record_id, form, by}
+  field.set        {record_id, field, value}
+  attachment.add   {record_id, field, blob_hash, size, mime}
+  note.add         {record_id, text}
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field as dc_field
+
+from .event import Event
+
+
+def total_order_key(ev: Event):
+    """A deterministic total order over events for LWW resolution."""
+    return (ev.hlc[0], ev.hlc[1], ev.author, ev.seq)
+
+
+@dataclass
+class Record:
+    record_id: str
+    form: str = ""
+    created_by: str = ""
+    fields: dict = dc_field(default_factory=dict)        # field -> value (LWW)
+    _field_stamp: dict = dc_field(default_factory=dict)  # field -> winning order key
+    attachments: list = dc_field(default_factory=list)   # [{field, blob_hash, size, mime}]
+    notes: list = dc_field(default_factory=list)         # [text, ...] (append-only)
+
+    def public(self) -> dict:
+        return {
+            "record_id": self.record_id,
+            "form": self.form,
+            "created_by": self.created_by,
+            "fields": dict(sorted(self.fields.items())),
+            "attachments": sorted(self.attachments, key=lambda a: (a["field"], a["blob_hash"])),
+            "notes": list(self.notes),
+        }
+
+
+def materialize(events: list[Event]) -> dict[str, dict]:
+    """Fold events -> {record_id: public_record_dict}."""
+    records: dict[str, Record] = {}
+    # Process in HLC total order so LWW is order-independent of *arrival*.
+    for ev in sorted(events, key=total_order_key):
+        p = ev.payload
+        rid = p.get("record_id")
+        if ev.kind == "record.create":
+            rec = records.setdefault(rid, Record(rid))
+            rec.form = p.get("form", rec.form)
+            rec.created_by = p.get("by", rec.created_by)
+        elif ev.kind == "field.set":
+            rec = records.setdefault(rid, Record(rid))
+            key = total_order_key(ev)
+            # LWW: only overwrite if this event is later in the total order.
+            if key >= rec._field_stamp.get(p["field"], (-1, -1, "", -1)):
+                rec.fields[p["field"]] = p["value"]
+                rec._field_stamp[p["field"]] = key
+        elif ev.kind == "attachment.add":
+            rec = records.setdefault(rid, Record(rid))
+            rec.attachments.append(
+                {
+                    "field": p["field"],
+                    "blob_hash": p["blob_hash"],
+                    "size": p.get("size", 0),
+                    "mime": p.get("mime", ""),
+                }
+            )
+        elif ev.kind == "note.add":
+            rec = records.setdefault(rid, Record(rid))
+            rec.notes.append(p["text"])
+        # Unknown kinds are ignored: forward-compatible by construction.
+    return {rid: rec.public() for rid, rec in records.items()}