Module oplog 

The append-only, replica-tagged operation log.

OpRecord follows docs/proposals/multi-device-sync.md §“The frame: sync events, not files” field-for-field, with two B1 specifics:

• op_id is content-derived via the shipped B7 discipline (car_proto::deterministic_run_id’s SHA-256 + 0x1f field separators; the proposal’s blake3(payload) is the same content-addressing idea — we reuse the hash the codebase already standardized on rather than add a dependency). The digest covers device_id ‖ seq ‖ prev ‖ hlc ‖ scope ‖ surface ‖ canonical(payload), so the id is simultaneously the natural dedup key for op retransmission AND a tamper-evident cover of the record, including its position in the device chain. Logical-entity dedup across devices (the proposal’s “conversations dedup on (speaker,text,timestamp); knowledge on fact_id”) happens at the fold’s stable-key level, not on op_id — see OpRecord::stable_key. Event-stream surfaces are the exception: routing observations fold as a MULTISET (the proposal replays “the merged multiset of observations”), so they key by op_id — two byte-identical observations are two events, and only retransmission dedups. See Surface::is_event_stream / OpRecord::fold_key.
• The HLC is shape-only in B1. Hlc carries the proposal’s {wall_ms, counter, device_id} total order; DeviceLog stamps pure Lamport values into wall_ms (counter stays 0) with the standard send/receive rules, so nothing in this crate reads a wall clock. B3 replaces the stamp source with the true hybrid clock — the wire shape and the fold are unchanged.

Order-verifiability: each op carries a per-device seq and the prev op_id of the same device’s preceding op — a per-device hash chain. verify_log recomputes every id and walks every chain, so a loaded or received log proves its own order and integrity.

Honesty note — device identity is asserted, not authenticated. The hash chain proves internal consistency (nothing was reordered or mutated after the fact), but a forger who recomputes the hashes can emit a chain claiming any device_id and it will pass verify_log. Cryptographic device identity (signing ops/checkpoints with a device key) lands with the checkpoint/relay slices (B4/B6); until then, trust in a log’s origin comes from the transport that delivered it.

Structs

DeviceLog

The per-device append discipline: maintains the seq/prev chain and stamps Hlc values from an HlcClock over an injected WallClock — B3’s real hybrid clock, replacing B1’s pure-Lamport stamp source behind the same wire shape.

Hlc

Hybrid-logical-clock stamp — the proposal’s {wall_ms, counter, device_id}. The derived Ord (field order) IS the total order every device agrees on. B1 stamped pure Lamport values into this shape; B3’s HlcClock supplies the real hybrid clock — the wire shape is unchanged, exactly as promised.

HlcClock

The real hybrid logical clock (B3) — the proposal’s {wall_ms, counter} state with the standard HLC send/receive rules (Kulkarni et al.):

OpRecord

One state-changing operation in the oplog.

Enums

ChainError

A chain-verification failure from verify_log.

FoldTier

How a surface folds — the proposal’s per-surface fold-rule tiers.

Scope

Visibility regime — the proposal’s “the scope field is the whole answer”.

Surface

Which persisted surface an op mutates — the proposal’s surfaces.

Functions

canonical_json

Canonical, key-sorted, compact JSON — the deterministic serialization the op_id digest and crate::fold::state_hash are computed over. Independent of serde_json’s map-ordering configuration.

logical_clock

A wall clock that never advances (always 0): the HLC’s degenerate pure-Lamport mode — B1’s stamp semantics, now produced by the same hybrid-clock code path.

system_clock

The real wall clock — the ONE place system time enters this crate, and only ever by explicit caller opt-in.

verify_log

Verify a log’s integrity and order: every id recomputes, and every device’s ops form a contiguous, prev-linked, HLC-monotone chain from the first op present for that device (a checkpointed log need not start at seq 0, but if seq 0 is present its prev must be None).

Type Aliases

WallClock

An injectable wall-clock reading (milliseconds since the Unix epoch).