readstate

Overview ¶

Package readstate owns the per-space read/unread engine: the unread entries, the per-object seen-heads frontier, per-tag counters, and the transitions log backing the read-state feed. See docs/read-tracking-proposal.md.

The engine persists three space-shared collections (one set per DB, like _meta):

• _read_unread — one row per unread change, deleted when read.
• _read_state — one row per tracked object: frontier heads, pending remote heads, per-tag counters, and the object's last stateSeq — the dirty-object feed (ChangedSince) reads THIS table; there is no transitions log. A consumer re-pulls the object's unread snapshot and diffs against what it holds.

All mutating methods take the caller's tx context: the apply path calls Track inside the same WriteTx as the record mutations, so an unread entry is atomic with its change; marks and merges open their own tx at the service layer. The engine holds no locks and no in-memory state — callers serialize per object (the apply path via the tree lock, merges/marks via the service's per-object mutex).

Read marking is forward-only: MarkRead covers the given changes and their causal ancestry. The ancestor walk runs over unread rows (each row carries its change's prevIds) and traverses gaps — read, self-authored, or untracked changes between unread ones — through the Resolver, pruning where a walked change's versionId drops below the object's minimum unread versionId (an ancestor's versionId is always smaller than its descendant's, so nothing unread can hide below that line). MarkReadUpTo never walks: range coverage by versionId is gap-immune.