0005: Causal DAG ordering with hybrid logical clock tie-break
- Status: accepted
- Date: 2026-09-22
- Amended by: 0046 (policy records are ordered by the linear policy chain, not by this DAG or the HLC; data events are unchanged)
Context
Deriving vault state from a set of independently written events needs a total order that every client computes identically. Wall-clock timestamps cannot be trusted: clients have skewed clocks and a malicious author can write any timestamp. Requiring accurate time on all clients is unenforceable.
Decision
Each event carries:
id: BLAKE3 hash of the canonical encoding of the event envelope, excluding the signature field.parents: the ids of the heads the author had observed when writing.hlc: a hybrid logical clock (wall time, counter, node id).author: the signing device key id, and a signature over everything.
State is a deterministic fold over the topological order of the DAG defined
by parents, with ties between concurrent events broken by (hlc, id).
Wall-clock time is used for display and tie-breaking only and is never load
bearing for security or correctness.
Field semantics under concurrency: each entry field is a multi-value register. If two events write the same field and neither is in the other's causal past, the fold yields both values and marks the field as divergent. The CLI, TUI and GUI surface divergences and the human's choice is recorded as a new event whose parents include both. There is no silent last-writer-wins for secret values.
Consequences
- Clock skew produces odd timestamps in the UI, nothing worse.
- "What did the author see when they made this change" is recorded, which is what policy verification needs (ADR 0006).
- The fold must be specified precisely enough that independent implementations converge; the spec includes canonical CBOR encoding rules and property-based tests that assert convergence under arbitrary interleavings.
- Divergences are rare (they require two humans editing the same field while disconnected) but must be handled in every client.
Alternatives considered
- Timestamp plus UUID ordering. Rejected: depends on clock accuracy and allows trivial backdating.
- Full CRDT per field type (text CRDTs for notes). Deferred; multi-value registers with human resolution are sufficient for secret values and simpler to make deterministic.