Skip to main content

History & conflicts

Collaboration in DeepState is built on a change log, not on locking or a central authority. Understanding the three rules below tells you exactly what happens when two people edit the same thing.

The three rules​

  1. Field by field. A change is recorded per column of a record - a node's title, its position, one key of its content, a connection's type. Two people editing different fields of the same node both win. Two people editing the same field: the later one wins.
  2. Rows come and go. Creating a record and deleting it are changes too. A delete beats any edit that happened before it; an edit that happens after the delete (on a device that hadn't seen it yet) does not resurrect the record - it is applied to nothing and dropped. Recreating a deleted node is a new node.
  3. Order is by clock. "Later" is decided by a hybrid logical clock: wall-clock time, with a counter to break ties, with a device ID to break those. It is also causal: when a device receives changes stamped ahead of its own clock, it moves its clock forward, so a reply is always stamped after the thing it replies to, whatever the wall clocks say.

Consequences worth knowing:

  • Concurrent moves of the same node: one position wins, cleanly. You never get a torn node.
  • Two people typing into the same note at the same time: the last one to stop typing wins the whole text field. DeepState does not merge prose character by character. For shared writing, keep one author per note, or split into several notes.
  • JSON content is split per top-level key, so one person editing an event's description and another its date both succeed.
  • Nothing is ever lost from the log: every change is still there, even if superseded, until you compact.

Deferred changes​

Changes arrive in whatever order the transport delivers them. If an edit to a node arrives before the node's creation (possible with changes files applied out of order, or two transports racing), the edit is parked as waiting and applied the moment the creation lands. The Collaborate dialog and the Apply-changes result show how many are waiting; a persistent count means something upstream never arrived - ask a peer to Push full history or send a fresh changes file.

Clock skew​

Because ordering uses wall-clock time first, a device whose clock is badly wrong will "win" conflicts it shouldn't (a clock an hour fast makes every edit from that device look newest for an hour). Two protections:

  • A device will only let incoming changes advance its own clock by up to one hour; beyond that the incoming stamps are honoured for ordering but the local clock is not dragged along.
  • When changes arrive from a peer whose clock is more than 5 minutes off yours, the Collaborate dialog shows a clock warning naming the device and the offset. Ask its owner to enable automatic time. The warning clears the next time the app starts.

Compaction​

The log grows with every edit. Merging only ever needs the latest change per field plus each record's creation and latest deletion; everything older is superseded and can never win. Compact (Collaborate → History) removes superseded changes older than 90 days from this device. It is safe at any time:

  • Peers are unaffected. Anything they haven't received yet is by definition not superseded and is kept; anything they need later is the newer change, which is kept too.
  • It does not touch a shared folder's files - those are append-only. Re-share into an empty folder to shrink it.
  • It does not remove the audit trail for the last 90 days, so who changed what recently is preserved.

The History line in the dialog shows the log size, the number of contributing devices and the oldest entry, so you can see whether compaction is worth doing.

Author and device​

Every change carries the author name (the operating-system username on the device that made it) and a device ID. These are visible when you inspect a node's history through the assistant's get_board_diff tool and in exported changes files. They are labels, not signatures: within a team that shares a key, anyone could write any name. Treat them as "who was logged in", not as proof.

Rebuilding from the log​

Because the log is complete, a board can be reconstructed from it alone: that is exactly what joining a shared board does, and what applying a first changes file does. It is also what makes the transports interchangeable - the relay, the folder and a USB stick all carry the same operations.